@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/docs/semantic-ingestion.md

@@ -0,0 +1,198 @@
+# Vanilla semantic proposal processor
+
+`src/ingestion/semantic.mjs` connects a host's extractor to Atelier's existing
+ingestion evidence reader. It produces qualified entity and assertion proposals
+and an evidence-revalidated searchable proposal view. The host chooses and
+invokes its extractor;
+this module has no provider selection, model call, subprocess, network client,
+runtime dependency, durable write, or graph mutation. Graphify, LightRAG, and Jev
+are optional host adapters and are not required for this processor.
+
+This is an internal first-consumer module. Its `atelier.semantic-candidate/v0`,
+`atelier.semantic-input/v0`, `atelier.semantic-proposals/v0`, and
+`atelier.semantic-proposal-view/v0` formats are not registered public contracts.
+There is no package subpath export or CLI command for them. Published v1 records
+and their closed extension fields remain unchanged.
+
+## Host flow
+
+1. Establish the existing permission to read the **whole ingestion plan** and
+   supply the current owner-adopted knowledge domain. `readScope: 'all-plan'` is
+   a reader precondition, not a permission granted by this module.
+2. Complete structural intake using the existing ingestion store. Select exact
+   evidence references from its completed attempts.
+3. Call `prepareSemanticInput({store, plan, domain, references,
+   identityCandidates})`. It reads each selected span using `store.getEvidence`
+   and pins the domain definition, source bytes, attempt, and locator.
+4. Invoke the chosen extractor with that input in the host. Include the returned
+   input digest in its candidate envelope. An extractor may be local,
+   deterministic, or model-backed; its permissions, budgets, retries, and
+   provider calls belong to the host.
+5. Call `prepareSemanticProposals({store, input, candidates})`. It rereads the
+   exact evidence, verifies the binding, and validates the candidate envelope.
+6. Use `readSemanticProposals({store, input, proposals, query, limit})` for a
+   fresh, literal search over assertions. It matches all whitespace-separated
+   query terms against endpoint IDs and labels, the predicate, the assertion's
+   own quotes, and its time expression. It excludes JSON field names, digests,
+   domain scope boilerplate and endpoint evidence from other assertions. It
+   verifies the same evidence and candidate binding before returning results.
+   Before serving a view the host must compare `domainRef` with its currently
+   adopted domain; this module checks the pinned snapshot, not an external
+   current-domain registry.
+7. Present the proposals to the existing knowledge evaluation and review owner.
+   That owner separately decides identity, semantic acceptance, activation, and
+   any permitted canonical projection. This module never performs those steps.
+
+An edit to an original source makes the earlier attempt stale. Intake and extract
+the changed source again, then create a new input and proposals. The module
+processes one source per input, so hosts can keep independent extraction caches
+and correction histories. It does not implement those caches or histories.
+Serving a saved proposal object without the fresh read does not revalidate it.
+
+## Input and candidate shape
+
+`plan` has exactly `planId` and `planDigest`. Each selected reference has exactly
+`sourceId`, `sourceDigest`, `attemptId`, and `locator: {kind, value}`. Locator kinds
+are the existing `line`, `csv-cell`, and `json-pointer` formats. Source digests
+are 64-character hexadecimal values; plan and input digests have a `sha256:`
+prefix. Evidence receipts must be current, verified, unsynthesized, and pending
+semantic acceptance, and must match every requested binding.
+
+The domain is an existing v1 knowledge `domain` or `domain-revision` record.
+Duplicate type or predicate IDs are refused. Identity candidates are optional
+host-supplied `{id, label, type}` proposals with unique IDs and vocabulary types.
+Their presence does not establish canonical identity or authenticate an owner.
+
+A candidate envelope has exactly:
+
+```js
+{
+  schema: SEMANTIC_CANDIDATE_VERSION,
+  inputDigest: input.digest,
+  entities: [{
+    id: 'nora', label: 'Nora', type: 'person',
+    identity: {status: 'source-local', candidateIds: []},
+    evidence: ['span-1'],
+  }],
+  assertions: [{
+    id: 'availability', subjectId: 'nora', predicate: 'available',
+    objectId: null, direction: 'subject-only', negated: true,
+    modality: 'asserted', scope: input.domain.data.scope,
+    time: {from: null, until: null, expression: 'Friday', unknowns: ['calendar-date']},
+    evidence: [{id: 'span-1', quote: 'Nora is not available on Friday.'}],
+  }],
+  unknowns: [],
+}
+```
+
+The example assumes `span-1` is that exact located source passage and the domain
+contains `person` and `available`. Candidate IDs use lowercase ASCII letters,
+digits, and hyphens, begin with a letter, and are at most 64 characters. IDs are
+unique across entities, assertions, and unknown findings. Labels never merge
+entities: two objects named Atlas can have different types and identities.
+
+Entity identity status is `source-local`, `existing-candidate`, or `unknown`.
+Only `existing-candidate` includes nonempty `candidateIds`; each must be a
+supplied candidate of the same type. Resolution remains pending even with one
+matching candidate.
+
+Binary assertions require two supplied entity IDs and `subject-to-object`.
+Unary assertions require `objectId: null` and `subject-only`. The predicate must
+belong to the domain vocabulary. Negation is a Boolean. Modality is `asserted`,
+`conditional`, `proposed`, `possible`, `uncertain`, or `unknown`. Scope must equal
+the supplied domain scope. Separate assertions between the same entities remain
+separate, including statements with different polarity or time.
+The vocabulary supplies IDs and meanings; it does not declare predicate arity
+or allowed endpoint types. The knowledge review owner checks those meanings.
+
+Time has exactly `from`, `until`, `expression`, and `unknowns`. Dates are nullable
+valid `YYYY-MM-DD` calendar dates, with an ordered interval when both are given.
+A temporal expression must occur in a cited quote. An unresolved expression such
+as Friday or through June requires explicit unknowns when neither boundary is
+resolved. Resolved dates without an expression are unanchored extractor
+interpretation; calendar validity alone does not provide a textual anchor.
+Quote matching establishes location; it does not establish that a
+date interpretation, predicate, polarity, or identity is semantically correct.
+
+Unknown findings have exactly `{id, relatedCandidateId, reason, evidence}`.
+The optional related ID refers to a supplied entity or assertion, or is null.
+The nonempty reason and supporting span IDs remain visible. An unmodeled
+predicate must be reported as a finding instead of an unsupported assertion.
+An assertion without evidence is refused; the caller can separately report a
+retrieval gap without presenting it as a supported assertion.
+
+## Results and refusals
+
+Proposals hydrate each support with the source ID, source digest, attempt ID,
+locator, relative source ref, and exact quote. They retain the original candidate
+envelope, pending identity and assertion acceptance, declared unknowns, input
+digest, and domain ref. The read model reports total assertion matches and omitted
+assertion matches when its limit truncates results. Entities and unknown findings
+are returned without filtering, to retain interpretation context. The view carries
+the pinned domain reference. It does not synthesize an answer.
+
+Every proposal and view declares `authority: 'none'`, `canonicalMutation: false`,
+`semanticAcceptance: 'pending'`, and `coverage: 'selected-spans-only'`.
+Counts report proposed entities, assertions, and explicit unknown findings
+(`abstentions`); successful validation reports zero refusals. A refused request
+throws `SemanticProposalError` with `refusalCount: 1` and a typed code:
+
+| Code | Boundary |
+| --- | --- |
+| `SEMANTIC_INVALID` | Closed, bounded plain JSON and valid query |
+| `SEMANTIC_PROFILE` | Existing domain definition and unique vocabulary |
+| `SEMANTIC_LIMIT` | Input, candidate, or result bounds |
+| `SEMANTIC_READ_SCOPE` | Whole-plan reader profile |
+| `SEMANTIC_EVIDENCE` | Available verified spans and literal quote support |
+| `SEMANTIC_STALE` | Existing reader reports a stale source or mismatched plan, digest, or attempt binding |
+| `SEMANTIC_BINDING` | Exact plan, source, attempt, locator, and input digest |
+| `SEMANTIC_IDENTITY` | Unique IDs, supplied identity mappings, and endpoints |
+| `SEMANTIC_TYPE` / `SEMANTIC_PREDICATE` | Declared vocabulary |
+| `SEMANTIC_DIRECTION` / `SEMANTIC_NEGATION` | Participant roles and Boolean polarity |
+| `SEMANTIC_MODALITY` / `SEMANTIC_SCOPE` | Declared qualification |
+| `SEMANTIC_TIME` / `SEMANTIC_UNKNOWN` | Retained time and explicit findings |
+
+The first failing rule refuses the entire request; there is no partial admission.
+There are at most 64 references, identity candidates, entities, assertions, or
+unknown findings per input, and at most 16 supporting spans per candidate.
+Identity alternatives and time unknowns also have a 16-item ceiling. Text limits
+are 8192 characters for labels, reasons, time expressions and time unknowns;
+256 for plan and attempt IDs; 16384 for locators and source refs; 65536 for
+quotes; and 512 for queries. Entity and unknown supports copy the full located
+span, so that span must also fit the 65536-character quote ceiling. Result
+limits must be safe integers between one and 64. Empty evidence selections
+are evidence errors; malformed collections and noninteger result limits retain
+shape errors rather than reporting capacity overflow.
+The existing ingestion plain-JSON bounds apply, including the 256 KiB payload
+limit, to caller inputs, assembled semantic inputs, hydrated proposals and read
+views. Hydration can exceed this limit even when raw candidates fit: entity
+supports include source span text and proposals retain raw candidates as well.
+Count, text-length, depth, member and byte overflow reports `SEMANTIC_LIMIT`;
+malformed JSON, invalid identifiers and invalid field shapes retain their typed
+validation codes. Oversized input or output is refused instead of silently
+truncated. This is a bounded evidence selection, not a complete-document
+extraction guarantee. It does not report coverage within the selection or list
+selected spans that no candidate cites; zero refusals is not a coverage score.
+
+## Qualification limits
+
+The tests exercise invented candidates, targeted mutation controls for the
+refusal scenarios represented in the test tables, successful pending identity
+mappings, direct receipt bindings, saved-proposal tampering, every declared
+collection
+bound, text/query/result limits, assembled and hydrated byte overflow, search
+exclusion and literal escaped characters, and the real local
+ingestion evidence reader. They check fidelity and refusal mechanics, including
+source correction. They do not qualify a semantic extractor, human review,
+permissions of an installed host, or economic benefit.
+
+This profile supports unary or binary entity-valued assertions and one domain
+scope string. It does not yet represent literal-valued assertions, structured
+per-assertion scope, attributed speakers, UTF-8 byte-range locators, or native
+engine graph projection. A richer adapter needs an explicitly reviewed mapping
+that retains those qualifications and reports projection omissions. A document
+graph's `related` edge must not replace a qualified real-world assertion.
+
+Graphify, LightRAG, and Jev integration must separately qualify their native
+capabilities, provenance mapping, optional configuration, lifecycle, and composed
+behavior. These tests make no quality, latency, token, or cost savings claim.

