.gitattributes

# Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
#
# Merge semantics for generator-owned artifacts (#4675).
#
# These files are sorted arrays and append-only ledgers derived from source. When
# two PRs each add or drop a few lines the result is a set union — fully
# composable — but a three-way TEXT merge reports it as a conflict a human must
# resolve by hand. The correct resolution is always the same: discard both sides
# and re-run the generator.
#
# ⚠️ The driver is a LOCAL git facility, and that bounds what it can fix (#5837).
# The GitHub merge queue rebuilds each PR server-side, where no custom merge
# driver runs — so for the three hottest artifacts a driver could not stop the
# queue from evicting the second PR that touched them. Those three are now
# SHARDED, one file per category / entry point, so PRs touching different
# categories touch disjoint files and the queue has nothing to conflict on. They
# stay routed here as directories: the driver still owns a same-category
# collision, which is the residue sharding cannot remove.
#
# packages/spec/spec-changes.json LEFT this list at #22485, because it left git: the
# #22449 B′ ruling generates it at publish (`scripts/release-spec-changes.sh` writes
# it into the package before the tarball is packed), the pull request generates it
# in memory, and the file is gitignored. NOT_DRIVER_MANAGED records `gen:spec-changes`
# as untracked output. A branch that still carries a regenerated copy meets a
# modify/delete conflict when it merges main, and the deletion is the resolution:
# `git rm packages/spec/spec-changes.json`, then commit — git runs no merge driver on
# a modify/delete, so nothing is deferred and no marker is left.
#
# docs/protocol-upgrade-guide.md LEFT this list at #22483 because nothing generates
# it any more. It is a hand-written pointer stub naming the guide's public address,
# and `gen:upgrade-guide` writes the gitignored docs pages under
# content/docs/protocol-upgrade/ instead (NOT_DRIVER_MANAGED records that path). A
# route there was harmful, not idle: the driver kept OURS whole, and the pre-commit
# discharge then passed it, because `check:upgrade-guide` compares no committed
# copy — so a branch carrying a generated guide merged the stub away in silence.
# Unrouted, a merge made from a checkout that carries this file conflicts on the
# stub. ⚠️ git reads the route from the checkout DOING the merge, so a branch
# forked before #22483 still defers the guide on its first merge of main; the merged
# tree has no row to discharge it against, so the next commit and the push are
# refused instead of passed (measured on PR #22556 with the previous head as the
# control, both merge directions). Since #22485 that refusal names the path as
# UNROUTED and prints the remedy that settles it — compare it with the merged-in
# side, keep the right bytes, `node scripts/check-regen-pending.mjs --release PATH`.
#
# `merge=os-regen` hands those paths to `scripts/git-merge-regen.mjs`, which does
# NOT text-merge them. See that file for why it also does not regenerate them
# in place (git runs merge drivers BEFORE the sources are merged, so anything
# computed there describes a half-merged tree).
#
# The driver is registered per clone by `scripts/setup-git-hooks.mjs`, which
# `pnpm install` runs. A clone WITHOUT it registered falls back to git's default
# text merge — i.e. exactly today's behaviour — so committing this file cannot
# regress anyone.
#
# The single source of truth for this list is `scripts/regen-artifacts.mjs`;
# `node scripts/git-merge-regen.mjs --self-test` reconciles the two in both
# directions. Add a path there, not only here.
#
# Deliberately absent: docs-import-surface.baseline.json and
# dual-source-exports.baseline.json (shrink-only ratchets — recomputing can
# WIDEN them), variant-docs.json and the migrations/conversions registries
# (hand-written). Those conflicts are for a human. See NOT_DRIVER_MANAGED.
#
# The migrations registry is the interesting one since #7297: its three append
# tables now come from `packages/spec/src/migrations/entries/` (one file per
# entry, the `.changeset/*.md` shape), so the conflict two retirement cards used
# to have is gone at the SOURCE — different entries are different files. Since
# #22554 the registry itself is git-ignored and generated whole at install and
# build, so git never merges it; its hand-written prose lives in
# `registry.ts.template`, which is plain source and text-merges like any other.
#
# The strictness ledger's COUNTS file joined at #5107 — the ledger's numbers were
# the repo's hottest conflict surface and merged in the one way that hides: two
# batches each decrement a header by their own correct delta, the rows merge
# cleanly because they do not overlap, and the subtotal merges clean and WRONG
# (seven cases in one day). Note it is the counts file, not the ledger — the
# ledger's prose is hand-written and must never be resolved by regenerating.
# #20361 sharded it into `….counts/`, one file per source directory, and stopped
# committing its cross-directory totals — the same measured conflict as the
# liveness counts below, in the same driver-less server-side merge.
#
# The liveness state table's counts joined at #7377 for the same reason, one file
# over — 9 of its 30 rows had drifted from the gate before anyone re-ran the
# documented snippet. Same split and the same caveat: `liveness/state-counts/` is
# the numbers and is driver-managed; `liveness/README.md` is the Notes prose —
# hand-written measurement of how each type got where it is — and is NOT.
# Regenerating a Note would fabricate a verdict, which that README calls worse
# than a missing row.
#
# #20361 then SHARDED those counts, one file per governed type, and stopped
# committing a total: the single file's shared total row was rewritten by every
# liveness PR, so in the driver-less server-side merge any two of them conflicted
# and each landing left every other one `dirty`, with no CI run until a
# merge-and-regenerate round. The cure is the one the header above records for
# the three hottest artifacts; each gate sums its shards when it reads them.
#
# The elevation census page (`content/docs/permissions/system-context.mdx`) was
# routed here from #13646 to #22927 and is not any more: nothing on it is
# generated. It joined as a `file:line` anchor table whose correct merged values
# were on NEITHER side of a conflict, became a MIXED row when #14064 measured that
# a whole-side deferral dropped its hand-written prose (`mixed: 'line-anchors'`),
# lost its line numbers to `path#symbol` anchors at #15921, and lost its last
# generated half — the census totals — to #22927's ruling. It text-merges like
# its prose neighbours now. ⚠️ What still catches a merge that leaves it wrong is
# `scripts/check-system-context-census.mjs`, which re-derives the census from the
# tree on every PR in the required `Lint & Repo Gates` job: a read no row anchors,
# or an anchor that no longer resolves. The `mixed` field and its comparator stay
# for the next mixed artifact (scripts/regen-artifacts.mjs, scripts/git-merge-regen.mjs).

