statecraft.
Catalog/spec-spine

022-index-sharding

Per-unit shard storage (conflict-free committed registry + index)

Lifecycle approvedImplementation completeVerification unknownQualification unknown

The two committed artifacts (the spec registry and the codebase index) were each emitted as one file behind one global content-hash line with id-sorted arrays. Because every spec or package PR rewrites that one hash line, two PRs touching different units collide textually, and GitHub's server-side merge (the web button and the merge queue's speculative build) does not run the spec-020 merge driver, so the conflict surfaces there and the merge queue ejects sibling PRs. This spec shards both artifacts by authority unit: per-spec registry shards under spec-registry/by-spec/<id>.json, per-spec traceability shards under codebase-index/by-spec/<id>.json, and per-package inventory shards under codebase-index/by-package/<slug>.json, each carrying its own input hash. The global view (validation, orphans, untraced code, the aggregate content hash) is computed ON READ from the shard set rather than committed, so there is no shared file to conflict on. Two PRs touching different specs then write disjoint files and never conflict, so the merge queue forms clean speculative stacks and auto-merge stops ejecting in-flight PRs. Staleness becomes per-shard (sharper than the broad hash), the committed shards stay present-on-clone, and a MAJOR schema bump (registry + index -> 1.0.0) marks the new on-disk shape. This generalizes spec 011 (index hash slices) from scoped staleness CHECKING to per-unit STORAGE, and it removes the textual-conflict cause spec 094's merge driver only papers over locally.

Read the full pinned specification ↗

Relationships

Claimed units

  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-core/src/shard.rs"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-types/schemas/codebase-index-spec-shard.schema.json"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-types/schemas/codebase-index-package-shard.schema.json"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-types/schemas/registry-spec-shard.schema.json"
}
  • extends
    {
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/index.rs"
  }
}
  • extends
    {
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/codebase.rs"
  }
}
  • extends
    {
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_index.rs"
  }
}
  • extends
    {
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/index.rs"
  }
}
  • extends
    {
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/compile.rs"
  }
}
  • extends
    {
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/registry.rs"
  }
}
  • extends
    {
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_compile.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/tests/cli.rs"
  }
}
  • extends
    {
  "spec": "002-registry-query",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_registry.rs"
  }
}
  • extends
    {
  "spec": "005-coupling-gate",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/couple.rs"
  }
}
  • extends
    {
  "spec": "005-coupling-gate",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_couple.rs"
  }
}
  • extends
    {
  "spec": "011-index-hash-slices",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/version.rs"
  }
}
  • extends
    {
  "spec": "011-index-hash-slices",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/schema.rs"
  }
}
  • extends
    {
  "spec": "011-index-hash-slices",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/tests/dtos.rs"
  }
}
  • extends
    {
  "spec": "011-index-hash-slices",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/conformance.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/lib.rs"
  }
}
  • extends
    {
  "spec": "010-index-render-orphans",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/render.rs"
  }
}
  • extends
    {
  "spec": "094-one-gate-and-the-boundaries-it-holds",
  "unit": {
    "kind": "file",
    "path": ".githooks/merge-derived-index.sh"
  }
}
  • extends
    {
  "spec": "094-one-gate-and-the-boundaries-it-holds",
  "unit": {
    "kind": "file",
    "path": ".githooks/enable-merge-driver.sh"
  }
}

Source headings

  1. 022: Per-unit shard storage
  2. 1. Purpose
  3. 2. Territory
  4. 3. The shard model
  5. 4. Behavior (MUST / SHOULD)
  6. 5. Staleness fidelity (a deliberate, bounded trade)
  7. 6. Migration
  8. 7. Relationship to the merge queue (complement, not replacement)
  9. 8. Out of scope
  10. 9. Acceptance criteria

Frozen anchors

No frozen anchors declared.