feat(client): add offline semantic release admission contract

.github/workflows/product.yml

@@ -63,7 +63,7 @@ jobs:
       - name: Exact owned coverage
         run: ./scripts/check_coverage.sh
 
-      - name: Validate public JSON contract
+      - name: Validate public JSON contracts
         run: |
           npx --yes ajv-cli@5.0.0 compile \
             --spec=draft2020 \
@@ -88,12 +88,69 @@ jobs:
             -s contracts/semantic-candidate.schema.json \
             -d contracts/fixtures/semantic-candidate.invalid-state-truth-mismatch.json \
             --invalid
+          npx --yes ajv-cli@5.0.0 compile \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json \
+            -d contracts/fixtures/semantic-release.valid.json \
+            --valid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json \
+            -d contracts/fixtures/semantic-release.invalid-published-truth.json \
+            --invalid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json \
+            -d contracts/fixtures/semantic-release.invalid-duplicate-concept.json \
+            --invalid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json \
+            -d contracts/fixtures/semantic-release.invalid-digest.json \
+            --invalid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release.schema.json \
+            -d contracts/fixtures/semantic-release.invalid-uppercase-digest.json \
+            --invalid
+          npx --yes ajv-cli@5.0.0 compile \
+            --spec=draft2020 \
+            -s contracts/semantic-release-supersession.schema.json
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release-supersession.schema.json \
+            -d contracts/fixtures/semantic-release-supersession.valid.json \
+            --valid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release-supersession.schema.json \
+            -d contracts/fixtures/semantic-release-supersession.invalid-digest.json \
+            --invalid
+          npx --yes ajv-cli@5.0.0 test \
+            --spec=draft2020 \
+            -s contracts/semantic-release-supersession.schema.json \
+            -d contracts/fixtures/semantic-release-supersession.invalid-rationale.json \
+            --invalid
+          python3 scripts/validate_semantic_release_supersession.py \
+            contracts/fixtures/semantic-release-supersession.valid.json
+          if python3 scripts/validate_semantic_release_supersession.py \
+            contracts/fixtures/semantic-release-supersession.invalid-self.json; then
+            echo "::error::self-supersession fixture unexpectedly passed semantic validation"
+            exit 1
+          fi
 
       - name: Lockfile freshness
         run: |
           cargo generate-lockfile --locked
           git ls-files --error-unmatch Cargo.lock >/dev/null
-          test -z "$(git status --porcelain=v1 --untracked-files=all -- Cargo.lock)"
+          if ! test -z "$(git status --porcelain=v1 --untracked-files=all -- Cargo.lock)"; then
+            echo "::error::Cargo.lock changed while validating the declared dependency graph"
+            git diff -- Cargo.lock
+            exit 1
+          fi
 
       - name: Clean working tree
         run: test -z "$(git status --porcelain=v1 --untracked-files=all)"

ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Product responsibility
 
-ConceptWeave owns the process that turns observed enterprise evidence into governed semantic-model releases. It does not own source-system truth or downstream catalog/query experiences.
+ConceptWeave owns the process that turns observed enterprise evidence into governed semantic-model releases and the stable client contract used to inspect those releases. It does not own source-system truth, consuming-product authorization, physical query execution, or downstream catalog/search experiences.
 
 ```mermaid
 flowchart LR
@@ -11,13 +11,15 @@ flowchart LR
     D --> V[Model Validation]
     V --> G[Governance & Publication]
     G --> P[Versioned semantic release]
+    P --> C[Client Consumption]
 
-    CO[contextual-orchestrator] -. proposal assistance .-> D
+    CO[contextual-orchestrator] -. proposal or optional alignment assistance .-> D
+    CO -. optional bounded matching assistance .-> C
     LW[LineageWeave] -. inferred/proposed lineage .-> O
     CG[context-graph-contracts] -. shared graph/provenance contracts .-> P
-    P --> SDP[semantic-data-portal]
-    P --> GRC[governance-risk-compliance]
-    P --> EA[enterprise-architecture-core]
+    C --> SDP[semantic-data-portal]
+    C --> GRC[governance-risk-compliance]
+    C --> EA[enterprise-architecture-core]
 ```
 
 ## DDD context map
@@ -27,51 +29,74 @@ flowchart LR
 | Source Observation | Supporting | immutable observations, parser receipts, evidence locations | source-system business truth |
 | Semantic Discovery | Core | candidate generation and evidence binding | publication authority |
 | Model Validation | Supporting | deterministic validation reports | human review decisions |
