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

package/docs/knowledge-health/devday/facilitator.md

@@ -1,16 +0,0 @@
-# Atelier Dev Day run sheet
-
-Rehearsal target: Wednesday 7 October 2026. In-person use: Thursday 8 October 2026, Asia/Makassar. This is a planned protocol; no participant result has been observed here.
-
-Before the event, rehearse the exact published version on a clean consumer. Record package version, integrity, tested Mac/Node, normal installed entry, public example and owning source route. Bring the pinned release and verified quickstart. A local tarball run and registry installation are separate records. If the full guided journey is unavailable, disclose that limit and use only the supported baseline exercise; do not present it as the complete delivery.
-
-Allow roughly 25–35 minutes for the exercise, adapting to the participant. Explain that their words, disagreement and decision to pause remain theirs. Ask whether they want their feedback recorded, use a participant code rather than a name, and preserve exact words only within the agreed note custody. They may decline or stop at any point.
-
-1. Ask what the participant currently thinks the source relationship means. Record their explanation and confidence before showing the finding. Ask what evidence would change their view.
-2. Open the installed public example through its normal entry. Let them locate the source passage and supporting evidence. Ask them to explain the finding in their own words, including what the tool cannot establish.
-3. Invite a contribution relevant to the example. Preserve their exact original words. Let them inspect any proposed interpretation and choose agreement, disagreement, perspective-only or pause. Do not reinterpret a pause as acceptance.
-4. Let them inspect the proposed revision and preview. Ask what will change, who owns the write, and what should remain unchanged. Apply only through the example's existing owning route after their explicit choice. Saving words and applying a source correction are different actions.
-5. Verify the exact accepted readback, reopen through the normal entry, and rerun the affected check. Let the participant explain what changed and what remains uncertain. Preserve a historical finding/context rather than relabeling it current.
-6. Ask what was difficult, whether the contribution felt meaningful, and whether the result was useful. Record an exact quotation if they agreed, elapsed time and assistance used. Separate their judgment from facilitator interpretation and automated results.
-
-If a write is uncertain, preserve the original operation ID and full intent. Use the existing original-ID lookup/readback before any admitted identical retry. Keep the interface in an unconfirmed/checking state until readback resolves it. Do not create a new operation ID, erase history or show Saved early. If the owning route cannot resolve it, stop the write step and retain the trace for support.

package/docs/knowledge-health/devday/public-default.md

@@ -1,107 +0,0 @@
-# Use the public workshop profile
-
-Use the exact package version and integrity supplied by the release owner. This
-profile is a source contribution until it is admitted, released and rehearsed.
-
-In an empty consumer directory, install that version and create a new workshop:
-
-```sh
-npm install --save-exact "@mnstry/atelier@$ATELIER_DEVDAY_VERSION"
-```
-
-```js
-import { initializeKnowledgeHealthWorkshop } from '@mnstry/atelier/knowledge-health'
-initializeKnowledgeHealthWorkshop('./workshop')
-```
-
-Build its graph and projection, then start the existing loopback host:
-
-```sh
-npx --no-install atelier graph --project ./workshop/atelier.project.json
-npx --no-install atelier build --project ./workshop/atelier.project.json
-npx --no-install atelier server --knowledge --project ./workshop/atelier.project.json --port=0
-```
-
-Open the printed URL at `/knowledge`. The Workshop profile appears when the
-current invented checklist has the actionable missing supporting relationship.
-Read the finding and both sources before responding.
-
-## Retain your response
-
-1. Record your original words and save the private draft.
-2. Record a separate interpretation. **Propose revised wording** shows the
-   confirmation step; confirm or keep the original wording, then save.
-3. Enter one exact choice yourself: `note`, `perspective-only`, `disagreement`
-   or `pause`. Save it. These responses retain different meanings, and a
-   proposed choice is refused.
-
-**Review** is a separate, optional action. It becomes available after all three
-fields are saved and read back. It opens a second session with one field:
-enter `["devday:workshop"]` there and save it to select the draft declaration.
-See [participant response](participant-response.md).
-
-The **Pause** control pauses the session and retains its existing state. A
-saved `pause` choice records your response without selecting a source edit.
-
-The same native text field stays available while a request is pending. Later
-wording and composition remain unsaved until you record them. Export the
-snapshot before closing the tab when wording or a request remains unresolved.
-Closed-tab browser recovery, native undo and keyboard behavior still require
-qualification in the receiving browser.
-
-If a reply is lost, **Retry exact request** first looks up its original ID in
-durable history. A known retained event is read back without another append.
-An unknown outcome retains the request for inspection. A source change leaves
-earlier history readable and refuses new writes to the old session.
-
-## Review a source-owner handoff
-
-After the selected draft is saved in the Review session, **Prepare
-source-owner handoff** reads both sessions back from durable storage and
-retains one copy-only proposal in the existing local proposal store. The
-proposal holds the original words, interpretation, choice, selected
-declaration, six finding reference fields, source, anchor, read set and the
-saved draft receipts, unshortened. The response names the proposal ID. Read the
-proposal back at `/api/proposals/<id>` or on the `/proposals` page.
-
-Repeating the request looks up the original saved receipt before anything is
-appended. The same handoff returns the same proposal. A different value under
-the same receipt is refused. If the source has changed since, a proposal that
-was already retained is still read back, and nothing new is retained. A
-missing or altered saved draft, or a handoff too large to keep whole, is
-refused. An unreadable proposal ledger is reported as unknown: inspect it, then
-repeat the same request. A retained proposal has status `proposed`. It is not a
-review decision and it applies no source change.
-
-The normal Knowledge host has no source-apply endpoint. A source owner may
-review and edit the exact declaration using normal repository editing, then
-read it back and reassess:
-
-```js
-import { createPublicWorkshopComposition } from '@mnstry/atelier/knowledge-health'
-const workshop = createPublicWorkshopComposition({ workspaceRoot: './workshop' })
-console.log(workshop.inspect())
-console.log(workshop.read(savedSessionId))
-```
-
-Keep the frozen expected evidence. A cleared relationship finding can still
-leave `devday:checklist` stale in question evaluation. Refreshing expected
-evidence is a separate explicit source-owner action. Neither result establishes
-semantic support, readiness or human acceptance.
-
-## API and authority
-
-`createPublicWorkshopComposition` delegates `start`, `event`, `lookup`, `read`,
-`recover` and `list` to the existing Knowledge sessions and durable coauthor
-store. `profile()` provides current evidence and the start snapshot;
-`prepareHandoff(sessionId)` prepares the copy-only handoff after durable readback.
-Use the existing session request shapes. The author is locally asserted.
-
-This profile saves ordinary public coauthor drafts. Its context retains the
-six finding fields; it does not issue a native typed finding-disposition receipt.
-It adds no source writer, ledger, canonical model, editor or server.
-
-The public Obsidian source-apply primitive is available under
-`@mnstry/atelier/obsidian/edits`. It requires its admitted workspace, vault,
-generation, policy and authored-body lens. Its compatibility with this workshop
-frontmatter remains an owner binding gap; these controls must remain enforced.

package/docs/knowledge-health/devday/quickstart.md

@@ -1,18 +0,0 @@
-# Start with the pinned public package
-
-This quickstart covers the published baseline, 0.2.0-alpha.12. It gives a public invented graph example and existing coauthor capabilities. The full Knowledge Health guided journey is a release-owner join; it is not present in this baseline installation.
-
-Use Node 22.18.0 for the tested rehearsal. Create a new empty directory and install the exact version:
-
-    npm install --save-exact @mnstry/atelier@0.2.0-alpha.12
-    ./node_modules/.bin/atelier --version
-    ./node_modules/.bin/atelier init --template sample-workspace --target example
-    cd example
-    ../node_modules/.bin/atelier graph
-    ../node_modules/.bin/atelier project
-
-The graph and projection describe the installed invented example. Read its source documents alongside the result. A structural check does not decide whether a real relationship is meaningful or accepted by its owner.
-
-These commands use the installed bin. They do not download a moving latest version or require a publisher checkout. The tested docs inside the installation include README.md, docs/knowledge-graph.md and docs/coauthor-session.md. The exported API families include @mnstry/atelier/graph, @mnstry/atelier/project and @mnstry/atelier/coauthor. Use only the actual version's declared exports.
-
-For the Dev Day release, the facilitator must first receive and rehearse its exact version, normal example entry, guided authoring entry and owning correction route. Replace the pinned version only after that receiving. Do not substitute an unreleased source template or a private editor for an installed capability. Keep the tested package integrity and the separate tarball/registry reports with the handover.

package/docs/knowledge-health/devday/support.md

@@ -1,22 +0,0 @@
-# Support and recovery
-
-| Surface | Evidence | Limit |
-| --- | --- | --- |
-| macOS, Node 22.18.0 | Clean public baseline registry and tarball consumer reports | Full Dev Day candidate remains pending receiving |
-| Node 24.13.1–24.x | Package declares support | No run in this packet |
-| Linux | Package may run there | No platform qualification in this packet |
-| Windows | No consumer run here | This proof harness refuses Windows execution until separately qualified |
-| Guided Knowledge Health UI | Existing native suppliers have separate proof | Not installed by the public baseline |
-| Human understanding/usefulness | Predeclared participant protocol | Actual event observations remain open |
-
-If installation fails, keep the exact version, registry integrity, Node/npm version and error. Do not add publisher overrides or switch to latest to hide the error. Retry a network fetch only after identifying the network failure; a save/application retry follows its own operation lookup and fencing contract.
-
-If a command or example is missing, check the installed package's bin, exports and files. In the observed baseline, normal init refused knowledge-workspace and listed private-domain, shared-project, sample-workspace, distribution and external-project. Use the tested sample-workspace baseline only for its supported graph exercise. The full guided example requires the new release owner's receiving.
-
-If source or repository identity changed, stop the affected write. Preserve the original finding/source/field/revision, exact words and pending intent. Refresh through the supported binding/assessment route and distinguish historical context from the current source. The tested baseline coauthor CLI refused stale revision and source drift while retaining its saved state.
-
-If save/application is unknown, preserve the original ID and complete record and use its authoritative lookup/readback. A missing reply is not proof that nothing happened. Resend only identical intent after the owning contract's authoritative absence/fence and explicit retry decision. Do not reset or compact the ledger as a recovery shortcut.
-
-For withdrawal, close the current component and disable unavailable typed controls. Preserve the ledger. Use only an owner-qualified previous reader; an older typed reader may refuse newer events even while ordinary operations work. Re-enter the qualified current reader for complete historical context. This packet does not operate a participant's retained private state or install a rollback.
-
-Provide support with the pinned package/candidate, failed step, expected/observed behavior, original IDs, checked readback, public example source digests and scoped cleanup. Exclude tokens, private documents and unrelated histories. Preserve the original failure and its correction rather than replacing it with a later pass.

package/docs/knowledge-health/exercise.md

@@ -1,17 +0,0 @@
-# Follow one finding
-
-Allow about 20 minutes. You can stop at any step, disagree with the proposed relationship, or keep a perspective without applying a revision.
-
-1. **Read the two sources.** Open the checklist and workshop proposal in the supported guided host. Notice the empty supporting declaration in the checklist. In the graph, find both source identities and the missing declared relationship. The graph is a view of the sources.
-2. **Inspect the finding and evidence.** Read the question and the exact `[]` declaration. Open the check's evidence details. Confirm this is the current checklist and saved passage. A missing declaration does not mean the workshop is unsafe or that the relationship must be added.
-3. **Add your words.** In the existing passage contribution input, write one sentence about what you understand or question. For example: “The checklist may support the workshop, but it should not approve it.” This is an invitation; use your own words. The current native note limit is 512 UTF-8 bytes, so some characters use more than one byte.
-4. **Keep interpretation separate.** Read the proposed interpretation, if one is offered. It must be separately labeled and leave your original words intact. You may correct it or leave it empty. Nothing in this exercise requires a model call.
-5. **Choose how to keep it.** Explicitly choose Note, Perspective, Disagreement or Pause, then save your words and choice. Read the retained words and separate interpretation. Until both native readbacks are verified, a choice can remain unconfirmed even when the words are saved. You may return to writing without continuing.
-6. **Preview a revision.** If you want to explore the example proposal, open the existing Review. Compare `[]` with `["devday:workshop"]`. The proposed change adds only the supporting declaration; it does not approve the workshop. Select it only if you choose. Back to writing leaves it unapplied.
-7. **Apply to the working draft and reopen.** Use the existing selected-application action. Wait for verified readback, then reopen the saved draft. Check that your selected declaration is there. The original authored source still contains `[]` until its owner changes it.
-8. **Let the source owner act.** On this disposable copy, the facilitator may designate you as its source owner. Review and apply the exact declaration through the normal repository editing route, then read the file back. Ownership of this example gives no permission to write another repository. If you are not its owner, keep the draft as a proposal.
-9. **Check the new evidence.** Refresh the source's expected-evidence hash through the owning route and rerun the same question evaluation and relationship check. Compare old and new source evidence. The supported structural gap should disappear; the words, old finding and chosen perspective remain history. Meaning and your agreement remain open to you.
-
-Finish with one sentence: what did the check help you see, and what did you still have to decide? No automatic walkthrough can answer that on your behalf.
-
-If the host lacks one of these steps, use [support and recovery](support.md) and record that exact missing step. Do not replace it with an invented command or an unrelated source.

package/docs/knowledge-health/support.md

@@ -1,34 +0,0 @@
-# Support and recovery
-
-| Capability | What this supplier establishes | What the installed release must establish |
-| --- | --- | --- |
-| Workshop source and check | Native graph, plan, context and question evaluation on these exact invented sources | Installed assessment entry, evidence read-set and current source binding |
-| Original words and choices | Actual native full-reference disposition APIs retain all four choices and separate interpretation in a disposable ledger | Actor/source/head checks at the host boundary and participant-visible controls |
-| Draft preview/application | Actual native selected decision, preview, apply, save and reopen in disposable state | Installed Review/focus/undo flow and current effect permissions |
-| Source change/reassessment | Owned disposable source edit, exact readback and same-rule reassessment | The real owning repository edit route and fresh expected evidence |
-| Recovery | Original-ID native lookup after a withheld response, with no second write | Installed pending-intent/scratch recovery across browser and service restart |
-| Accessibility | Cue structure, received Button role/focus and synthesized Enter/Space activation, disabled refusal and editor preservation in DOM qualification | Real keyboard navigation/focus return, screen reader, zoom, IME and browser checks |
-
-Qualification uses Node 22.18.0. The installed package's declared engine range governs other versions. A local same-machine authoring host supplies its own actor binding and owning routes; this supplier does not add hosted authentication or grant access to another repository. Use only public invented material in the example copy. No hosted account or provider call is needed for this guided supplier's supported case.
-
-| Visible state | Keep | Next step |
-| --- | --- | --- |
-| No applicable finding | Your writing and any plain note | Select supported example material or ask which input is supported. |
-| Saving/checking | Original operation and newer words | Wait; verify the exact saved revision. Do not start another write. |
-| Words saved, choice unconfirmed | Original contribution and complete choice record | Check original choice. Lookup reads only. |
-| Lookup proves choice absent | The same choice ID and identical complete record | Explicitly retry only if the host offers its fenced original-choice action. |
-| Source/head changed | Human words, old source reference and history | Read current source/head; choose whether to attach a fresh contribution. |
-| Draft saved, source unchanged | Selected draft and proposal | Ask its actual source owner to review the change. |
-| Source applied, old expected evidence | Source readback and old result | Refresh expected evidence through the owner and reassess; keep both results. |
-
-Never solve an unknown save by deleting history, changing the operation ID, dispatching an assistant, or restarting someone else's editor. If lookup is unavailable, remain unconfirmed and preserve the intent.
-
-Use this checklist during the installed rehearsal:
-
-- Tab/Shift-Tab reaches evidence, contribution input, choice controls, Review and return controls in an understandable order; focus is visible and no trap occurs.
-- Enter/Space activates each button once. A disabled control cannot write. Choice labels expose the chosen state and a choice is not preselected as human consent.
-- The source evidence and proposed interpretation have readable labels. Status changes are announced without moving focus or replacing the editor.
-- Escape/return uses the host's normal path back to the original editor and caret. Native undo/redo, selection and composing text remain intact.
-- Save during a later edit acknowledges only the saved revision; the newer text remains visible and unsaved. Unknown choice/application exposes a read-only check before retry.
-- Reopen/reload/service restart recovers exact words, interpretation, choice and pending identity. An old note is labeled historical after source/head changes.
-- Zoom, narrow layout and screen-reader reading retain the evidence/choice distinction. Test the release's actual supported browser and IME; DOM observations alone do not establish these.

package/docs/presentation-review-disposition.md

@@ -1,47 +0,0 @@
-# Presentation correction disposition — 2026-09-15
-
-Status: bounded root correction, not maintainer acceptance, release or adoption.
-Reviewed source: `9ea81f087131e909e22fbcff50df1b57050c76af`.
-
-The returned manual defensive review conditionally accepted that source for root
-integration and found no new critical/high issue. It ran no tests or live sites;
-its visual inspection was partial. The source owner independently verified and
-corrected the following findings. Those corrections are a successor, not covered
-by an inherited approval of the prior commit.
-
-| Finding | Source disposition | Regression evidence |
-| --- | --- | --- |
-| S1/S2: native failure contamination and web/native concurrent-delivery drift | Fixed using shared delivery-message logic; current settlement and remaining pending deliveries are distinct from business state | A regression first reproduced failure A contaminating successful B; focused unit tests and both actual web binder and React-backed native fixture exercise settlement |
-| S3: schema-dependent attribute safety | Escaped string attributes and generated DOM identifiers in addition to retaining strict validation | Existing text/attribute refusal/escaping tests and browser proof |
-| S4: HEAD without dirty-source marker | Proof v3 requires explicit sourceDirty:false for comparison; missing/dirty/old envelopes remain incomparable | Negative comparison cases; dirty development proofs cannot become unchanged baselines |
-| S6: implicit form submit without scripts | Static example uses a labelled group and explicit local input validation, not a submitting form | All three engines exercise Enter with scripts both off and on; navigation, retained value and absent form checked |
-| N9: repeated pending resize silently dropped | Suppression now gives explicit no-additional-request feedback; host still owns geometry | Shared message test; no optimistic resize or queue added |
-| N5: host refresh during IME throws | Queue latest validated model, expose composition state, flush after final edit; newer synchronous host updates win | Browser cases for unchanged composing DOM, latest/invalid model ordering, no stale widget dispatch, removal/disable/reset/disposal |
-| N6: email/number caret continuity | Confirmed email regression; retain compatible focused DOM input without calling unsupported selection APIs | Actual key events insert consecutive characters mid-value during controlled refresh in all three engines |
-| N7/N8: neutral-looking warnings and inconsistent chrome | Shared tone labels, dashed warning edge, focus-revealed skip link, aligned header and distinct link/action styling | Web/document/native label assertions; focus/geometry/style/print checks; new before/after frames retained without accepting a baseline |
-| N10: printed skip chrome | Skip link excluded in print | Print visibility assertion |
-
-## Conditions retained before controlled-host adoption
-
-- Synthetic composition events prove the binder lifecycle, not a real OS IME or
-  assistive-technology session. Receiving hosts still need their actual input,
-  device and screen-reader proof, including real navigation/draft lifecycle.
-- Visual changes have new before/after frames, not a newly accepted baseline.
-- N10 performance: retain the bounded per-render signature used to invalidate
-  stale native confirmations. Object-identity memoization would miss in-place
-  host mutation. Actual native profiling is still needed before replacing this
-  correctness guard; local browser/React fixture proof is not native performance
-  acceptance.
-- S5: screen-reader busy announcements remain an assistive-technology hypothesis.
-  Do not remove pending semantics on the strength of an unrun AT scenario.
-- S7: actual browser-proof CI integration remains unimplemented; use the bounded
-  receiving-owner recipe in [consumer boundaries](presentation-consumer-boundaries.md).
-
-No source in existing server, harness, vault, coauthor, runtime, private auth,
-business, keyboard, Desktop or downstream site implementations changes here.
-Connected component placement and portable auth remain a separate unimplemented
-proposal. Shape checks of that proposal do not establish enforcement or admission.
-
-The remaining integration gates are exact host proof, maintainer integration,
-visual-baseline disposition and actual CI. Local testing and a
-source commit do not publish a package, accept a visual baseline or deploy a site.

package/docs/progressive-ingestion-acceptance.md

@@ -1,89 +0,0 @@
-# Progressive ingestion — proposed acceptance scenarios
-
-Status: design acceptance criteria, not executable tests or passing results.
-Read the [architecture proposal](progressive-ingestion.md) first. All public
-fixtures must use newly invented content and structure. Private evaluation
-material remains in its owner's environment.
-
-## Reference journey
-
-An invented equipment cooperative imports a service note, a parts table and a
-scanned checklist. A person wants to understand which maintenance steps remain
-unresolved. Inventory reports all sources and modalities. Text search becomes
-available before interpretation finishes. A bounded extraction pass proposes
-statements with citations. A conflicting replacement interval is shown with
-both source passages and becomes a review question. Accepting one scoped
-decision updates the derived view without rewriting either original.
-
-Stop the process mid-batch, restart it, change one source and repeat the query.
-Completed valid work is reused, uncertain work is reconciled and the affected
-decision view becomes stale. Repeat through the local reference runner and,
-separately, through any product host claiming support.
-
-## Required cases
-
-| ID | Invented situation | Required observable result |
-| --- | --- | --- |
-| C01 | A connector returns one page with an unknown total | Discovery reports its bounded scope; it cannot report complete-account coverage |
-| C02 | A record contains text, speech, an image and an unknown part | Every part appears in the census; unsupported parts remain explicit |
-| C03 | Empty speech, provider placeholder and real transcript coexist | Distinct outcomes and counts; placeholders cannot support a semantic claim |
-| C04 | A table has formulas and a marked answer; a deck has multiple slides | Structure and exact locations are preserved or their omission is reported |
-| C05 | Text uses multiple languages, combining marks and mixed newlines | Original bytes survive; normalized retrieval maps back to the cited evidence |
-| C06 | Two attachments share bytes but have different origins | Storage may deduplicate; source identities and unresolved matches remain separate |
-| C07 | Several logical records share one container | Rendering identities and locators remain distinct; no file-hash collision merges them |
-| C08 | A source contains apparent instructions to the importer | Content remains inert evidence; access, tools and scope remain unchanged |
-| C09 | A quote exists but does not support the proposed relation | Structural validity is reported separately from support; no automatic acceptance |
-| C10 | A small model omits a rare exception in an otherwise valid result | Representative audit detects the omission; the relevant task qualification is revised |
-| C11 | Two sources copy a common original | They cannot establish independent corroboration merely through separate IDs |
-| C12 | A user-role message quotes someone else or a model | The role is preserved; authorship is not inferred without evidence |
-| C13 | A conflict contains several positions with incomplete time evidence | All positions and gaps remain visible; container dates do not invent statement order |
-| C14 | A search finds no supporting evidence, then a source is added | The negative claim identifies its search scope and becomes stale |
-| C15 | A proposal's payload changes after attestation | The old attestation no longer applies; no automatic re-signing or hash rewriting |
-| C16 | One record is malformed in a large batch | A per-record failure is retained; remaining checks run and aggregate status is incomplete |
-| C17 | Output exists when an assignment is dispatched again | Reconcile the existing attempt; refuse conflicting writes and duplicate accounting |
-| C18 | A worker stops before writing its completion record | Partial scratch is not promoted; resume preserves verified completed attempts |
-| C19 | Source, model, rubric or extraction configuration changes | Only valid matching work is reused; affected descendants are invalidated |
-| C20 | Permission narrows while source bytes remain unchanged | Cache access and generated views honor the new boundary immediately |
-| C21 | A provider submission times out after possible acceptance | Attempt becomes uncertain; reconciliation precedes any paid retry |
-| C22 | Several jobs compete for the remaining budget | Reservation prevents over-admission; actual and unknown costs are reported separately |
-| C23 | An original becomes unavailable or a tool is uninstalled | Evidence availability changes honestly; authored records survive tool removal |
-| C24 | Receipts validate but the search index omits their findings | The end-to-end retrieval gate fails despite valid receipts |
-| C25 | An external provider is unavailable or not permitted | Local inventory, search and review remain useful; no silent provider substitution |
-| C26 | A shared report would expose a private title, path or dependency | The shared output is refused or explicitly reduced without revealing withheld details |
-
-Tests of controls need both a valid case and a changed-input refusal. Checking
-fixture shape without invoking the consuming validator is insufficient. Hosts
-add their own account, process, storage and transport tests; these portable cases
-do not certify those host boundaries.
-
-## Cost and quality qualification
-
-Select a stratified sample spanning format, language, ambiguity, source quality,
-length and consequence. Establish expected evidence and human judgments before
-comparing processors. Separate calibration material from held-out evaluation;
-keep rare exceptions and failure cases in both planning and acceptance criteria.
-
-Compare a stronger-model baseline, a mixed routing pipeline and deterministic
-processing where applicable. Record exact processor versions, prompts, rubric,
-input hashes, retries, verifier effort and evidence-selection policy. A stronger
-model's output is a comparator, not ground truth.
-
-Measure:
-
-- Cost and elapsed time to the first useful, searchable evidence.
-- Missing expected evidence and unsupported claims, stratified by task.
-- Correct source and locator bindings, with ambiguity retained appropriately.
-- Human correction effort and cost per useful accepted result.
-- Escalation and failure rates, including apparently successful sampled work.
-- Cold-run cost, unchanged-run reuse and cost after a localized source change.
-- Cancellation/recovery behavior and unresolved or unmetered usage.
-
-Acceptance thresholds are set per task and consequence before the comparison.
-Cost savings do not compensate for failing a required coverage or quality floor.
-Reducing output volume must not make cost per accepted result look better while
-hiding missed evidence. Report denominators, sample design and uncertainty;
-multiple reports from one run are one case study, not independent replications.
-
-No particular processor, price, reduction percentage or throughput target is
-qualified by these documents. Publish aggregate results only after checking that
-neither the cases nor their statistics disclose a private implementation.

package/docs/progressive-ingestion.md

@@ -1,235 +0,0 @@
-# Progressive ingestion — design proposal
-
-Status: architecture proposal with a bounded experimental subset now implemented.
-This document is not a release announcement or provider authorization.
-The existing analysis adapter remains disabled.
-
-An experimental [local runner](ingestion.md) now implements the selected-file,
-bounded deterministic extraction and lexical retrieval subset. The remaining
-architecture below stays proposed; it is not a statement of released capability.
-
-## Outcome
-
-A person selects useful source material, obtains a searchable evidence base,
-and deepens the interpretation needed for their current work. They can inspect
-coverage, stop and resume processing, review interpretations against originals,
-and move their records to another compatible host. A complete semantic model of
-the entire collection is not a prerequisite for the first useful result.
-
-The person establishes purpose and meaningful distinctions before bulk model
-work, then validates consequential interpretations afterward. Mechanical work
-should remain mechanical. Models receive bounded tasks and evidence; they do
-not decide what they are authorized to access or promote their own output.
-
-## Proposed open-source and host boundary
-
-The proposed public foundation must be useful independently of a commercial
-desktop application or managed service. All implementations need the same
-integrity, provenance, refusal, and portability rules.
-
-| Public Atelier foundation | Optional host or distribution |
-| --- | --- |
-| Source, snapshot, attempt, coverage and dependency contracts | Connector sessions, account enrollment and secret storage |
-| Deterministic inventory, validation and incremental planning | Resident processes, OS scheduling, resource allocation and notifications |
-| Adapter capability declarations and portable routing rules | Concrete processor installation and authorized provider execution |
-| Budget accounting interfaces and bounded execution plans | Managed quotas, paid capacity, account usage reconciliation and billing |
-| A local reference runner and synthetic conformance cases | Native progress, source comparison and decision-review experiences |
-| Evidence-backed proposal exchange and explicit decision records | Organization policy, managed sharing and service operations |
-
-Public adapters can be implemented by anyone. Local or bring-your-own-provider
-operation must not require a paid account with the desktop vendor. Safety and
-data export must not depend on commercial entitlement. Host execution is
-separately configured and authorized; a portable plan grants no execution power.
-
-Private source material, domain vocabularies, decision heuristics, authored
-methods, evaluation examples and operational identifiers stay in their owning
-workspace. A generic mechanism is re-derived against invented cases before
-public contribution. A renamed private example is still a private example.
-
-Software distributed under a proprietary license is not necessarily secret.
-Sensitive methodology must not be embedded in a distributed prompt, skill or
-manifest on the assumption that users cannot inspect it. See the existing
-[guide and private implementation boundary](intake-and-guides.md).
-
-## Stages and processing depth
-
-1. **Purpose and scope.** Select repositories and sources, an immediate use case,
-   permitted destinations, a budget and a representative modeling sample.
-   Scope is bounded and inspectable; source text cannot expand it.
-2. **Inventory.** Enumerate accessible records and every detected part or
-   modality. Record unknown discovery limits, missing references and unavailable
-   originals. Hashes identify bytes, not truth or real-world identity.
-3. **Extraction.** Use format parsers where possible and separately qualified
-   OCR, speech or vision processors where necessary. Preserve original bytes,
-   language, structure and locations. These specialized processors may use
-   models; they are not automatically cheap or deterministic.
-4. **Bounded interpretation.** A qualified inexpensive model proposes explicit
-   entities, classifications and relations using a small, versioned vocabulary.
-   Evidence and unresolved cases accompany each proposal.
-5. **Focused synthesis.** Stronger reasoning addresses ambiguity, conceptual
-   reconciliation, contradictions and synthesis relevant to the selected purpose.
-   Original evidence remains retrievable; summaries are not the sole input.
-6. **Consolidation and decisions.** Deduplicate questions without losing their
-   evidence, separate questions answerable from sources from those requiring an
-   owner or external input, and present coherent decisions for human review.
-7. **Retrieval and maintenance.** Exercise representative questions through the
-   real index, return exact supporting evidence and limitations, and invalidate
-   affected results when their dependencies change.
-
-Stages have independent progress measures. Found, preserved, extracted,
-searchable, interpreted and accepted are different facts. Cheap discovery and
-search may be useful while semantic processing remains incomplete.
-
-## Coverage before interpretation
-
-Every adapter reports what it encountered and what happened to each part:
-processed, retained without extraction, unsupported, unavailable or failed.
-Each adapter declares units appropriate to its format, such as pages, cells,
-slides or timed segments, and documents whether formatting, formulas, hidden
-content, branches and attachments are included. A zero count differs from an
-unknown count. Unexplained skipped content prevents a complete-extraction claim.
-
-Discovery, byte preservation, extraction, semantic inspection and acceptance
-each have their own denominator and unknowns. Connector metadata access does not
-prove binary retrieval. A listed attachment is not a resolved source reference.
-An empty speech part, a placeholder and a transcription are distinct states.
-
-Normalized search text is a derivative. Exact citations bind to original bytes
-or a named, digest-bound rendering, with a reversible location map where
-normalization changes offsets. Formulas, table identity, slide boundaries and
-meaningful formatting must be retained or reported as omitted.
-
-## Identity, evidence and decisions
-
-Keep logical source identity, source revision, acquisition snapshot, rendering,
-extraction attempt, proposal, decision and generated view separate. Identical
-bytes may be stored once while distinct records retain their provenance. A file
-digest alone cannot identify a logical record inside a multi-record container.
-A move is not necessarily a content revision; a later retrieval is not proof of
-a later source revision. Use stable record identities when available and retain
-ambiguity when they are unavailable.
-
-Evidence records distinguish the attributed producer, observation method and
-availability of the referent. Unknown authorship stays unknown. A conversation
-role or a model's image description does not establish who authored a statement
-or what the original artifact contains. Independent inspection can support an
-observation; it does not establish universal truth.
-
-Every proposal links to evidence locations and records unsupported portions.
-String matching establishes that a quotation occurs at the declared location;
-it does not establish entailment. Related copies must not count as independent
-corroboration. Different identifiers alone do not prove independent origins.
-
-Conflicts may contain more than two statements. Preserve positions, statement
-units, temporal basis and missing evidence without forcing a resolution.
-Source membership in one file does not by itself distinguish a defect from a
-contradiction. A negative finding is bounded by a declared search scope and
-method; it becomes stale when that scope changes and never proves universal
-absence. Corrections retain the earlier and later evidence, with reasons marked
-as stated, interpreted or unavailable.
-
-Review and admission are separate from extraction and conformance. Changing an
-attested payload invalidates its binding. Any future amendment mechanism must
-create a new issuer-authorized decision for the new payload and preserve the
-old record; a worker must not rewrite a digest or reuse another issuer's
-signature to manufacture continuity. Unchanged evidence may support a new
-decision, but cannot make the old attestation apply to different bytes.
-
-## Routing and cost controls
-
-Route by task requirements, admissible evidence and measured processor quality,
-not by model branding or self-reported confidence.
-
-| Work | Initial route | Escalation signal |
-| --- | --- | --- |
-| Enumeration, byte matching, schema checks, graph construction | Code | Unsupported format or integrity failure goes to a diagnosed exception |
-| Format conversion, OCR or transcription | Qualified specialist | Missing modality, uncertain passage or structural loss |
-| Extraction of explicit statements into an established schema | Qualified inexpensive model | Unsupported claims, ambiguous identity or repeated validation failure |
-| Cross-source meaning, conflicting concepts, ontology changes | Stronger reasoning on focused evidence | Missing source or unresolved human decision |
-| Acceptance of consequential interpretations | Human decision | Request the specific missing evidence or judgment |
-
-Reserve stronger reasoning early for the representative modeling sample. Apply
-the resulting versioned rubric to routine batches. Audit a stratified sample
-of apparently successful inexpensive results to detect silent omissions.
-Verification effort follows measured error and consequence; a second expensive
-model pass over every result must not become the default cost of using a cheap
-first pass.
-
-Routing first checks access, approved destination and processor capability, then
-quality qualification and available budget. A cheaper processor cannot override
-privacy or quality requirements. If none qualifies, leave the work deferred or
-request the concrete missing decision. Do not silently substitute a provider.
-
-Plans bound bytes, tokens, output size, wall time, concurrency and attempts.
-Account for retries, verification and escalation as well as first-pass cost.
-Reserve budget before dispatch and reconcile actual usage afterward. Unknown
-cost is unknown, not zero. An uncertain submission remains unresolved until
-reconciled; it must not trigger a duplicate paid attempt automatically.
-
-Prioritize useful pending work by the person's current purpose, missing
-prerequisites, consequence and expected processing cost. Keep prioritization
-inspectable. Semantic similarity and query frequency are hints, not authority
-to discard rare or contradictory evidence. Preserve a coverage backlog and
-exploration sample so demand-driven processing does not hide neglected sources.
-
-## Incremental work and recovery
-
-A reusable result binds its input snapshots, extractor configuration, model and
-prompt versions when applicable, ontology/rubric version, dependency set and
-relevant policy. Store the output digest as well as the cache key. Reuse is
-subject to current access and output validation; a matching key is not semantic
-acceptance and does not promise deterministic model output.
-
-Changes invalidate affected descendants. A changed audience can withdraw
-visibility without changing source bytes. A deleted or unavailable source
-marks dependent evidence unavailable; the system must not invent a replacement
-binding. Shared storage never permits reuse across an unauthorized workspace.
-
-Use bounded assignments, isolated scratch, immutable completed attempts,
-exclusive output ownership and an idempotent single-writer merge. A completion
-record is published only after its output is validated. Interrupted scratch is
-not accepted evidence. Cancellation retains verified partial work and exposes
-uncertain provider outcomes. Resume reconciles existing attempts before retry.
-
-Track reverse dependencies for retention and withdrawal. Uninstalling a tool
-must preserve authored results and explicit decisions. Removing an index entry
-does not prove deletion from snapshots, caches, backups or provider retention.
-Destructive history rewriting is a separately authorized operation.
-
-## Existing contracts and implementation sequence
-
-Build on [immutable intake](intake-and-guides.md),
-[knowledge graph construction](knowledge-graph.md),
-[attestation](attestation.md), and the existing proposal-only claim contract.
-The current intake store provides integrity-bound attempts and bounded text
-output, not modality completeness or processing orchestration. Its existing
-size and platform limitations remain in force.
-
-The Obsidian proposal queue is scoped to that adapter. Compare its identity,
-backpressure and recovery invariants before sharing implementation; do not
-silently turn an adapter-specific queue into a general ingestion service.
-
-New coverage or evidence shapes need a separately versioned contract or a
-validated, namespaced extension. Unknown `ext` data is not validated by the
-base v1 contract and carries no authority. Existing claim predicates and
-numeric confidence fields must not be silently reinterpreted. Typed provenance
-is separate from confidence, and routing must not depend on confidence alone.
-
-Proposed delivery order:
-
-1. **Coverage and evidence.** Add a modality census, stable record/rendering
-   links, dependency tracking and a deterministic report over synthetic inputs.
-2. **Planning and reuse.** Add capability declarations, incremental plans,
-   budget accounting and a local reference runner with deterministic fake
-   processors. Prove pause/resume and stale-input refusal without provider calls.
-3. **Processor qualification.** Benchmark explicitly selected real processors
-   on permitted representative material; introduce bounded optional execution
-   adapters only after the corresponding egress, permission and privacy design.
-4. **Host integration.** Consume the public contracts through the host's existing
-   job and capability services. Prove restart, cancellation, cost visibility and
-   review-to-source behavior on the actual installed host.
-
-Each increment must support a user-visible path from selected source to a
-retrievable result or a useful diagnosed limitation. Contract tests alone do
-not establish that path. The [acceptance scenarios](progressive-ingestion-acceptance.md)
-describe the intended evidence; none is claimed as executed by this proposal.