docs: align commit validation doc set ahead of implementation

[owleyeview]

Summary

Pre-implementation alignment of the commit-validation documentation set. Each settled design
decision now has one authoritative home; other documents summarize briefly and link.

Documentation only — no canonical TDL, generated JSON, or map-holons code is modified. Required
corpus and runtime changes are recorded as scheduled follow-up work.

Closes #29

Authority split

Concern	Authoritative document
Schema locality and ownership	schema-design-spec.md
Default-completion workflow	layered-desc-arch.md
Descriptor invariants	descriptor-semantics-rules.md
Validation layers and guarantees	validation-arch.md
Dependency-placement principle	dependency-gravity.md
Commit validation behavior	commit-validation-design-spec.md
Relationship write consistency	relationship-persistence-design-spec.md
Rule vocabulary and inventory	validation-schema-design-spec.md
Delivery sequencing	commit-validation-impl-plan.md

document-role-manifest.md records all nine.

Normative changes

Schema locality and aggregate validation. A Schema and every descriptor in its Components
collection are stewarded in one Space; semantic references may cross Schema and Space boundaries
without implying containment or a guaranteed remote inverse. Staging a descriptor schedules
validation of its owning Schema over prospective persisted-plus-staged components, even when the
Schema holon was not staged. Schema Modules are deferred and deliberately absent.

Default completion moves to the Shared Objects layer. core_shared_objects attempts
completion on create and independent clone once the governing descriptor resolves; an unavailable
descriptor is a non-fatal deferred outcome, not a construction failure. The loader pass is the
bootstrap backstop, every other producer must invoke the same operation, and Commit never supplies
defaults. Clone-time completion fills only omissions in the new staged clone. validation-arch.md
gains a Construction completeness guarantee (§3.2) distinct from peer admissibility and Commit
validity.

Outcome model. Four distinct types: CommitValidationViolation (one semantic finding),
CommitValidationReport (assessment plus derived decision), HolonError (only for failures that
prevented reliable assessment), and ValidationResult (reserved for future durable evidence).
Findings are dependency-safe and identity-only, live in core_types, and are stored on
StagedHolon separately from operational errors, replaced together with validation state after
each pass. StagedHolonWire in holons_boundary carries them across the wire; no bound runtime
reference crosses that boundary.

Commit as the public persistence gate. Internal node/entry persistence and SmartLink
operations consume prepared Commit plans rather than acting as parallel mutation APIs.
LocalHolonSpace bootstrap is the sole intended permanent exception. Commit responses gain
Rejected, RejectedHolons, the report projection, and a report-derived violation count, keeping
rejection, explicit abandonment, and operational failure distinct.

Constraints and blocking policy. Constraints are intrinsic mandatory commitments evaluated
independently of whether any ValidationBindings occurrence exists; unsupported effective
constraints fail closed. All current rules and constraints are blocking at Error severity, and
DefaultSeverity, MinimumBlockingBehavior, and binding/profile policy metadata are removed from
the target model until a real non-blocking use case exists.

Local consistency vs. cross-cell coordination. relationship-persistence-design-spec.md now
owns authoritative Space-local buckets, paired declared/inverse preparation and persistence in one
normal-order zome call, and source-chain conflict reload/revalidation/retry. DHT reads are not a
serializable cross-cell snapshot: a rule needing multi-cell aggregate authority fails closed with
RelationshipCoordinationRequired rather than passing on an incomplete view. Cross-Space inverse
realization stays deferred and does not make a complete local forward commitment provisional.

Kernel and inventory. DS-SCHEMA-003 is exclusively a kernel invariant enforced by exhaustive
unit tests — no ValidationRule, binding, or registry dispatch. The rule inventory is reconciled
against canonical TDL: 50 seeded instances, five marked for removal, 45 target. DS-CARD-001 is
the stable finding identity for cardinality; EnumTokenNonRetroactivity stays unbound pending the
DS-ENUM-003 decision, with an indicated preference for an unconditional enum-variant lineage
rule.

dependency-gravity.md is rewritten (930 → 148 lines) as the dependency-placement principle,
seven dependency classes, and a placement test — delegating layer inventory and rule semantics to
their owning specs, and replacing Nursery-as-a-layer with Commit.

Delivery sequence

commit-validation-impl-plan.md is restructured as VAL-PRE → VAL0 (landed, with follow-up) →
Capabilities 1–4 → Final Activation Milestone. Capability 1 produces a report and wire projection
but does not activate the production gate; that happens only at the milestone, once every
reachable constraint type and authored binding has a compatible handler and an extern/API
inventory (baselined against PR 623 and issue #622) shows convergence.

Recorded follow-up work

Not done here, tracked in the plan:

• VAL0 follow-up: remove DefaultSeverity, MinimumBlockingBehavior, and
  ValidationBlockingBehavior from schema-src/core/validation.tdl; remove the five superseded
  rule instances; regenerate core/validation.json and update loader metrics fixtures.
• Capability 1: add Rejected and the RejectedHolons pair to schema-src/dance/schema.tdl
  (CommitResponse is a holon typed in the dance extension, not Core) and regenerate
  dance/schema.json.

Verification

• git diff --check clean; all relative links in changed files resolve.
• Rule inventory mechanically reconciled against schema-src/core/validation.tdl: 50 table rows ↔
  50 TDL instances, exact match both directions, 5 removals → 45 target.
• make build-core not run — mkdocs is not installed on this machine. Please run before merge.

[evomimic]

Review findings

I am requesting three changes before approval.

1. Preserve vertical, end-to-end delivery

The revised implementation plan makes Capabilities 1–4 integration/test-only and defers the public production Commit gate until a final activation milestone.

That conflicts with the vertical-slice direction for this work: each delivered capability should exercise the real Commit path end-to-end. Incremental activation remains safe because unsupported effective constraints and active bindings fail closed.

Please retain production Commit integration for the first delivered slice, then expand coverage capability by capability. The final milestone can verify complete coverage and remaining ingress convergence, but should not become the first point at which descriptor-aware validation reaches Commit.

2. Distinguish a MAP Space from a Holochain write authority

The relationship-persistence changes state that a Space-local bucket can be protected through a normal-order zome-call transaction and source-chain conflict retry.

That guarantee holds only where every write to the affected bucket is owned by one Holochain cell/source chain. A MAP Space is a stewardship and containment unit; it is not automatically one source-chain authority.

Please state the source-chain-authority condition explicitly, or phrase the immediate guarantee in terms of Commit-local authoritative buckets. Multi-cell aggregate authority should remain deferred behind RelationshipCoordinationRequired.

3. Make the persistence-extern inventory concrete and consistent with PR 623

PR 623 established that test-only functions must be absent from packaged production coordinator artifacts. The activation checklist should not create a broad *_for_test exemption category that could leave production exports unexamined.

Please inventory the actual remaining public production persistence externs and their call paths, including the asserted DeleteHolon gap. If an extern is intentionally temporary or exceptional, name it, scope it, and link its owning follow-up. Internal storage functions and test-only probe exports should remain outside the public production surface by construction.

Follow-up wording

The clarified Schema-containment direction is reflected correctly:

• A Schema and its Components are stewarded within one Space.
• The containment hierarchy is Space → Schema → Module → Type.
• Semantic references to descriptors outside that containment hierarchy do not imply co-location.
• Section 12.5 remains the correct policy for arbitrary cross-Space inverse realization.

The PR body says Schema Modules are deferred and deliberately absent. Deferring their implementation detail is fine, but the documentation should preserve the intended Space → Schema → Module → Type containment model rather than describe Modules as absent from the target architecture.