-| Governance & Publication | Core | proposal lifecycle, review receipts, releases, supersession | catalog/search runtime |
+| Governance & Publication | Core | proposal lifecycle, review receipts, releases, supersession authority | catalog/search runtime |
+| Client Consumption | Supporting | release admission, compatibility, exact byte verification, diff/resolution, explicit immutable supersession validation, future match/query-plan contracts | generator internals, consumer authorization, publication authority, physical query execution |
 | Interoperability | Supporting | versioned import/export and ACL adapters | foreign product internals |
 
-## Aggregate boundaries
+The generation-to-client dependency crosses only versioned public release contracts. Client code may reuse public domain value types, but it must not import generator-private adapters, prompts, persistence tables, Source Observation internals, or orchestration state.
+
+## Aggregate and value-object boundaries
 
 ### SemanticCandidate
 
 Smallest consistency boundary for a single proposed semantic artifact and its evidence-bound publication state. It cannot jump directly from Draft to Published.
 
-### SemanticModelRelease (planned)
+### SemanticModelRelease
+
+Planned Governance & Publication aggregate for immutable publication. The current Client slice defines only the consumer-visible release contract: stable release identity, contract and ontology versions, truth/publication state, declared artifact digest identity, provenance references, and stable concept identifiers. Release construction is not publication authority.
+
+### ReleaseDigest
+
+Client value object for a declared canonical `sha256:<64 lowercase hex>` digest identity. It validates digest syntax only. Exact detached artifact bytes must be hashed and compared before integrity is claimed.
+
+### SemanticReleaseReference
 
-Immutable publication aggregate containing approved candidate identities, release version, artifact digests, validation receipts, reviewer receipts, and supersession metadata. It will reference candidates rather than copy foreign source records.
+Client value object that binds a stable semantic-release id to its exact artifact digest. It is an immutable coordinate for published release identity and avoids treating a mutable name or version number alone as sufficient supersession evidence.
+
+### ReleaseSupersession
+
+Client-visible immutable declaration naming an exact predecessor reference, exact successor reference, and nonblank rationale. It rejects self-supersession. Client validation requires both releases to pass normal Published + Authoritative compatibility admission and both id+digest references to match exactly. The declaration does not mutate either release and never infers replacement from version ordering, timestamps, diff size, or semantic similarity. Governance & Publication remains the authority that creates the eventual publication/supersession receipt; the Client only validates the consumer-visible contract.
+
+### SemanticReleaseClient
+
+A stateless domain service in Client Consumption. Its compatibility policy has one explicit current contract version and an explicit set of supported legacy versions; it never infers compatibility from semantic-version ordering. Unknown versions fail closed. Current and supported-legacy releases pass the same `Published` plus `Authoritative` gate before resolution, diff, artifact verification, or supersession validation. It performs no network, LLM, database, tenant-authorization, publication-decision, or physical-query work.
 
 ## Truth model
 
 - `observed`: exact source fact;
 - `inferred`: derived candidate;
 - `proposed`: submitted for governance;
 - `authoritative`: explicitly reviewed and published;
-- `superseded`: formerly authoritative and replaced;
+- `superseded`: formerly authoritative and replaced through explicit release evidence;
 - `rejected`: explicitly rejected.
 
-Truth status and publication workflow are distinct. A source observation can be authoritative in its source domain without making an inferred semantic interpretation authoritative.
+Truth status and publication workflow are distinct. A source observation can be authoritative in its source domain without making an inferred semantic interpretation authoritative. Client admission fails closed rather than coercing these states. Supersession preserves the immutable prior release rather than overwriting it.
 
 ## Integration boundaries
 
-- `contextual-orchestrator`: LLM/model routing only.
+- `contextual-orchestrator`: all production LLM/model routing; optional future matching/explanation is still proposal evidence.
 - `LineageWeave`: inferred/proposed lineage evidence only.
 - `semantic-data-portal`: published semantic artifact consumer/governance/catalog plane; it is not ConceptWeave's internal database.
 - `context-graph-contracts`: shared cross-product identifiers, truth/provenance/event contracts where adopted.
 - Keyverse: future identity/tenant authentication boundary.
+- Consuming products: retain tenant/purpose authorization, business-domain truth, and physical data/query execution behind their own ACLs.
 
 No direct cross-service application-table SQL is permitted.
 
