.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. `authorable-surface.json` alone is a 8k-line sorted
# array, so any two PRs landing near each other collide.
#
# `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 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.

packages/spec/spec-changes.json                              merge=os-regen
packages/spec/authorable-surface.json                        merge=os-regen
packages/spec/authorable-surface.base.json                   merge=os-regen
packages/spec/json-schema.manifest.json                      merge=os-regen
packages/spec/api-surface.json                               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