.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.
#
# `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. The
# file stays out of this list anyway, because it is now MIXED: a driver that
# deferred it whole would resolve its still-hand-written prose by regenerating,
# which loses an edit rather than a merge. `check:migration-registry` is what
# guards the generated half instead.
#
# 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.
#
# 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.md`
# 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.

packages/spec/spec-changes.json                              merge=os-regen
packages/spec/liveness/state-counts.md                       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/export-origins/**                              merge=os-regen
packages/spec/api-surface-signatures.json                    merge=os-regen
docs/protocol-upgrade-guide.md                               merge=os-regen
docs/audits/2026-07-unknown-key-strictness-ledger.counts.md  merge=os-regen
content/docs/references/**                                   merge=os-regen