-## Foundation directory structure
+## Current directory structure
 
 ```text
 crates/
-  conceptweave-domain/       # Core domain contract only
-contracts/                   # Versioned public schemas
+  conceptweave-domain/       # Core candidate/evidence lifecycle contracts
+  conceptweave-client/       # Offline release admission, compatibility, integrity and supersession validation
+contracts/                   # Versioned public JSON Schemas and fixtures
 docs/
-  adr/                       # Binding architecture decisions
+  adr/                       # Proposed/accepted architecture decisions
   doctoring/                 # Standards/research evidence
 scripts/                     # Deterministic repository-quality helpers
 .github/workflows/           # CI evidence
 ```
 
 Adapters and application services are added only when their bounded responsibility exists; generic `utils`, `helpers`, or `services` dumping grounds are prohibited.
+
+ADR 0005 remains Proposed while PR #5 is Draft and current-head checks/governance are incomplete; implementation on an unintegrated head is not sufficient to mark the architecture decision Accepted.

CHANGELOG.md

@@ -10,9 +10,22 @@ All notable changes to ConceptWeave are documented here.
 - Rust 1.98.0 `conceptweave-domain` foundation with evidence-bound semantic candidate contracts.
 - Fail-closed Draft -> Proposed -> Validated -> Reviewed -> Published lifecycle with explicit rejection and supersession.
 - Draft 2020-12 JSON Schema for the semantic-candidate public contract.
-- Standards and research doctoring covering stable W3C ontology standards, 2026 RDF/SHACL work in progress, Apache Ossie, and recent LLM ontology-engineering research.
+- Rust-first `conceptweave-client` supporting subdomain with deterministic offline semantic-release admission by contract version, publication state, truth status, provenance, stable concept identity, and declared SHA-256 digest identity.
+- Deterministic offline semantic-release diff that first applies the same authoritative-use admission policy, then reports stable previous/current release identity and sorted added/removed concept identifiers without network or model calls.
+- Exact offline SHA-256 verification of caller-supplied detached immutable semantic-artifact bytes through `verify_detached_artifact`, with typed digest-mismatch evidence and the same fail-closed authoritative-use admission gate.
+- Explicit semantic-release compatibility policy that distinguishes the current contract version, caller-declared supported legacy versions, and unknown versions without inferring compatibility from version ordering; supported legacy releases still pass the same Published/Authoritative gate.
+- Explicit immutable semantic-release supersession references that bind predecessor and successor release ids to their exact artifact digests, require a rationale, reject self-supersession, and validate both releases through the ordinary authoritative-use gate without inferring replacement from version order or timestamps.
+- Draft 2020-12 `semantic-release` public JSON Schema with valid and fail-closed fixtures for non-authoritative publication, duplicate concept identifiers, and malformed digest identity.
+- Standards and research doctoring covering stable W3C ontology standards, 2026 RDF/SHACL work in progress, Apache Ossie, and recent LLM ontology-engineering/matching research.
+- Executable documentation/API contract preventing the retired `verify_serialized_artifact` name or manifest-self-digest semantics from drifting back into Client Consumption documentation.
 
 ### Security
 
 - Model-generated semantics remain non-authoritative until deterministic validation and authorized review.
-- Unsafe Rust is forbidden in the core domain crate.
+- Client authoritative-use admission rejects incompatible, unpublished, or non-authoritative releases without requiring a network/model call.
+- Legacy compatibility is explicit opt-in policy; unknown versions remain fail-closed and the current version cannot also be configured as legacy.
+- Release diff validates both compared releases through the same fail-closed authoritative-use gate so comparison cannot bypass contract-version, publication-state, or truth-status policy.
+- Detached-artifact integrity verification first applies authoritative-use admission, then computes SHA-256 over the exact supplied detached semantic-artifact bytes and rejects any mismatch with the declared release digest.
+- Digest syntax validation remains distinct from byte verification so a syntactically valid digest is never treated as proof that detached artifact content matches it.
+- Supersession validation requires exact predecessor/successor id-and-digest references and leaves the prior published release immutable; a correction is not inferred from ordering, timestamps, or semantic similarity.
+- Unsafe Rust is forbidden in the core domain and client crates.

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/conceptweave-domain"]
+members = ["crates/conceptweave-domain", "crates/conceptweave-client"]
 resolver = "2"
 
 [workspace.package]