@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/docs/atelier-sync.md

@@ -0,0 +1,172 @@
+# Atelier Sync: Deliverable Zero
+
+Atelier Sync is the collaborator-facing name for the resident repository
+supervisor. Deliverable Zero is deliberately headless: it proves the Git,
+filesystem, state-machine, recovery, and user-authority boundaries before a
+tray shell or installer is allowed to make the product feel finished.
+
+This is repository mechanics, not MNSTRY runtime authority. A Git commit
+changes the enrolled repository. It does not mutate MNSTRY identity, consent,
+visibility, provisioning, commerce, sessions, audit, or any other managed
+runtime object.
+
+## Authority contract
+
+- Enrollment names exactly one repository. Atelier never scans a home folder.
+- One resolved absolute system Git executable, version, and executable digest
+  owns Git semantics for the enrollment. Every inherited `GIT_*` variable is
+  stripped from supervised Git calls before Atelier adds its small fixed
+  safety environment. Custom SSH transport belongs in the user's SSH config;
+  credentials continue through ordinary Git credential helpers. Git `2.40.0`
+  or newer is required so global and system attribute provenance is observable.
+- Every cycle observes the full repository. There is no watcher correctness
+  dependency in Deliverable Zero.
+- Fetch and fast-forward-only reconciliation are mechanical operations.
+- Commit creation is a two-phase, user-confirmed operation. Planning records
+  the head, branch, complete status digest, exact file paths, commit message,
+  reviewed blob/mode manifest, diff summary, and exact optional upstream push
+  identity. The push identity digest covers the single resolved, normalized,
+  credential-free execution destination; persisted display evidence likewise
+  strips authentication material, query strings, and fragments. Multiple push
+  URLs and `url.*.insteadOf`/`pushInsteadOf` rewrites are refused as ambiguous.
+  Every authoritative field is bound into the operation id.
+  Execution requires that exact id and refuses if the plan, repository,
+  staged bytes/modes, written tree, commit parent/message, or publish target
+  changed. A publish plan is refused while any earlier local commit remains
+  unpublished, and publication names the exact verified commit object rather
+  than a movable `HEAD` ref. Plans expire after 24 hours, are consumed by a
+  definitive execution attempt, and are held under resident file/count
+  ceilings. Expired, malformed, or oversized retained plan files are removed
+  under the repository lock before those ceilings are enforced; redirected
+  plan state remains a hard refusal.
+- A commit plan cannot absorb pre-existing staged work. It stages only literal,
+  explicitly reviewed paths.
+- Configured Atelier boundary policy is checked against the staged change set
+  before commit creation using the enrolled Git executable. When the enrolled project
+  operates a private-domain repository with a declared owner, actor verification is blocking even in
+  legacy-warning mode. The Sync path disables the boundary command's optional
+  network `gh api user` fallback and fails closed when local actor evidence is
+  insufficient. Commit history is provenance, not current-user identity, and
+  is not accepted as actor evidence on this path. Shared-only checks skip derived actor lookup, including ambient platform
+  identities. Invalid explicit selectors are still refused. Ownership is scoped
+  to configured repository names; it does not authenticate repository identity. Ordinary Git hooks still run; the resulting commit tree,
+  single parent, and message must equal the reviewed authority or the local
+  commit is rolled back and publication is refused.
+- Push is present only when the reviewed plan requested it, the branch had no
+  prior unpublished commits, and HEAD still names the exact verified commit.
+  Atelier re-resolves the single push URL immediately before publication and
+  pushes the exact commit object directly to that reviewed destination. Push is
+  never forced, never follows tags, and never recursively publishes submodule
+  refs. When fetch and push resolve to the same credential-free identity,
+  Atelier refreshes the exact remote-tracking branch and re-observes before it
+  reports `committed-and-published`. A distinct configured push URL is honored,
+  but remains an explicit attention state because it cannot prove the fetch
+  upstream synchronized. A failed push or post-push tracking refresh preserves
+  the local commit, creates one stable attention state, and returns a non-zero
+  command exit.
+- Semantic conflict resolution, merge commits, rebase, reset, force push,
+  browser apply, broad path scans, telemetry, and hidden upload are absent.
+
+## Repository completeness
+
+`atelier sync status` emits a supervisor envelope whose `state.observation`
+contains the current `atelier-repository-observation@v1` document. That
+observation cannot report `complete: true` when any of these are unresolved:
+
+- lexically identifiable provider-managed, UNC/network, WSL-cross-boundary, or
+  unclassified external filesystem roots (mapped-drive classification remains
+  an operating-system integration concern for the signed beta);
+- an unsupported Git engine or bare repository;
+- sparse checkout, partial clone, or shallow repository state;
+- tracked paths carrying `assume-unchanged` or `skip-worktree` index flags;
+- missing or unhealthy submodules;
+- required Git LFS content without a working LFS integration, including LFS
+  semantics declared by tracked or untracked worktree attributes, repository
+  info attributes, and default global or system attributes;
+- an unclassified custom clean, smudge, or process filter;
+- a configured `core.hooksPath` whose executable behavior is outside the
+  reviewed repository contract;
+- a remote URL whose authentication shape cannot be classified;
+- multiple push destinations or any configured Git URL rewrite rule;
+- any required Git evidence read that fails, times out, exceeds its budget, or
+  cannot be parsed.
+- a change set above the 4,096-entry resident observation ceiling; or
+- a `core.attributesFile` outside the repository-owned/tracked attributes
+  boundary whose filter semantics have not been classified.
+
+HTTPS through Git Credential Manager, SSH through the user's existing SSH
+configuration, and local test remotes are classified explicitly. Atelier does
+not collect or store provider credentials.
+
+## Local operation state
+
+Ignored `.atelier-local/runtime/` contains:
+
+- `enrollment.json` — exact repository and Git engine;
+- `state.json` — a bounded projection of healthy, attention, or paused state;
+- `control.json` — user pause/freeze state;
+- `plans/` — expiring, consumed reviewed commit plans under count/byte ceilings;
+- `operations.ndjson` — sequence- and hash-chained resident trace with explicit
+  hash-bound checkpoints before its byte or record ceiling, with a fresh
+  digest-linked generation after a torn or corrupt chain; and
+- an atomic per-repository operation lock.
+
+Every directory component is containment-checked and every state leaf is
+opened without following redirects where the platform supports it, with leaf
+type and identity checks on every platform. Stale-lock recovery uses an
+exclusive recovery claim, ages out an abandoned recovery claim after the owner
+grace interval, identity-checks the lock directory before and after quarantine,
+and quarantines only the claimed stale directory; it never recursively deletes
+a newly acquired lock. A live PID without durable process identity cannot wedge
+the repository forever: its owner record becomes recoverable after the 24-hour
+maximum operation age. Enrollment takes the same lock as every other
+authoritative state mutation.
+
+Deleting this directory removes convenience and diagnostics. It cannot change
+repository meaning. Git plus readable files remain authoritative.
+
+## Engineering commands
+
+```bash
+atelier sync enroll --repo /absolute/path/to/repository
+atelier sync status --repo /absolute/path/to/repository
+atelier sync reconcile --repo /absolute/path/to/repository
+atelier sync run --repo /absolute/path/to/repository --once
+
+atelier sync plan \
+  --repo /absolute/path/to/repository \
+  --path docs/decision.md \
+  --message "docs: record decision" \
+  --publish
+
+# Repeat the exact operation id printed by plan:
+atelier sync commit \
+  --repo /absolute/path/to/repository \
+  --operation operation-... \
+  --confirm operation-...
+```
+
+`status`, `audit`, `reconcile`, `run --once`, and `commit` return a non-zero
+process exit when their result is not healthy, so automation cannot treat a
+paused state, attention state, or failed publication as success merely because
+JSON was emitted.
+
+The future native shell may label the final two commands **Commit & sync**.
+It must not bypass either phase.
+
+The repeated operation id is a visible user-intent confirmation gate, not an
+authorization secret. Local software able to read and modify the repository is
+inside the same operating-system trust domain; the control prevents implicit
+or stale execution, not a hostile process with the user's filesystem access.
+
+## Evidence boundary
+
+Deliverable Zero proves the headless supervisor contract on Linux and macOS,
+with Windows CI covering the portable observation, state, and direct-process
+contract. POSIX executable-wrapper substitution is explicitly skipped on
+Windows; native Windows wrapper-injection proof, signed installation,
+background launch at user login, Windows Home/Pro device behavior, macOS
+notarization, and a nontechnical-user workflow belong to the signed
+collaborator beta. Repositories without an initial commit are not supported by
+this deliverable. A Git executable upgrade changes enrolled identity and
+requires re-enrollment.

