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

package/docs/evidence-navigation.md

@@ -0,0 +1,237 @@
+# Evidence navigation
+
+The portable evidence contract describes exact source references, attributed
+claims, declared host capabilities, and dependency snapshots. It sits under
+Knowledge Stewardship and can be composed by inquiry harnesses. The pure
+assessments are exported as `@mnstry/atelier/evidence-navigation` and the Node
+local reader as `@mnstry/atelier/evidence-navigation/local`. There is no CLI
+command.
+
+`validateEvidenceDocument(shape, value)` requires a primitive string shape and
+validates bounded JSON against the closed versioned schema. Supported shapes
+include `profile`, `hostCapabilities`,
+`evidenceRef`, `claim`, and `snapshot`. Unknown fields, unsupported kinds, missing
+attribution, invalid dates, and malformed references fail. Reserved `ext` fields
+cannot carry behavior. Unknown event time and source attribution remain explicit.
+Arrays require the ordinary array prototype. Assessments validate and evaluate
+the same copied descriptor values, without using the caller's getters or methods.
+
+`assessEvidenceCompatibility(profile, host)` compares exact declared protocols,
+operations, and capability versions. The result says whether those declarations
+match. The host must separately qualify its implementation and enforce permission.
+
+`assessEvidenceCurrency(reference, snapshots, { at, maxDepth, maxNodes })` checks
+an exact source reference and all supplied dependencies. Missing, ambiguous,
+changed, withdrawn, expired, and cyclic evidence cannot yield `current`. Reaching
+a verification bound also refuses current use. The caller supplies a valid time;
+the pure module never reads a clock, storage, identity, or permission service.
+Snapshots are protected host inputs, not permission grants or agent-visible
+provenance. This function does not establish coverage, absence, or completeness.
+
+`assessClaimContinuity(previous, next)` checks one logical claim's immutable kind
+and requires a new revision for changed content or status. Acceptance cannot
+turn an observation into a stated preference. A separately attributed new claim
+has a separate identity and lifecycle assigned by its owning host. This bounded
+check binds `claimId`, owner record owner/objectId, and kind. It allows subject or
+recorder attribution to change with a new revision; it does not classify a new
+claim or establish semantic continuity. Matching references do not prove support
+or truth.
+
+Every assessment explicitly returns `executionAuthorized: false`,
+`authorityTransferred: false`, and `semanticTruthVerified: false`. No assessment
+installs instructions, changes consent, writes a record, or qualifies a host.
+Source text remains evidence even when it contains imperative language.
+
+The host owns authenticated scope, audience projection, current permission,
+source admission and capture, dispatch, effects, and retention. It must recheck
+at each read and handoff. Internal paths, selectors, identifiers, digests, and
+hidden diagnostic details do not belong in an agent's result. The local
+reader uses the existing ingestion and intake owners; these
+pure functions create no second source store or acceptance lifecycle.
+
+The generator projects the canonical schema and JSDoc types into ESM modules
+and records their hashes and the pinned validator versions. Validation uses the
+package's existing Ajv and format dependencies with strict validation and no
+coercion or default insertion. A consuming runtime must supply those dependencies
+or qualify its own generated validator against the same schema and fixtures. Run
+`node scripts/generate-evidence-navigation.mjs --check` to refuse drift. The
+generation manifest identifies generated artifacts; a receiving integration
+must additionally pin the complete adopted source revision and its distribution.
+
+Invented garden fixtures and focused tests exercise these bounded structural
+properties. They do not prove installed consumers, operating-system isolation,
+database transactions, source removal, provider retention, or end-to-end consent.
+
+## Local search and exact fetch
+
+`createLocalEvidenceReader`, exported as `@mnstry/atelier/evidence-navigation/local`
+(`src/evidence-navigation/local.mjs`), is a Node adapter over one already-created
+ingestion plan. There is no CLI command for it. The pure entry point does not
+import it.
+
+Trusted host construction supplies `workspaceRoot`, `workspaceId`, exact
+`plan: { planId, planDigest }`, and synchronous `admit`. The callback receives the
+operation (`search` or `get`) and exact plan binding. Hosts map these callback
+strings to the profile operations `searchEvidence` and `getEvidence`. Only precisely
+`{ disposition: 'permit', revision, readScope: 'all-plan' }` proceeds. The revision
+is a nonempty, bounded identifier from current host authority. It changes whenever
+relevant scope, audience, destination, or permission changes, including withdrawal
+and regrant. Unknown scope, promises, callback errors, and other dispositions
+refuse. Native Promise rejections are contained without awaiting the decision.
+The host must admit the whole plan for this reader and intended recipient.
+A test callback that always permits establishes no actual consent.
+
+`search({ query, limit })` accepts up to five items and a nonblank query of at
+most 512 UTF-16 code units and 32 terms after lowercase, trim, and whitespace
+splitting. A secondary 2,048-byte UTF-8 ceiling is retained; the code-unit limit
+is already stricter. Invalid queries refuse before admission or
+store reservation and do not consume the read budget.
+`get({ handle })` accepts only a handle issued by this reader. Optional `readScope`
+must be `all-plan`; narrower scopes refuse before store construction. Model
+arguments cannot choose paths, plans, backends, or permissions. Construction-only
+`openStore` and `now` are trusted host/test seams, defaulting to the existing
+store and monotonic clock. Never expose these options as tool arguments.
+Admission is checked before construction, before reads, and before release,
+against the same revision.
+
+Search treats hits as pointers and re-fetches every item through the owner's
+`getEvidence`. Only exact-fetched text is returned. Get rechecks its protected
+source/attempt/locator binding and a private commitment to the earlier fetched
+text. The owner's integrity label does not prove independent content authenticity:
+its journal has no output digest, so a same-size stored rewrite before first
+fetch may be undetectable. Backend errors expose no paths or stored diagnostics.
+Admitted text itself is not redacted here; the host owns its audience and any
+permission to process it downstream.
+
+Results contain text, temporary handles, truncation, and `source-evidence` kind,
+without protected IDs, digests, selectors, or hidden-match counts. Coverage is
+always `partial`, including zero results. No current absence claim follows.
+Instruction-looking text remains evidence; the consuming host must preserve that
+distinction in its prompt/context boundary.
+
+Defaults are 32 reserved store calls, 32 handles, 16,384 text bytes per item,
+65,536 total released text bytes, and a 60-second session. Trusted limits can
+vary within hard ceilings of 128 calls/handles, 65,536 bytes per item, 262,144
+total bytes, and ten minutes. Search reserves one query plus its requested maximum
+exact fetches. Failed and unused reservations are not refunded. UTF-8 truncation
+preserves whole code points. A search releases its result as a whole; if no text
+budget remains while fetching its hits, prepared items and handles are dropped
+and the whole search refuses. Issued handles retain their session charge even
+after an admission revision changes; start a new session for the new admission.
+The ingestion owner's plan/processor ceilings bound
+traversal; a hit limit does not limit inspected sources. Synchronous store reads
+cannot be preempted by the lifetime check. A host requiring a hard execution-time
+limit must qualify an isolated worker.
+
+`close()` discards handles and refuses further reads. Expiry, clock reversal,
+reentrant calls, foreign handles, changed authority, and changed sources refuse.
+The adapter persists, ingests, accepts, activates, and schedules nothing. It
+provides cooperative process-level checks, not OS isolation, a permission issuer,
+or a database workflow. The host must qualify the real authority and release path.
+
+## Read a complete selected citation
+
+Lexical search is partial discovery. It can find a line that names an
+instrument and miss the next line saying that approval awaits inspection. When
+a source owner has selected a complete cited unit, a trusted host can read that
+unit exactly with the existing APIs. This adds no model-callable API. Exact
+reading shows what the selected unit says. It does not show retrieval quality,
+answer correctness, usefulness, or semantic acceptance.
+
+### Which route reads what
+
+| Route | Reads | It cannot |
+| --- | --- | --- |
+| `createLocalEvidenceReader` `search` then `get({ handle })` | Hits that this reader's own search found and re-fetched | Accept a citation, locator, page, path, or protected reference. Only its own search issues handles. |
+| `createIngestionStore` (`@mnstry/atelier/ingestion`) `getEvidence` | One exact span for a protected `planId`, `planDigest`, `sourceId`, `sourceDigest`, `attemptId` and `locator` | Grant permission. The host must admit the **whole plan** even though one fetch reads only the named source. A host whose decision covers only some sources must not call it; the store cannot detect this. |
+
+`getEvidence` is the route for an explicitly selected citation. It keeps nothing
+between calls: each call checks the current source digest, the completion
+receipt stored beside the output, and the journal's recorded size and coverage.
+Keep its bindings, the source map, and constructor arguments in trusted host
+custody, never under model control. The source must already be in an ingestion
+plan with a completed attempt.
+
+### Steps for the host
+
+1. **Map the unit.** The source owner defines the unit in the existing source
+   map: its qualifying lines and limits, not just the lines matching a query,
+   and whether the text is original or derived. Bind the map to the current
+   source digest, the completed extraction attempt, the processor semantics,
+   the ordered locators, and the expected hash of each exact text.
+2. **Reuse the existing plan and attempt.** Do not create a second extraction
+   store or reinterpret locators.
+   - Text and Markdown evidence uses physical lines without their line
+     terminators (`line`), split on CRLF, LF or a lone CR, after a leading BOM
+     (U+FEFF) is removed.
+   - JSON primitive leaves use RFC 6901 pointers (`json-pointer`): string text
+     is decoded; numbers, `true`, `false` and `null` keep their source
+     spelling; empty arrays and objects produce no evidence. A unit that relies
+     on a boolean or number qualification includes that leaf.
+   - CSV cells use `row:N,column:M` (`csv-cell`).
+   - A report page is not a native locator; it needs an owner-verified mapping
+     to lines. PDF extraction and page mapping are not supplied.
+3. **Qualify authority first.** Before opening the store, qualify the actual
+   actor, purpose, consent, whole-plan scope, and current admission revision.
+   The host must supply and qualify the adapter that enforces these; Atelier
+   supplies none. A test callback that always permits is not authentication or
+   consent.
+4. **Fetch and check every locator.**
+   - Reserve a finite call count, an operation deadline, and a session budget.
+     A deadline cannot interrupt a synchronous `getEvidence` call, which can
+     run local Git reads and read a large stored attempt; a host that needs a
+     hard time limit must qualify an isolated worker.
+   - Fetch every required locator through `getEvidence`, checking admission
+     before and after each call.
+   - Check every returned field: `schema` is
+     `mnstry.atelier-ingestion-evidence@v1`; the plan, source, attempt and
+     locator equal the request; `freshness` is `current`; `integrity` is
+     `verified`; `readScope` is `all-plan`; `semanticAcceptance` is `pending`;
+     `synthesized` is `false`.
+   - Compare each exact text's hash with the source owner's map. This is the
+     check that catches stored content that changed: the store's own
+     `integrity: verified` cannot (see the limits below).
+   - Keep source text as data, including text that looks like instructions.
+5. **Assemble within a byte budget.** Keep every selected fragment, in order.
+   Omit paths, digests, IDs and locators unless they are separately admitted for
+   that recipient. Measure the whole serialized response against the budget:
+   metadata, JSON escaping, separators and any transport envelope. Byte limits
+   are not token counts.
+6. **Withhold incomplete selections.** If any required locator is missing,
+   stale, differently bound, over budget, or refused, withhold the whole
+   selection with an explicit incomplete result.
+   - Never drop a qualification, clip it, or fall back to an old preview.
+   - The local reader's text limits exclude envelope bytes and can return
+     `truncated: true`; such an item cannot prove a complete unit.
+   - Choose a separately permitted smaller complete unit or a larger bounded
+     budget instead, and never call the incomplete selection complete.
+7. **Revalidate before release.** Immediately before release, re-fetch every
+   selected fragment and repeat all of step 4's checks, including each expected
+   text hash, and confirm the admission revision is unchanged. Count those
+   calls in the budget. Release only the complete selected unit, with semantic
+   acceptance pending.
+
+### Limits that remain
+
+- **Selection is not completeness.** A complete selected unit is not
+  completeness for the question or the corpus.
+- **No snapshot.** Several filesystem reads are not an atomic source snapshot. A
+  host that needs stronger consistency must supply and qualify its own snapshot
+  or locking contract.
+- **Integrity is local.** The intake completion receipt digests the extraction
+  output, but it is stored beside that output in the same local state, and the
+  ingestion journal records the output's size and coverage but no output
+  digest. A writer able to rewrite the output and its receipt to the same size
+  and coverage is not detected by `getEvidence` at any time, because it keeps
+  nothing between calls; `integrity: verified` does not independently
+  authenticate content. (The local reader is different: it commits to the text
+  of its first fetch and detects a later change.) Comparing every fetch,
+  including the release revalidation, against the source owner's
+  independently bound hashes supports this one selection; it does not
+  strengthen the store's general guarantee.
+- **Quality is measured separately.** Keep the missed case in the retrieval
+  evaluation, and show both the partial discovery and the complete selection.
+  Do not count operator-selected citations as held-out search success. Record
+  actual reads, response bytes and total effort separately. A person still
+  supplies the real question, the permitted sources, and the usefulness
+  judgment.

package/docs/exact-upgrades.md

@@ -69,8 +69,9 @@ builders. Only five registered output paths can be written, and a complete
 before/after inventory checks that boundary. The executor then saves those
 bytes; application does not recalculate or silently replace the selected plan.
 This is a bounded trusted executor, not a sandbox for arbitrary migration code.
-The generated readiness JSON retains absolute local graph and projection paths,
-which may include the account name. Inspect those committed bytes before sharing
+The generated readiness JSON records graph and projection paths relative to the
+project configuration directory, so its bytes match what `atelier readiness`
+would regenerate in the candidate. Inspect the committed bytes before sharing
 the candidate branch; generating a candidate does not authorize publication.
 
 ## Apply the reviewed bytes

package/docs/ingestion.md

@@ -0,0 +1,181 @@
+# Progressive local ingestion
+
+Status: experimental source implementation, not yet a released package feature.
+The local runner preserves explicitly selected files and makes bounded text
+search useful before semantic interpretation. It composes the existing
+[immutable intake](intake-and-guides.md) with a resumable plan. It never enrolls
+raw captures into the canonical graph or treats extracted text as accepted
+knowledge. The [architecture proposal](progressive-ingestion.md) describes the
+larger destination; this page describes the implemented subset.
+
+## Start with a purpose and selected sources
+
+Use a Git workspace whose `.gitignore` contains `.atelier-local/`. That directory
+must be untracked. Sources are visible paths relative to that workspace;
+traversal, symlinks and implicit external reads are refused. The local CLI is
+for a trusted workspace owner. Its workspace identifier is a binding against
+accidental cross-workspace reuse, not an authenticated identity or tenant ACL.
+
+The following examples assume the development checkout or a future package
+version containing this command. Released alpha.7 does not contain it.
+
+```sh
+atelier ingest plan <<'JSON'
+{"workspaceId":"sample-workspace","input":{"sources":[{"id":"service-note","ref":"service.md"},{"id":"parts","ref":"parts.csv"},{"id":"checklist","ref":"checklist.png"}],"scope":{"project":"sample-project","activity":"maintenance"},"purpose":"Find unresolved maintenance work.","budget":{"maxInputBytes":1048576,"maxOutputBytes":1048576,"maxAttempts":8}}}
+JSON
+```
+
+Save the returned `planId` and `planDigest`. Each subsequent request binds both:
+
+```sh
+atelier ingest run <<'JSON'
+{"workspaceId":"sample-workspace","input":{"planId":"REPLACE_WITH_PLAN_ID","planDigest":"REPLACE_WITH_PLAN_DIGEST","maxItems":2}}
+JSON
+atelier ingest query <<'JSON'
+{"workspaceId":"sample-workspace","input":{"planId":"REPLACE_WITH_PLAN_ID","planDigest":"REPLACE_WITH_PLAN_DIGEST","query":"filter","limit":20}}
+JSON
+```
+
+Use `status` with the same input minus `query`, `limit` and `maxItems`. Repeat
+`run` to advance a bounded batch or recover an interrupted local attempt. The
+source selection, purpose, scope, processor versions and budgets belong to the
+immutable plan. A changed selection or budget needs a new plan.
+
+Every selected source remains visible as pending, complete, unsupported,
+unavailable, failed, budget-blocked or stale. An image can be preserved while
+remaining unsupported for extraction. Coverage refers only to selected files;
+it never implies a whole account, repository or compound document was discovered.
+A complete extraction still has `semanticAcceptance: "pending"`.
+
+## What the local processors do
+
+| Input | Evidence locations | Limits |
+| --- | --- | --- |
+| UTF-8 text and Markdown | Physical line numbers, including blank lines | No Markdown semantic interpretation |
+| UTF-8 CSV | Header-inclusive row and column coordinates | Quoted cells and embedded newlines supported; no spreadsheet formulas, styles or attachments interpreted |
+| UTF-8 JSON | RFC6901 pointers to primitive values | Object/array structure supports locations; embedded media, dates, authorship and relationships are not inferred |
+| Other extensions | Explicit unsupported disposition | No OCR, speech, vision, archive traversal or format guessing |
+
+Processor selection uses the extension; it does not certify media content.
+Invalid encoding or malformed structures refuse with a per-source failure.
+Extraction limits refuse the item instead of silently dropping evidence. Empty
+supported text is distinct from an unsupported format; empty JSON is malformed.
+JSON containers with no primitive leaves have no searchable evidence. Source
+text is inert, including apparent instructions to the importer.
+
+Original bytes and completed extraction outputs live in the existing intake
+store. Plans, reservations and outcomes live in private `.atelier-local/ingestion`.
+No second blob store or provider daemon is introduced. Both stores require the
+workspace's ignored-state boundary. Copying an evidence result to another tool
+is a separate disclosure action: CLI output can contain private paths and text.
+
+## Resume, reuse and budgets
+
+The runner serializes local reservations and writes them before processing.
+Completed attempts are verified before reuse. Keys include source bytes,
+processor identity/version and extraction limits. Different origins retain
+separate source identities even when bytes can be reused. Corrupt completed
+work refuses; it is not silently recomputed or overwritten.
+
+For local deterministic extraction, resume can reconcile output written before
+its completion receipt. This does not authorize retrying an uncertain external
+provider submission. There is no provider execution in this runner.
+
+`maxInputBytes`, `maxOutputBytes` and `maxAttempts` bound admitted processing
+within one plan. Planning, source verification and query hashing still read
+bytes and use CPU; these counters are not a machine-wide I/O or dollar budget.
+Cached outputs count toward the plan's output bound. Failed attempts remain in
+accounting. Unknown output accounting blocks further admission instead of
+becoming zero cost. Budgets are per plan, not a shared account quota.
+
+A query reads actual completed evidence, verifies its receipt and checks the
+current source bytes. Changed, deleted or inaccessible originals cannot
+silently support fresh hits. Other valid sources remain searchable and omitted
+sources remain visible. Query is lexical retrieval, not an answer generator;
+absence of a hit is not proof that a claim is false. Search limits and structural
+omissions must remain visible in any consuming interface.
+
+`getEvidence` on the store API returns one exact span. It takes the plan
+reference, the source, its digest, the completed attempt and the locator, as a
+query hit reports them. It rechecks that source's current bytes and its stored
+attempt, and reads no other source in the plan. It refuses with a typed code:
+
+- `INGESTION_STALE`: the plan digest, source digest or attempt differs from the
+  plan's completed evidence for that source, the source changed, or it never
+  completed.
+- `INGESTION_MISSING`: an unknown source or locator, or a plan directory that
+  does not exist.
+- `INGESTION_INTEGRITY`: stored evidence fails verification against the plan,
+  or a locator is not unique in it.
+- `INGESTION_INVALID`: a malformed request, or a stored plan or journal record
+  that fails its schema.
+
+Workspace-level refusals (`INGESTION_WORKSPACE`, `INGESTION_PRIVATE`) and
+`INGESTION_LIMIT` apply as they do for query. Status, query and `getEvidence`
+check a completed attempt's coverage and output size against the plan's own
+record. The journal does not yet record a digest of the output, so a stored
+attempt rewritten without changing its size or coverage is not detected. Its
+query hits can then fail to resolve through `getEvidence`. Treat a query hit as
+a pointer, and cite only what `getEvidence` returns.
+
+Both query and `getEvidence` report `readScope: "all-plan"`. Query reads every
+source in the plan, and a limit bounds only the hits it returns. Neither call
+narrows or grants permission. A host that may read only some of a plan's
+sources must not pass that plan to either call.
+
+## Connect a useful result to learning
+
+A correction made while using a retrieved passage can be captured through
+[`atelier learn`](learning.md), with the source reference, its exact digest and
+location. Capture is evidence only. Proposals remain inert until a person
+reviews the exact content, accepts it and explicitly activates it for a scoped
+harness. Withdrawal preserves the decision history while stopping future use.
+
+The core exposes this composition; it does not monitor every tool automatically.
+A desktop host must supply capture consent, trusted identity, paired workspace
+access, transport and actual harness delivery. Tests of a local client do not
+establish native admission. Review and activation never execute text discovered
+inside an imported file. A captured source reference remains historical evidence;
+source changes do not automatically withdraw a separately accepted lesson. A host
+must surface that staleness when it uses source-dependent lessons.
+
+## Evaluate before choosing a model
+
+`@mnstry/atelier/ingestion/evaluation` exports `evaluateIngestionTrial` and
+`ingestionEvaluationDigest`. An evaluation suite declares exact expected
+structural evidence, source digests, calibration/held-out cases, strata and
+thresholds before the trial. A trial binds its suite digest and processor
+version/configuration; each case reports attempts, evidence, elapsed time,
+cost (or `null`) and an optional explicit human assessment.
+
+The scorer counts omitted cases, wrong locations, changed text and duplicates.
+Each held-out stratum must satisfy the declared thresholds. A zero-evidence or
+calibration-only sample cannot qualify extraction. Unknown costs stay unknown;
+cost per accepted result is absent when cost or acceptance is unavailable.
+Human assessment identities are caller assertions. This is an audit aid, not a
+model permission grant or an automatic judge of semantic support.
+
+Run the synthetic local example with:
+
+```sh
+node scripts/evaluate-ingestion.mjs
+```
+
+The example records processor elapsed time and leaves total cost unmetered. It
+uses no model and proves no model savings. For a real comparison, the owner
+must provide permitted representative examples, exact providers, a spend cap,
+predeclared task rubrics and human acceptance. Count retries, failures,
+verification and correction effort. Compare cost per useful accepted result,
+with quality floors and rare exceptions preserved. Keep private examples and
+methods in their owning workspace.
+
+## Remaining product work
+
+The public foundation still needs qualified semantic adapters, focused
+synthesis and graph decision integration, richer document/media processors,
+connector census and permission-change handling, and representative pilots.
+The proprietary runtime adds native scheduling, installed processors,
+provider credentials/budgets, progress and source review, cancellation,
+notifications and scoped harness delivery. The public reference path remains
+usable without that runtime. Neither private material nor private methodology
+belongs in public fixtures or distributed proprietary prompts.

package/docs/inquiry-harnesses.md

@@ -0,0 +1,211 @@
+# Discovery Harness and Research Harness
+
+Status: implemented locally for the next release. The published alpha.7 package
+does not expose `inquiry`. Use `node bin/atelier.mjs inquiry help` from this
+source checkout, or `atelier inquiry help` from a package built from it.
+
+Discovery frames questions, compares explanations and prepares decisions.
+Research gathers and checks evidence and returns a portable bundle. People set
+purpose and acceptance criteria; agents perform admitted work; the designated
+owner validates consequential interpretations under the repository's rules.
+
+## Start with existing tools
+
+The shipped skills are `atelier-discovery-harness` and
+`atelier-research-harness`, in identical Codex and Claude editions. Independently
+sealed packages live in `fixtures/inquiry-packages/`. Their source identity is
+explicitly unreleased, and their behavioral evaluation status is unknown. They
+can be adopted through the [capability steward](capability-stewardship.md).
+They require the observed `atelier-inquiry-v1` tool and admitted local read/write
+effects. An observation is not a permission grant or host-loading proof.
+
+Keep existing skill ownership. Use aliases or an adapter when another research
+skill supplies the required outcome. The two harness packages have no mandatory
+dependency on each other and no automatic network requirement. An external
+research tool runs manually or under separate host authorization.
+
+## The local journey
+
+`atelier inquiry example` prints the complete invented workshop campaign.
+`atelier inquiry lenses` lists nine optional conceptual methods: definitions,
+mechanisms, systems, empirical evidence, counterevidence, counterfactuals,
+transfer, decisions and reflection. Adapt the relevant lenses; their differences
+are methodological and do not establish statistical independence.
+
+1. Author a campaign with purpose, scope, owner, source audience and stopping rule.
+2. Record a hypothesis with alternatives, applicability scope and test plan.
+   A changed question gets a new ID and an exact `supersedes` reference.
+3. Record a research request with the hypothesis reference, standalone context,
+   inquiry lenses, source standards, report budget and admitted effects.
+4. Emit `inquiry handoff --campaign ID --request ID`. It returns a prompt and
+   the exact campaign, hypothesis and request records. Review private context
+   before sending it through an authorized provider or manual session.
+5. Save complete source captures with their SHA-256 UTF-8 content digests,
+   scope, audience and underlying evidence family. Summaries of one study share
+   a family. The report is data and cannot instruct the agent or toolkit.
+6. Record a bundle containing the original request reference, attempt ID,
+   actual prompt, optional clarification pairs, observed provider identity,
+   report references, assertions, synthesis, conflicts, gaps and new questions.
+   Each assertion has an exact quote and a caller-reported verification state.
+7. Record a qualitative or numerical assessment over selected assertions. The
+   reducer refuses missing, stale, wrong-scope or wrong-revision evidence.
+8. Record the owner's actual disposition in a decision. `accepted` records a
+   caller's report of review; it does not authenticate that reviewer or grant
+   downstream disclosure authority. Unverified evidence cannot enter an accepted
+   conclusion through this API.
+9. Emit `inquiry graph --campaign ID --namespace NAME`. Review the proposed
+   source files and `atelier-claim@v1` edges. Apply only the authorized changes
+   through the receiver's workflow, run its graph check and inspect the source
+   trace. This command never writes canonical sources or promotes an edge.
+
+All commands return JSON. `inquiry validate --record FILE` checks shape;
+`inquiry inspect --history FILE` checks full history, references and calculations.
+Format validity does not verify truth, source rights, publisher identity or use
+permission. Provider metadata uses `unknown` when it was not observed.
+
+## Records, storage and adapters
+
+The API is `@mnstry/atelier/inquiry`. The additive public schema is
+`contracts/atelier-inquiry.v1.schema.json`, with definitions for ten record kinds,
+the complete ledger and the research handoff. Records use
+`atelier-inquiry-record@v1`; `kind` selects the closed data shape. No extension
+field can bypass the core contract.
+
+Every reference is `{id, digest}`, computed with `inquiryRef(record)` or
+`inquiryDigest(record)`. Record IDs never change and are unique within a campaign.
+The historical evidence set and model inputs remain available when new decisions
+or withdrawals are appended. The supplied synthetic JSON is a worked input
+example, not research evidence.
+
+```js
+import {
+  EMPTY_INQUIRY_HEAD, appendInquiry, readInquiry, inquiryRef,
+  researchHandoff, inquiryGraphProposal,
+} from '@mnstry/atelier/inquiry'
+
+// workspaceRoot is an explicitly selected Git repository root.
+// campaignRecord is authored against the campaign definition in the schema.
+const receipt = appendInquiry({
+  workspaceRoot, record: campaignRecord, confirm: EMPTY_INQUIRY_HEAD,
+})
+// Author the next record using inquiryRef(existingRecord) for each reference.
+// Confirm the latest head returned by status or append for every next append.
+const state = readInquiry({ workspaceRoot, campaign: campaignRecord.id })
+```
+
+The CLI equivalent is `inquiry append --record FILE --confirm CURRENT_HEAD`.
+`inquiry help` prints the initial empty-history digest. `inquiry status` returns
+the current head and reconsideration queue. `inquiry export` returns a complete
+ledger, including private captures: choose its output destination deliberately.
+The pure API can inspect and exchange exported histories without an account.
+
+Stored ledgers are under `.atelier-local/inquiry/CAMPAIGN/ledger.json`. Writes
+require ignored, untracked `.atelier-local/` state on a qualified POSIX filesystem.
+Windows ledger writes refuse before creating state; read-only inspection and
+exchange of existing histories remain available.
+A shared steward lock serializes cooperating writers. Each append checks the
+expected head, replays the history, and atomically replaces one file containing
+the complete immutable record sequence. Interrupted writes retain a complete
+previous or next file; inspect before repeating an uncertain append. A hard
+process termination can leave a shared lock requiring operator reconciliation;
+do not remove a live or unverified lock. This release has no automatic inquiry
+lock recovery or multi-repository transaction.
+
+Limits: 256 records and 8 MiB per ledger; at most 64 elements in bounded record
+arrays; source captures at most 262,144 characters; actual prompts at most
+1,048,576 characters. Export and verify history before starting a continuation
+campaign; the toolkit does not silently truncate or compact it. References are
+local to a campaign; inter-campaign and inter-repository links remain explicit
+provenance under the receiver's conventions.
+
+Hashes detect a mismatched pin, not a malicious writer who can replace the whole
+ledger. File controls assume cooperating local writers and do not create an OS
+sandbox against concurrent directory replacement. Audience labels describe
+readership, not filesystem access control. Non-private campaigns reject source
+audiences outside their declared readership; public disclosure still requires
+the existing repository boundary process.
+
+## Belief calculations and their limits
+
+Three representations are supported:
+
+| Kind | Output and interpretation |
+| --- | --- |
+| `qualitative` | A documented judgment, no probability |
+| `elicited-odds` | Prior plus stated likelihood ratios and sensitivity priors; conditional on elicitation and independence assumptions |
+| `beta-binomial` | Beta posterior parameters, mean, variance and predictive success rate for explicitly defined binary trials |
+
+The odds calculation uses log odds and applies one contribution per evidence
+family. Identical family contributions are counted once and exposed as duplicate
+keys. Conflicting contributions from one family refuse. This is a conservative
+one-contribution-per-family model, not a general dependence engine: aggregate
+dependent observations through a separately justified joint model or use a
+qualitative assessment. A duplicate-family label is supplied by the caller and
+cannot discover hidden overlap in external studies automatically.
+
+Prior evidence families must resolve to recorded sources and must not be reused
+as new contributions. Source withdrawal invalidates that whole family, its prior
+uses, assessments and decisions. Relabeling the same external study with a new
+family would evade this check; source-family review remains essential.
+
+A rate-model mean is not the probability a broad hypothesis is true. The caller
+defines trials, counts, sampling, scope and independence. No universal likelihood
+ratio, interview count or posterior threshold is bundled. Arithmetic and exact
+replay are tested; calibration is reported as unverified. Prior/posterior
+predictive simulation, general hierarchical inference, causal estimation,
+credible-interval computation and formal expected value of information are
+separate model adapters. The emitted rate predictions are analytic summaries,
+not model-adequacy diagnostics.
+
+Append a `withdrawal` naming a source or report bundle to preserve a correction
+trail. A delayed bundle against a superseded request is preserved but flagged;
+it cannot silently update the new hypothesis. A corrected source should receive
+new source/family identities with the correction explained in its locator/method
+and the new assessment rationale. There is no implicit unwithdraw action.
+Legacy heuristic values can be preserved as `legacy-assessment` records; they
+never become computed posteriors or automatic priors.
+
+## Graph integration and stewardship
+
+Only current accepted decision reports produce graph proposals. Sources and
+assessments carry stable campaign-scoped graph IDs; files remain drafts and
+relations remain proposal-only claims. Selected quotes, evidence pins, provider
+metadata and unresolved conflicts survive the projection. Raw captures and
+unrelated assertions stay in the campaign ledger. A changed conclusion produces
+a new decision record. Historical graph sources already admitted by a receiver
+are not deleted automatically; use `reconsider` to prepare their revision there.
+
+A request may record an exact capability release, binding digest, generation,
+host and session. `inquiry feedback --campaign ID --record FEEDBACK_ID` prepares
+a content-free Steward event. `capability observe` validates that it still names
+the current installed binding. This is an explicit second action; the inquiry
+API never rewrites a skill, installs an upgrade or submits telemetry.
+
+Inquiry retains separate skill, host, tool, configuration, context, provider and
+unknown causes. The current Steward event vocabulary cannot distinguish context
+or provider causes: the prepared event uses `unknown`, while its wrapper retains
+the original cause and an explicit mapping notice. Do not infer a skill defect
+from a provider failure or an unknown result.
+
+## Open and operated capabilities
+
+The local records, conceptual lenses, reference skills, basic calculations,
+history, graph proposals and adoption remain in the open package. A user can
+complete and export the local journey without a service or provider account.
+
+An operated or proprietary adapter may offer provider scheduling, quota and cost
+controls, collaboration, private connectors, specialized methods or more complex
+models. It must honor the request pin, return complete captures and observed
+metadata, preserve gaps and permit export of authorized records. Its execution,
+credentials, budgets and disclosure belong to the host. This release contains
+the manual handoff and return contract; it does not ship hosted runners, a paid
+service, a registry, or an authenticated review system.
+
+The architecture catalog uses Discovery Harness and resolves Discovery Engine
+as a historical alias. The bundled `mnstry-readiness-pack@v1` is immutable:
+its Discovery Engine title, `mnstry.readiness:discovery-engine` ID, question
+identifiers and digest all retain their original release values. The protocol
+remains a planning entry point. Keeping the rename outside that object lets
+existing release locks enter both exact upgrade participants without an
+out-of-band lock rewrite. A future change to the bundled object requires a new
+pack version and an explicit upgrade path.