git-ents.gitmain
⌘K
foforge

docs: single-owner rule ids and cross-references

commit 7b7c4d8
docs: single-owner rule ids and cross-references

Several requirements were stated normatively in more than one file, so a future edit to one could silently drift from its restatement. Make each rule single-owned and have the others cross-reference it.

trims: gate.adoc intro and receive.refstore-seam to cross-ref arch.refstore-read-cas-split trims: sync.local-advisory to cross-ref gate.advisory-local, keeping sync.inbox-routing as the sync-owned consequence moves: receive.loose-cas-discipline → arch.loose-cas-discipline (overview.adoc), development-plan.adoc citation updated trims: roots.composition to cross-ref arch.store-composition-root and arch.no-hosted-branch, keeping the four-seam enumeration and the honesty test

Joseph D. Carpinelli · 1 month ago
tree browse at HEAD · parents: 2f377f0 · comment on this commit

Reviews

No reviews of this commit yet — record a verdict below.

Start a review

verdict

docs/development-plan.adoc @@ -45,7 +45,7 @@ | Medium | sonnet | Read/CAS trait split per `arch.refstore-read-cas-split`; loose-ref impl - ports the CAS discipline from `pre-redo` (`receive.loose-cas-discipline`: + ports the CAS discipline from `pre-redo` (`arch.loose-cas-discipline`: no shelling to `git update-ref`). Fable reviews the trait before phase 2 consumes it.
docs/spec/gate.adoc @@ -1,8 +1,8 @@ == The Gate Verification is a pure function over ref-store reads: it MUST depend only on -the read half of the ref store, never on write access or on any state -outside `refs/meta/*`. +the read half of the `RefStore` seam (<<arch.refstore-read-cas-split>>), +never on write access or on any state outside `refs/meta/*`. The gate is the one admission judgment in the design; every mutation, human or machine, is admitted or refused by this same function (see <<receive.unit>>).
docs/spec/overview.adoc @@ -228,6 +228,14 @@ performs a write. -- +[role="requirement", id="arch.loose-cas-discipline"] +.Loose Ref CAS Discipline +-- +A loose-ref `RefStore` implementation MUST write refs through its own +compare-and-swap discipline and MUST NOT shell out to `git update-ref`, +so local mutations honor the same CAS guarantee hosted storage provides. +-- + The honesty test for these boundaries — a third single-node composition root constructible from library crates alone — is a deployment requirement and lives in `roots.adoc` as <<roots.honesty-test>>.
docs/spec/receive.adoc @@ -48,18 +48,11 @@ [role="requirement", id="receive.refstore-seam"] .RefStore Seam -- -The `RefStore` seam MUST expose reads and atomic multi-ref -compare-and-swap, with reads split into their own trait so a read-only -caller (<<gate.tip-signed>>) cannot depend on write access. +The `RefStore` seam `receive` is handed MUST satisfy the read/CAS split +specified in <<arch.refstore-read-cas-split>>. -- -[role="requirement", id="receive.loose-cas-discipline"] -.Loose Ref CAS Discipline --- -A loose-ref `RefStore` implementation MUST write refs through its own -compare-and-swap discipline and MUST NOT shell out to `git update-ref`, -so local mutations honor the same CAS guarantee hosted storage provides. --- +// moved: receive.loose-cas-discipline -> arch.loose-cas-discipline (overview.adoc) [role="requirement", id="receive.object-access"] .Object Access Via gitoxide
docs/spec/roots.adoc @@ -10,11 +10,11 @@ [role="requirement", id="roots.composition"] .Deployment Lives Only at the Root -- -The four seams (`RefStore`, the object store via `gix_object::Find` / -`Exists` / `Write`, `EventSink`, `Executor`) MUST be wired together only in -a composition root. -Library code outside a root MUST NOT select among implementations of -these seams. +A composition root is the sole place all four seams — `RefStore`, the +object store via `gix_object::Find` / `Exists` / `Write`, `EventSink`, +`Executor` — are wired together, applying <<arch.store-composition-root>> +and <<arch.no-hosted-branch>> across the full seam set, not just store +implementations. -- [role="requirement", id="roots.local"]
docs/spec/sync.adoc @@ -55,7 +55,7 @@ [role="requirement", id="sync.local-advisory"] .Local Store Accepts Regardless of Verdict -- -The local store MUST accept a write regardless of the gate's verdict; the -gate's advisory role (<<gate.advisory-local>>) governs annotation only, and -sync MUST NOT use a failing local verdict to block a local write. +Sync MUST honor the gate's advisory role locally (<<gate.advisory-local>>): +it MUST NOT use a failing local verdict to block a local write. +The rejection consequence sync owns instead is <<sync.inbox-routing>>. --