package/docs/blocks/claims.md

@@ -1,24 +1,34 @@
 This package makes three promises. None of them asks for your trust — each
 one names the command that proves it.
 
-**Nothing leaves your machine, with one exception you can see.** There is no
-telemetry, no update check, no crash reporting, and no send path anywhere in
-the package. The exceptions are explicit: `boundary check` may invoke `gh api
-user` after no declared actor matches an explicit `--actor`,
-`MNSTRY_ATELIER_ACTOR`, `GITHUB_ACTOR`, or a configured Git email; repository
-identity checks may invoke `gh api repos/...` to resolve a canonical GitHub
-identity. Those authenticated requests use your own `gh` credentials. A
-recognized explicit actor prevents the boundary actor fallback; recorded
-repository identities let identity checks keep working when the provider is
-unavailable. The only network client
-refuses non-loopback URLs, the served pages carry a policy that authorizes no
-external origin, and release audit scans every executable or markup file in
-the exact `npm pack` inventory for egress primitives. The standalone gate also
-scans executable and markup files under `src/`, `bin/`, `scripts/`,
-`templates/`, `examples/`, and `skills/`. Two limits worth stating plainly:
-the egress control does not interpret data-only `.json` or `.md` files, and it
-does not model `child_process`; the two reviewed `gh` paths above are therefore
-documented exceptions rather than scanner detections:
+**There is no silent egress; every network path is named.** There is no
+telemetry, update check, crash reporting, or model provider path in the package.
+The optional vault API adds explicit host-bound artifact uploads and reads; it
+is never activated by local authoring commands. Its injected storage, database
+and identity SDKs may use the network and require separate hosted qualification. The exceptions are explicit: `boundary check` and
+`upgrade` (including `--dry-run` and `--apply`) may invoke `gh api user` only when
+an operated private-domain repository needs owner attribution, no explicit selector or `GITHUB_ACTOR` was supplied, and no
+configured Git email maps to an actor. Shared-only boundary checks skip derived
+identity lookup. Invalid explicit selectors are refused without fallback;
+platform logins must uniquely match declared login mappings. Repository identity
+checks may invoke `gh api repos/...` to resolve a canonical GitHub identity.
+Those authenticated requests use your own `gh` credentials. Recorded repository
+identities let identity checks keep working when the provider is unavailable.
+See `docs/install.md` for the full attribution precedence and mode semantics.
+Explicitly enrolled Atelier Sync may also run bounded Git fetches
+for observation/reconciliation and one non-force push only when the exact
+reviewed commit plan requested and confirmed it, no earlier local commit is
+waiting to be published, and HEAD still names the verified commit object. Sync
+never uses the network actor fallback, follows tags, or recursively publishes
+submodule refs. The local authoring HTTP client
+refuses non-loopback URLs, the served pages authorize no external origin, and
+release audit scans every executable or markup file in the exact `npm pack`
+inventory for egress primitives. The standalone gate also scans executable and
+markup files under `src/`, `bin/`, `scripts/`, `templates/`, `examples/`, and
+`skills/`. Two limits worth stating plainly: the egress control does not
+interpret data-only `.json` or `.md` files, and it does not model
+`child_process`; the reviewed `gh` and enrolled Git paths above are documented
+subprocess exceptions rather than scanner detections:
 
 ```bash
 npm run egress:check

package/docs/blocks/will-not-do.md

@@ -1,7 +1,16 @@
 - It does not write to a MNSTRY runtime database.
-- It does not import, provision, publish, or send anything.
-- Except for the documented `gh` actor-resolution fallback, it initiates no
-  external network requests.
+- It does not import, provision, publish, or send project content to a MNSTRY
+  managed runtime.
+- Conformance remains offline. Local CLI network access is limited to the documented
+  `gh` actor-resolution fallback and explicitly enrolled Atelier Sync Git
+  operations: bounded fetch for observation/reconciliation, and non-force push
+  only when the exact reviewed commit plan requested and confirmed it, no
+  earlier local commit remains unpublished, and HEAD still names the verified
+  commit object; Sync does not use network actor fallback, follow tags, or
+  recursively publish submodule refs.
+- Optional vault adapters use explicitly injected host SDKs and transports. The
+  host owns their network access, authentication and infrastructure; importing
+  the kit does not create a service or make a network request.
 - It does not execute model-assisted analysis or any model provider.
 - It does not include client project content.
 

package/docs/coauthor-session.md

@@ -0,0 +1,57 @@
+# Experimental portable coauthor session
+
+Tracked by issue #33. The experimental reducer is exported at
+`@mnstry/atelier/coauthor`; the private draft adapter at `@mnstry/atelier/coauthor/store`.
+The `atelier coauthor start|read|event|recover` CLI consumes one JSON request on
+stdin. Run it from the intended Git workspace; `.atelier-local/` must be ignored
+and untracked. The shipped `atelier-guided-coauthor` skill guides harness use.
+This local candidate has not been published or accepted by a real author.
+
+The harness supplies a session id and an ordered list of consumer-owned field
+ids, each bound to an immutable source reference and SHA-256 digest. The pure
+reducer accepts revision-bound events and returns a new state plus effects.
+It does not access files, render a browser, contact a model or authorize writes.
+
+An answer remains in history. Every proposed wording change requires explicit
+confirmation before saving. Answer-and-continue intent survives confirmation;
+advance occurs only after a matching receipt. Pause retains the current phase.
+Rejection restores the original answer. Undo of an already saved value is not
+implemented: consumers must not advertise it or delete history to simulate it.
+
+## Adapter obligations
+
+- Keep reducer state inside the trusted adapter; untrusted callers submit
+  intents, never snapshots or save receipts. Rehydrate from validated events
+  with `replaySession`, using the original immutable configuration.
+- Authenticate and authorize actors outside this module. Session identifiers
+  and matching digests are correlation data, not proof of identity or authority.
+- Persist accepted events through the existing consumer ledger. This module's
+  in-memory history is a replay projection, not a second durable database.
+- Before executing `write-field`, verify source identity and containment and
+  apply the consumer's compare-and-swap write policy. Key execution by session
+  id plus request id. Retry uses the same key; duplicate delivery must not
+  perform another write. Reconcile a pending write after a restart rather than
+  blindly replaying historical effects.
+- Emit a receipt only after durable persistence and readback of the exact
+  target field's UTF-8 value. The receipt binds session, request, field, source
+  reference, source digest and value digest. A digest match alone does not
+  establish that these adapter duties occurred.
+- A failure remains visible. One explicit retry is allowed; subsequent failures
+  require adapter reconciliation. A valid late receipt can resolve recovery.
+- Persist the accepted receipt event before showing saved state. This module
+  grants no canonical publication, release, remote execution or guide access.
+
+The supplied store reuses the collaboration ledger implementation, in a separate
+coauthor stream that is never mixed into legacy proposal aggregates. It verifies
+contiguous versions and previous-event identity; compaction that drops history
+is refused. It writes immutable private draft values, then replays a readback-bound
+receipt before showing saved state. It never edits selected source files.
+Workspace-local Git checks are the only subprocess use; no network is added.
+Operation locks serialize this adapter's writers. A leftover lock requires
+operator inspection, never automatic removal of an unknown writer's lock.
+
+`start` takes `{config: {id, fields}}`; `read` and `recover` take `{sessionId}`;
+`event` takes `{sessionId, event}`. A receipt or failure event submitted through
+the CLI is refused. Source changes block new writes, not reading old history.
+Configuration and saved drafts have the additive `atelier-coauthor.v1` schema;
+source path containment and duplicate fields are checked by the adapter as well.

package/docs/connected-composition.md

@@ -0,0 +1,75 @@
+# Connected composition: synthetic foundation
+
+Status: experimental, opt-in source prototype. Not an accepted public API,
+production auth integration, published release, or certification of a private
+host. Existing package exports and contracts remain unchanged.
+
+## Bounded implementation
+
+Owned additions: `src/composition/`, `src/access/`, `src/preview/`,
+`examples/connected-composition/`, `test/connected-composition*.test.mjs`, and
+`scripts/prove-connected-composition.mjs`. This document records the reservation.
+No existing sidecar, vault, coauthor, presentation, keyboard or business module
+is changed. The prototype starts from the frozen presentation supplier and is a
+separate candidate; its local proof cannot satisfy that supplier's CI gate.
+
+The public root supplies placement validation, an opt-in trusted-host enforcement
+helper and a two-origin preview channel. A private host supplies identity,
+membership, delegation, policy, registry/source resolution, services, result
+filtering and audit storage. Auth adapters can differ without changing placements.
+White-label and self-provisioned hosts remain possible; no hosting infrastructure
+or tenant provisioning is implemented here.
+
+The example uses two invented auth adapters and an in-memory collection service.
+It is intentionally not an auth provider. Only preview-plane synthetic reads and
+an explicitly enabled reversible sandbox action are supported. No production
+plane, live network transport, credential, payment or irreversible action exists.
+
+## Implementation sequence and acceptance
+
+1. Closed, byte/depth/count-bounded JSON parsing, placement and action schemas;
+   exact source-byte and immutable definition/renderer digests.
+2. Trusted channel authentication, complete decision binding, agent attenuation,
+   fail-closed revalidation before service and before output; bounded projection.
+3. Independent fake service authorization, expected-version/idempotency behavior,
+   with accurate uncertainty rather than invented rollback after an effect.
+4. Exact-origin/source/nonce MessageChannel handshake and generation/source/sequence
+   guards; old mounts and pending responses cleared on change or logout.
+5. An Astro page retaining useful static content without JavaScript or an account;
+   isolated dynamic preview, ordinary native controls, narrow responsive layout.
+6. Focused control tests, three desktop browser engines, source-edit/build/refresh,
+   fake adapter switch/logout, scoped agent refusal and no secret projection.
+
+The browser receives proposals and filtered results, never a trusted session,
+decision or service port. This separation protects against an untrusted preview,
+not a malicious host constructor. A real service must independently authorize
+and atomically own effect/version/idempotency receipts. Types and callback names
+are not security boundaries. A compromised private service or dishonest projector
+is outside this root helper's assurance.
+
+No general source writer is added. The browser does not get filesystem tools.
+The proof harness edits only its disposable authored fixture and rebuilds it.
+Existing coauthor draft persistence and canonical source promotion stay owned by
+their existing workflows. There is no duplicate placement database.
+
+## Proposal alignment
+
+The wire retains the `proposal-v1` discriminators from the reviewed placement
+proposal, with an executable closed action validator added. The implementation
+is `connected-composition/experimental-v1`, not a proposal acceptance event.
+An action's full request digest is additionally bound to authorization, so an
+identifier cannot silently stand for a changed payload. The projector returns
+only filtered data; the root constructs all public state metadata itself.
+Audit intake uses `pending` and output settlement uses `prepared`, not
+`delivered`: returning a prepared result is not a browser delivery acknowledgement.
+Preview lifecycle generations are mount-local and never serialize host session
+generation or identity. Real hosts must map invalidation into channel disposal.
+The first resolver intentionally admits exactly one data binding and a web
+projection. Multi-resource composition, other host projections and a published
+package export require their own accepted contracts; parsing their proposed
+shape alone is not runtime admission.
+
+Missing completion gates: owner validation of real host adapters and source
+promotion integration, service-specific transaction/reconciliation proof,
+assistive-technology and actual native/device tests, private adopter acceptance,
+maintainer integration and recognized CI. None is implied by this prototype.

package/docs/decisions.md

@@ -0,0 +1,167 @@
+# Typed decision proposals
+
+The optional `@mnstry/atelier/decisions` API validates finite questions and
+their proposed answers. It performs no provider calls, credential lookup,
+source mutation, or acceptance. A consuming host supplies the provider and
+independently checks authorization before disclosure or use.
+
+For a development pilot, pin the reviewed source commit or its verified
+tarball. Check that the installed package exports `./decisions`; an older
+published alpha may not contain this API. A source merge does not publish a
+new registry version.
+
+This API is suitable for a small, explicit choice, an ordered score, or a
+Boolean probability. It does not extract missing evidence or generate prose.
+The fixtures describe an invented reading room; their answers and usage are
+synthetic examples, not model evaluation results.
+
+```js
+import {
+  decisionRequestDigest,
+  validateDecisionRequest,
+  validateDecisionResult,
+} from '@mnstry/atelier/decisions'
+
+const requestCheck = validateDecisionRequest(request)
+if (!requestCheck.ok) throw new Error('Invalid decision request')
+const digest = decisionRequestDigest(request)
+
+// The host obtains a result under its own provider and disclosure policy.
+const resultCheck = validateDecisionResult(request, result)
+if (!resultCheck.ok) throw new Error('Invalid decision result')
+```
+
+The adjacent TypeScript declarations export `DecisionRequest`,
+`DecisionQuestion`, `DecisionResult`, `DecisionAnswer`, `DecisionScope`,
+`DecisionUsage`, and `DecisionValidation`, including the individual question
+and answer variants. Runtime validation remains required for external data.
+
+For hosts that need only question and answer validation, use
+`validateDecisionAnswers(questions, answers)`. It checks bounded plain JSON,
+question structure, exact answer keys and types, probability distributions,
+and score expectations. It accepts no state, computes no hash, performs no
+provider execution, and writes nothing. The host supplies its own transient
+request binding and enforces its privacy policy.
+
+```js
+import { validateDecisionAnswers } from '@mnstry/atelier/decisions'
+
+const answerCheck = validateDecisionAnswers(questions, answers)
+if (!answerCheck.ok) throw new Error('Invalid decision answers')
+```
+
+This separate API checks evidence reference syntax, uniqueness and bounds,
+but cannot establish membership in a source snapshot that it has not received.
+The request and result validators still enforce that membership. A successful
+answer check establishes neither authorization nor semantic correctness.
+
+## Requests
+
+`atelier-decision-request@v1` records a request ID, task, rubric version,
+host-reported scope, state, evidence references, and questions. The
+`scope.workspaceId` and `scope.authorizationRef` fields bind the assessment to
+the host's reported snapshot. They do not authenticate a caller, prove
+consent, or grant access. The host must revalidate current permissions and
+revocation before sending data or acting on a cached result.
+
+Each question includes instructions and at least one `evidenceIds` entry
+referring to the request's evidence. Evidence identities are unique; their
+`sourceRef` strings are opaque references preserved for the host. Validation
+does not fetch them or prove that the state faithfully represents a source.
+
+| Question | Criteria | Answer |
+| --- | --- | --- |
+| `choice` | A map of 2–64 option IDs to descriptions | A selected option, complete probability map, and provider confidence statistic |
+| `score` | An ordered list of 2–10 descriptions | A zero-index weighted expectation, complete probability list, and provider confidence statistic |
+| `boolean` | Explicit `true` and `false` descriptions | A probability between zero and one |
+
+Identifiers are 1–128 ASCII characters, beginning with a letter or digit and
+continuing with letters, digits, `.`, `_`, `:`, or `-`. The names `__proto__`,
+`constructor`, and `prototype` are refused as object keys and identifiers.
+State and descriptions support Unicode; validation does not normalize text.
+
+Requests are limited to 64 questions, 256 evidence entries, 32,000 state
+characters, 4,000 instruction characters per question, 2,000 characters per
+criterion, and 2,048 characters per source reference. String limits count
+Unicode code points. Empty state is allowed so the host can record an
+insufficient-evidence abstention; instructions and descriptions must contain
+non-whitespace text.
+
+## Results and integrity
+
+`atelier-decision-result@v1` copies the request ID, task, rubric version and
+scope, and carries `requestDigest`, provider ID, concrete model name,
+elapsed milliseconds, and usage. Token counts are nonnegative safe integers;
+`usage: null` records unavailable usage without treating it as zero.
+
+`authority` is always `proposal-only`. `mode` is `shadow` or `advisory`;
+neither value grants execution authority. An `assessed` result contains
+exactly the requested answer keys and types. An `abstained` result contains
+an empty answer map and one explicit reason: `insufficient-evidence`,
+`ambiguous`, `no-match`, `budget-exhausted`, `provider-unavailable`, `timeout`,
+`invalid-response`, or `unauthorized`.
+
+The validator checks that distributions sum to one within `1e-6`, a chosen
+option has maximum probability, and a score equals its zero-index weighted
+expectation within `1e-6`. Tied maximum choices are valid. Boolean answers
+have no confidence field. Confidence is a provider statistic, not measured
+semantic correctness; a structurally valid high-confidence answer can still
+be wrong. The host owns evaluation data, calibrated thresholds, escalation,
+and fallback behavior. The host must also compare the recorded model with
+its requested concrete model pin; the request contract does not prescribe a
+provider or model.
+
+`decisionRequestDigest` returns lowercase SHA-256 over canonical JSON with
+object keys recursively sorted in JavaScript string order. Array order and
+exact Unicode content are retained. It includes the full request, scope,
+evidence, rubric, and optional extensions. Reordering object insertion does
+not change the digest; changing any represented value does. This is local
+integrity evidence, not a signature or proof of provenance. Invalid requests
+throw a generic `TypeError`; validators return `{ ok, errors }` without
+echoing source text, unknown field names, or provider response content.
+
+Content hashes can themselves be sensitive. A host whose policy forbids
+hashing a passage must use its own transient request binding instead of this
+digest-bearing envelope. It can reuse the question and answer types without
+calling `decisionRequestDigest` or retaining a full request. The public
+contract does not override the host's privacy policy.
+
+## Closed fields and extensions
+
+The standalone JSON Schemas are
+`atelier-decision-request.v1.schema.json` and
+`atelier-decision-result.v1.schema.json`. They validate static shape. Use the
+JavaScript validator as well for request binding, evidence relationships,
+distribution semantics, and bounded in-process JSON.
+
+As with other Atelier contracts, the roots allow optional
+`contractVersion: "1.0.0"`, and closed objects allow an optional object-valued
+`ext`. Unknown first-class fields are refused. Namespaced extension members
+are inert metadata: consumers must ignore unrecognized members and must
+never derive authority from them. Dynamic question, choice and answer maps
+contain only their declared entries; they have no reserved metadata entry.
+
+Both requests and results, including extensions, are limited to 16,777,216
+canonical JSON bytes, 100,000 values, and 32 levels of nesting below the root.
+Cycles, symbols, sparse arrays, accessors, non-finite numbers, undefined
+values and custom prototypes are refused. Plain objects with a null
+prototype are accepted. No input is mutated.
+
+## Host integration
+
+1. Build bounded questions from already authorized evidence. Preserve all
+   source passages and coverage independently of a proposed prioritization.
+2. Validate the request, then check the host's current consent, destination,
+   concrete model pin, input limit, evaluation budget and timeout policy.
+3. Call a provider through the host adapter. Keep credentials, private
+   criteria, raw responses and provider execution outside the public kit.
+4. Normalize and validate the result against the exact request. Retain full
+   distributions and unknown usage; represent failures as explicit
+   abstentions without accepting partial answer sets.
+5. Compare shadow results with an independently labeled evaluation set.
+   Enable an advisory consumer only after task-specific acceptance. Keep the
+   host's existing behavior as the fallback and recheck authorization on
+   cache access.
+
+This module does not change the existing analysis adapter's default-disabled
+execution policy or accept a model proposal as an authored fact.