#
# #13731 enumerated this file's blind spot and closed it: `check:merge-driver` now
# also reconciles the GENERATORS. Every `gen:*` script in every workspace manifest
# (and the root) must be accounted for — named as a row's `gen` below, or carrying a
# recorded disposition in NOT_DRIVER_MANAGED. Until then the gate was green over an
# artifact that was in NEITHER list, which is how #13646 and #13335 were each found
# by hand, during a merge. Eleven generators were unaccounted; each now has one.
#
# The two rows added here are the ones whose answer was "route": the per-skill
# reference indexes (#13335) and the react-blocks contract (#14296 item 3 retired
# its second, JSON rendering — one artifact now, so one row). Their
# neighbours got the other answer for reasons recorded per path — the skill docs and
# the AI skills guide are MIXED (a spliced block in hand-written prose, so a deferral
# would launder the prose; #14064 added a THIRD answer for the mixed file whose
# generated half no hand merge can reach — see `mixed` in scripts/regen-artifacts.mjs
# — but "not routed" remains the first answer to reach for), the two per-package
# test-typecheck ledgers are shrink-only
# ratchets, the sdui lockstep record cannot be regenerated without an objectui
# checkout, and the openapi/sbom outputs are gitignored so git never merges them.
#
# ⚠️ The same LOCAL-facility bound applies to all three: routing removes hand-merge
# rounds, it does NOT protect them in the merge queue. What protects them is
# server-side — `check:skill-refs` and `check:react-blocks` run in `lint.yml` on
# `pull_request` and `merge_group` with no `paths:` filter, and both RE-DERIVE their
# artifact from source rather than reading it back, so they also catch the silent
# case where two branches' rows do not overlap and the text merge exits 0 describing
# neither side.

packages/spec/liveness/state-counts/**                       merge=os-regen
packages/spec/authorable-surface/**                          merge=os-regen
packages/spec/authorable-surface.base.json                   merge=os-regen
packages/spec/authorable-defaults/**                         merge=os-regen
packages/spec/json-schema.manifest/**                        merge=os-regen
packages/spec/api-surface/**                                 merge=os-regen
packages/spec/src/meta-spelling/meta-url-data.generated.ts   merge=os-regen
packages/spec/export-origins/**                              merge=os-regen
packages/spec/declaration-map/**                             merge=os-regen
packages/spec/api-surface-signatures.json                    merge=os-regen
docs/audits/2026-07-unknown-key-strictness-ledger.counts/**  merge=os-regen
content/docs/references/**                                   merge=os-regen
skills/*/references/_index.md                                merge=os-regen
skills/objectstack-ui/references/react-blocks.md             merge=os-regen
scripts/platform-object-tenancy-census.json                  merge=os-regen