package/docs/semantic-operation.md

@@ -0,0 +1,317 @@
+# Semantic operation: internal vanilla profile
+
+`src/knowledge/semantic-operation.mjs` connects a host's extraction to the
+existing intake and knowledge owners. It is an internal library. There is no
+public export, registered schema or CLI command yet. The proposed consumer is
+an agent operating the experimental Atelier CLI after Foundation registers it.
+
+Atelier never invokes a model. The host supplies its raw output, its normalized
+candidate envelope, configuration pins and usage report. A deterministic or
+authored route explicitly declares that it automates no model extraction.
+Every receiver decision comes from the host's actual receiver session. The
+library checks consistency; it does not authenticate a person or grant source,
+model, publication or projection permission.
+
+## Owners and sequence
+
+Create the internal runner with `{workspaceRoot, workspaceId, run}`. The domain
+must already exist in the knowledge harness. All writes use its history digest
+through `appendHarness`; intake retains the original source and raw output.
+There is no second canonical ledger.
+
+1. Complete structural ingestion through the existing ingestion owner. Use
+   a separate one-source plan for each independent correction unit. The exact
+   reader checks the whole plan: editing another source in a shared plan also
+   invalidates that plan. Independent plans let unaffected operations reuse
+   their completed attempts without rebinding an old model response.
+2. Call `begin` before the host starts extraction. It reads current all-plan
+   evidence and the current ledger domain, pins the semantic input, records a
+   reservation in the existing ledger, then calls intake `beginAttempt`.
+   Only the new successful reservation returns `execution: 'ready-for-host'`.
+   A reopened begun, partial or reserved attempt has unknown execution.
+3. The host runs its extractor separately. Call `complete` with exact raw
+   output bytes, their SHA-256 digest, the normalized candidates and usage.
+   Raw output is retained even if candidate interpretation, plain-JSON bounds
+   or usage validation fails. Resume that
+   interpretation on the same attempt; never rerun extraction silently.
+4. Prepare the structural source contribution through
+   `prepareIngestionContribution`, retaining its real `extracted` origin and
+   source binding. The receiver evaluates and reviews that source.
+5. Call `prepareContribution` for each entity, assertion or unknown finding.
+   Entities are `concept` contributions, assertions are `claim` contributions.
+   Their author identifies the host machine, and `origin.method: 'authored'`
+   explicitly means a machine-authored interpretation pending review.
+   Their bodies retain the complete qualified candidate, citations, raw attempt
+   pins, input digest and host-reported usage.
+6. Submit receiver `evaluation`, `review` and `activation` records through
+   `record`. Assertion endpoints require currently accepted entity records.
+   A source-local identity stays distinct. An existing or unknown identity
+   requires an explicit identity choice in the receiver's review basis.
+7. Call `prepareRelation` only after assertion acceptance. Qualified assertions
+   return an explicit projection omission. An eligible plain relation remains
+   pending until the receiver reviews it. Activate the accepted assertions and
+   permitted relations, then call `project`.
+8. Reopen with the same workspace and run. Use `proposals` for pending results
+   and `context` for accepted knowledge. Read both through the supported runner.
+9. Record a receiver withdrawal or a superseding source/identity contribution.
+   `cascade` performs idempotent relation cleanup after an assertion withdrawal.
+   Old projection activations refuse as soon as their support is ineligible,
+   including before cleanup. The receiver selects a new current activation.
+
+## Proposed experimental commands and request shapes
+
+Foundation owns command registration. The proposed group is
+`atelier knowledge semantic <operation>`, with one JSON stdin request (at most
+1 MiB), a caller-selected workspace and a run. These internal operation names
+and shapes are the proposed binding; they are not a shipped command contract.
+
+| Operation | Request fields |
+| --- | --- |
+| `begin` | `operationId`, `attemptId`, `at`, `term`, `plan: {planId, planDigest}`, `references`, `identityCandidates`, `extractor`, `confirm` |
+| `status` | `operationId` |
+| `reconcile` | `operationId`, `at`, `by`, `reason`, `outcome`, `confirm` |
+| `complete` | `operationId`, `output`, `expectedOutputDigest`, `candidates`, `usage`, `at`, `confirm` |
+| `proposals` | `operationId`, `query`, optional `limit` |
+| `prepareContribution` | `operationId`, `id`, `kind`, `candidateId`, `source` pointer, `sourceBinding`, `term`, `at`, `confirm`; optional exact `supersedes` and `revisionReason` |
+| `prepareRelation` | `assertion` pointer, `at`, `confirm` |
+| `record` | A complete receiver `record`, `confirm` |
+| `cascade` | Existing `withdrawalId`, `at`, `confirm` |
+| `context` | `query` |
+| `project` | `activationId`, `namespace` |
+
+`extractor` has exactly `id`, `version`, `route`, `model`, `promptDigest` and
+`parameters`. Routes are `model`, `deterministic` or `authored`; only the model
+route has a nonnull model ID. The configuration digest covers all these fields
+and the exact semantic input digest. Parameters and input remain bounded plain
+JSON. Byte, member and depth overflow reports `SEMANTIC_OPERATION_LIMIT`;
+malformed plain JSON reports `SEMANTIC_OPERATION_INVALID`. A pin records what the host declares; it is not a provider receipt.
+
+`usage` has exactly `inputTokens`, `outputTokens`, `cost`, `currency`,
+`elapsedMs` and `retries`. Unknown values are `null`, never zero. Counts are
+nonnegative safe integers; cost is nonnegative and currency is an explicit
+three-letter code or null. Usage is labelled host-reported. Record actual
+provider receipts separately when available.
+
+Reconciliation outcomes are `not-executed` or `failed-no-output`, with an
+explicit actor and reason. They are host declarations, not independently
+verified cleanup. A partial raw output must be completed on its original
+attempt. A completed capture cannot be abandoned to permit another execution.
+Matching completed source/configuration operations return a cache hit with the
+existing operation ID; they do not create the requested new attempt.
+
+An explicit identity review basis uses JSON shaped as:
+
+```json
+{
+  "schema": "atelier.semantic-identity-decision/v0",
+  "operationId": "example-operation",
+  "candidateId": "example-entity",
+  "resolution": {
+    "status": "existing",
+    "contribution": {"id": "accepted-entity", "digest": "sha256:..."}
+  }
+}
+```
+
+The existing contribution must be a supplied identity candidate of the matching
+type and currently accepted. An explicit `resolution: {status: 'source-local'}`
+chooses the new contribution instead. A label never resolves identity by itself.
+An explicit contribution revision supersedes the latest interpretation for that
+operation and candidate, with a stated reason. It still needs fresh receiver
+evaluation, review and activation. Rebinding assertions to a revised entity
+reuses the immutable raw capture; it does not re-execute extraction. Changing
+the extracted candidate itself requires a separately declared interpretation
+route and capture, rather than rewriting the recorded model output.
+
+## Citations, witnesses and supported representation
+
+The profile is `atelier.semantic-operation-profile/v0`. It retains the semantic
+candidate's binary or unary participants, direction, negation, six modalities,
+domain scope, full time qualifications, unknowns and located quotes. Original
+quotes remain unchanged in the body and are revalidated against exact source
+evidence. See [semantic ingestion](semantic-ingestion.md) for candidate bounds.
+
+The structural source body is JSON extraction output. Ledger `basedOn` quotes
+are limited to 8192 characters, with unique contribution IDs. Each dependency
+therefore gets one labelled witness: the JSON-string encoding of its first
+cited quote, without outer quotation marks, cut only at complete code points
+and escape sequences. It must occur in the stored contribution body. Endpoint
+dependencies use encoded candidate IDs when present in the entity body, or a
+bounded actual text substring for an ordinary accepted concept. Its record ID
+need not occur in its body. A body with no representable witness is refused.
+The body labels `sourceWitness` entries
+with `encoding: 'json-string-substring'` and `purpose: 'ledger-dependency-only'`.
+Display citations from the candidate, never the dependency witness.
+
+The witness helper can form distinct source dependencies, but this operation
+profile processes one source per semantic input. It refuses missing or
+ambiguous current structural sources, attempt/digest mismatch, absent witnesses
+and more than 64 source-plus-endpoint dependencies with
+`SEMANTIC_UNSUPPORTED_LEDGER_CITATION` (`unsupported-ledger-citation`). It
+retains all cited spans in the candidate even when they share one dependency.
+
+UTF-8 byte-range locators, multiline quotes, structured per-assertion scope,
+literal-valued objects and speaker attribution are outside this profile.
+The runner returns named `SEMANTIC_UNSUPPORTED_LOCATOR`,
+`SEMANTIC_UNSUPPORTED_SCOPE` and `SEMANTIC_UNSUPPORTED_LITERAL_OBJECT` refusals
+for these richer locator, scope and object forms. Richer forms require an
+owner-reviewed mapping. They must be refused or retained
+as explicit unknowns by the host, rather than dropped or coerced into entities
+or edges. Canonical identity resolution stays in explicit receiver reviews.
+
+## Projection and freshness
+
+Only a binary `subject-to-object` assertion with `negated: false`,
+`modality: 'asserted'`, the domain scope, and no time boundaries, expression or
+unknowns can become a plain relation. Every other assertion remains a qualified
+contribution and appears in `projectionOmissions`.
+
+The relation ID is derived from its assertion contribution ID. Its rationale
+ends with `semantic-support: <assertionId> <sha256:digest>`. On every projection,
+that assertion must exist at the exact digest, be currently accepted and active,
+and be neither stale, withdrawn nor superseded. Relation participants must match
+the assertion. An ineligible relation refuses the whole activation; it is never
+silently filtered out. This guard is required because harness v1 relations do
+not have a supporting-assertion dependency field.
+
+`project` calls the existing `knowledgeGraphProposal` only after this check. Its
+document graph stays a document graph; typed `semanticEntities` and
+`semanticAssertions` retain the interpretation and qualifications separately.
+Calling the ordinary graph projector directly does not implement this semantic
+support profile. Neither projection applies canonical graph mutations.
+
+When a freshness or concurrent-history check fails after an interpretation write,
+the error carries `recorded: {record, head, nextAction: 'reopen-recorded-write'}`.
+Reopen that saved record; do not blindly repeat the write. A completed raw attempt
+always stays immutable, including a refused interpretation.
+
+Within one synchronous runner call, repeated validation can reuse one verified
+ledger snapshot and raw capture. Sources and ledger history are rechecked before
+returning. This cache is discarded after the call. Subsequent calls reread
+current state. Edited originals make earlier operations stale; a new structural
+plan and extraction are required. Unaffected independent plans reuse their
+completed raw attempts. History remains intact.
+
+`proposals` declares `answerClass: 'pending-proposals'`; `context` declares
+`answerClass: 'accepted-knowledge'` and does not synthesize an answer. Accepted
+source material is evidence, not automatic acceptance of every statement in it.
+A host-generated derived answer is a separate host artifact with explicit
+support and limitations; this runner neither creates nor admits such answers.
+
+## Qualification and optional tools
+
+Tests use invented sources and simulated receiver decisions. They establish
+mechanics, not model quality, authenticated human acceptance or economic benefit.
+Durable intake execution uses the qualified POSIX profile; portable stateless
+eligibility and witness tests run on Windows as well.
+
+This runner needs none of Graphify, LightRAG or Jev. It has no native adapter
+binding yet. Their implementations and all eight presence profiles remain
+separate qualification work. A real receiver run through the installed command,
+saved-state readback, a correction repeat and an independent useful-task repeat
+are required before claiming completion. Measure cold ingestion, incremental
+correction and warm retrieval separately, retaining unknown cost and omissions.
+
+
+### Correction dependencies and captured-output refusals
+
+An assertion depends on each reviewed endpoint interpretation, including the
+receiver's explicit identity choice, as well as a distinct resolved canonical
+contribution. These dependency-only witnesses are labelled `identity-choice`
+and `resolved-identity`. Withdrawing, re-evaluating, superseding or changing the
+reviewed interpretation makes the affected assertion or its acceptance require
+reconsideration through the existing ledger. Unaffected accepted knowledge stays
+retrievable. Corrected interpretations reuse immutable raw capture.
+
+A ledger reservation owns its attempt identifier even before intake publication.
+After intake begins, the reservation must still be reserved at the returned
+history head before `ready-for-host` is returned. A refused saved reservation
+carries `recorded` with the actual record reference and the head returned by its
+successful append. This saved head is diagnostic; reopen with `status` to obtain
+the current history head before supplying confirmation for another write.
+
+Executed output is captured before source-freshness or interpretation checks.
+If the original or adopted domain changed, interpretation refuses as stale and
+carries `captured` with the actual intake completion. Its head identifies a
+successful append made by this call, or the history observed at call entry when
+no append returned. It is diagnostic and may be older than later history; it
+does not establish current custody or authority for another write. Reopen with
+`status` for the current head and the stored completion readback. Compare
+completion records canonically; their object key order is not a digest contract.
+`status` can reopen those exact bytes as complete while the semantic operation
+remains reserved and stale; it does not imply accepted interpretation or permit
+claiming the output was never executed. The existing completed-attempt guard
+still prevents abandonment, and identical-byte completion remains idempotent.
+
+Saved receipts survive whatever value a failure throws. After a write or capture
+has returned, the runner adds `recorded` or `captured` in place when the original
+object or function has writable data properties for those receipts, or can accept
+new properties. It preserves that object’s identity, `code` and message. Otherwise,
+including a primitive or an object with missing receipt properties that cannot be
+added, it throws `SemanticOperationError` with a generic message and the receipts
+as its own properties. The wrapper retains the original value as a non-enumerable
+`cause` and its original own-data `SEMANTIC_*` code, or uses
+`SEMANTIC_OPERATION_INTERRUPTED`. A write that failed before returning saved
+nothing and attaches nothing. Existing writable receipt properties retain their
+attributes, so `JSON.stringify(error)` can omit non-enumerable receipts. The
+wrapper’s non-enumerable `cause` is also omitted; an original error decorated in
+place retains its existing properties and their visibility. Read `recorded` and
+`captured` explicitly when reporting a failure. Neither `cause` nor property order
+is a serialization contract.
+
+The semantic projection also returns labelled `dependencyWitnesses`. The existing
+generic projector emits `evidences` claims for ledger dependencies; these are
+provenance/dependency proposals, not additional extracted domain assertions.
+Use `semanticAssertions` and their qualifiers for those assertions. Consequential
+withdrawal cleanup matches both the generated semantic relation identity and its
+exact supporting assertion digest, leaving ordinary support-like rationale text
+untouched.
+
+If a receiver re-accepts an immutable assertion after changing its endpoint
+identity choice, acceptance in the ledger alone does not restore semantic
+compatibility. Context reports the affected record in `diagnostics` and
+`reconsider`, withholds it and dependent records, and preserves unrelated
+accepted retrieval and projection. Its old body is never rewritten. An
+activation selecting the incompatible assertion refuses; an independent
+activation remains usable. Named semantic pin mismatches are withheld with record-specific diagnostics.
+Low-level IO/intake errors and unexpected history failures still refuse the
+request. The receiver must explicitly revise the assertion for the new choice.
+
+Reconciled reservations permit a fresh operation only after checking that their
+own intake has no partial or completed output. Intake IDs remain workspace-wide: a collision with
+another run refuses exact status readback rather than attributing that run's
+bytes to the old reservation. It does not prevent beginning with a new ID after
+explicit reconciliation. The runner does not add a workspace-wide reservation
+owner or claim atomic publication across intake and knowledge ledgers.
+
+Activation membership is recomputed against the merged reconsideration set.
+A mixed activation containing an incompatible assertion cannot activate its
+other members in context. A separate current activation can make those
+compatible members available again; retrieval and projection use the same
+activation eligibility.
+
+If an interrupted reserved operation discovers a different immutable intake
+manifest under its attempt ID, explicit `not-executed` reconciliation records a
+`foreign-manifest-before-readiness` recovery pin and the exact manifest digest.
+That conflicting manifest confirms this reservation did not publish a matching
+attempt or reach the supported host-readiness return. The host declaration
+remains labelled, not independently authenticated. Reconciled status reports
+`foreign-manifest` with its pin and never returns the other run's raw bytes. A
+fresh distinct attempt ID is required. Own partial or completed output remains
+ineligible for abandonment. Completion requires a present immutable manifest
+with the operation's exact pins before raw publication. An absent manifest
+refuses with `SEMANTIC_RECONCILE_REQUIRED`; a foreign manifest refuses with
+`SEMANTIC_OPERATION_INTEGRITY`. A manifest appearing after an absent read cannot
+receive the refused completion's bytes. The readiness return also requires the
+own attempt to remain `begun`, alongside the unchanged reservation phase/head.
+
+Reconciliation rechecks intake through its post-write status. If contradictory
+own partial or completed output was captured, status and a later fresh-execution
+request refuse with `SEMANTIC_RECONCILE_REQUIRED` and `captured` custody. The
+reconciliation failure also carries its saved `recorded` custody. Raw bytes and
+the original host declaration remain immutable; neither is called unexecuted
+or silently discarded. The intake owner's exact readback remains available.
+These current-read checks do not provide an atomic transaction across the two
+stores or independently prove a host's declaration. Hosts must serialize their
+completion and reconciliation decisions; the runner creates no automatic
+unreconciliation or new execution permission after a detected contradiction.

package/docs/skill-steward.md

@@ -1,5 +1,11 @@
 # Skill stewardship
 
+For publishing and governing multiple capability packages across repositories,
+use the [capability stewardship foundation](capability-stewardship.md). It adds
+explicit publisher identity, release pins, local ownership modes, host profiles
+and version-bound evidence. The catalog commands below retain their original
+contracts; use the new layer when a catalog has multiple independent sources.
+
 Atelier skill stewardship is a local, evidence-gated loop for keeping agent
 skills useful without turning every repeated request into permanent
 instructions. It separates four concerns that are easy to blur together: