.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.

packages/spec/spec-changes.json              merge=os-regen
packages/spec/authorable-surface.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
content/docs/references/**                   merge=os-regen