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

package/docs/optional-ingestion.md

@@ -0,0 +1,83 @@
+# Optional ingestion suppliers
+
+Atelier's semantic runner remains the source of truth for ingestion attempts,
+captured output and proposed knowledge. The optional supplier APIs compose an
+ordinary host-selected extractor with Jev judgments, Graphify operations and
+LightRAG extraction or retrieval. No tool, account or Python SDK is required to
+import the JavaScript APIs. Importing them performs no extraction or network call.
+
+```js
+import {
+  createComposition,
+  createVanillaCompositionBinding,
+  createCompositionJudgmentBinding,
+  createGraphifyCompositionBinding,
+  createLightRAGCompositionBinding,
+  PRESENCE_PROFILES,
+} from '@mnstry/atelier/ingestion/optional'
+```
+
+Each binding accepts the consuming host's existing ports. The vanilla binding
+receives the semantic runner, the same-workspace intake capture callback and the
+host's selected extractor. Jev receives the existing decision contracts and
+prepared-request transport. Graphify and LightRAG receive an explicitly supplied
+native dispatcher. A dispatcher must preserve the original operation receipt,
+source bindings, artifacts, generation and retry-inclusive usage; an artifact
+digest alone is not an authenticated operation receipt.
+
+`createComposition` receives `bindings`, `operationRoles`, `invoke`,
+`readKnowledgeView` and `eligible`. These are the existing capability, knowledge
+and evidence owners' ports. The returned `execute` method accepts an explicit
+route, input and question. Every supported presence profile retains vanilla;
+select one extractor and one answerer for a route. Jev adds judgments rather
+than a second extraction pass. LightRAG's coupled native answer is a distinct
+route from retrieval followed by the ordinary answerer. Mere tool presence
+never invokes it or selects a fallback.
+
+The eight profiles are exposed by `PRESENCE_PROFILES`: vanilla alone, each single
+optional tool, each pair and all three tools. Missing selected operations refuse
+before execution. Accepted, current, located evidence can serve an answer;
+native labels and scores do not create canonical identities or accepted claims.
+Qualifiers, direction, time, negation and unresolved mappings survive ingestion.
+Partial failures retain their original outputs and unknown costs. Retrying,
+accepting knowledge, enabling a provider and publishing a projection remain
+decisions of their existing owners.
+
+## Native Python adapters
+
+The package includes the authored adapter source under
+`src/ingestion/optional/graphify/` and
+`src/ingestion/optional/lightrag/atelier_lightrag_supplier/`. It does not bundle
+the third-party SDKs or download them. A consuming host supplies its compatible
+Python runtime, separately installed SDK, pinned source, isolated storage and
+existing operation lifecycle.
+
+Graphify's `json_bridge.py` supports a host-owned persistent process so dependent
+operations share one supplier and generation. Preserve its separate source,
+cache and artifact roots. Its operations include extraction, query, topology,
+diagnostics, incremental updates and exports. The adapter uses POSIX filesystem
+locking; a host must qualify its actual platform before selecting this route.
+
+LightRAG's `LightRAGSupplier` accepts a native factory and role instrumentation
+before initialization, with one event loop per workspace and generation. It
+supports native insertion, custom knowledge projections, retrieval, coupled
+answers and storage lifecycle. Accepted canonical projections and editable
+native exploration use distinct workspaces. Native embeddings and model calls
+remain explicitly configured host capabilities.
+
+Source replacement, withdrawal, tool removal and recovery must use the current
+source/evidence owners and the host's existing lifecycle. Unknown native cleanup
+or provider execution is retained as unknown and grants no implicit replay.
+
+## Qualification
+
+`@mnstry/atelier/ingestion/qualification` exports the trial executor, accounting
+and independent-assessment receiving helpers. They preserve failed attempts,
+retries, shared costs and unknown accounting. Useful-answer scoring requires a
+separate verified assessor receipt; a task's own success claim does not count.
+
+The repository tests cover portable composition, all eight presence profiles,
+invented judgments, receipt boundaries and failure custody. These establish
+source behavior. Actual installed native workflows, provider authorization,
+independent semantic quality and measured time or cost improvements require
+qualification by the consuming host.

package/docs/personal-workspace.md

@@ -0,0 +1,257 @@
+# Personal workspace composition
+
+This module composes enrolled local repositories and private interpretation in
+one Atelier graph. The person supplies a private home outside every enrolled
+repository. Shared source files are never changed. Private authored inputs change
+only through an explicit, confirmed restore (see below).
+This is a local composition module. Host integration and release require
+separate acceptance.
+
+A manifest records enrollment, repository identity, and folder bindings. An
+overlay contains annotations, connections, collections, saved repository
+selections, and preferences. These closed documents grant no consent,
+permission, policy exception, disclosure, or effect authority. Valid graph
+metadata does not constrain a tool that can directly read the filesystem.
+
+## Files and API
+
+The caller passes `personalHome` explicitly; the module does not discover it
+from the environment or the current directory. The caller owns these files:
+
+- `atelier.personal.json`: `atelier-personal-workspace-manifest@v1`.
+- `atelier.overlay.json`: `atelier-personal-workspace-overlay@v1`.
+
+Both contracts live in `contracts/`. Paths in the private manifest are absolute
+canonical paths. Bindings must not overlap; enrolled roots must not nest.
+Each repo has a `repoId`, `root`, recorded `remote` (or `null`), and `enrolled`.
+Overlay references are closed `{ repoId, nodeId }` pairs. Repository IDs are
+stable local enrollment keys; matching a recorded remote is an offline change
+check, not proof of upstream membership or provider identity.
+
+The module entrypoint is `src/personal-workspace/index.mjs`; its public package
+subpath is `@mnstry/atelier/personal-workspace`. The API consists of fifteen exports:
+
+- `MANIFEST_SCHEMA` and `OVERLAY_SCHEMA`.
+- `PersonalWorkspaceRefusal`.
+- `loadPersonalManifest` and `loadPersonalOverlay`.
+- `resolvePersonalWorkspace`.
+- `planPersonalGeneration`, `materializePersonalGeneration`, and
+  `composePersonalWorkspace`.
+- `selectPersonalGeneration`, `selectionConfirmDigest`, and
+  `readPersonalSelection`.
+- `inventoryPersonalHome`.
+- `planPersonalRestore` and `restorePersonalInputs`.
+
+Package registration and installed-consumer qualification are separate from
+module source qualification. A registered package can be used as follows:
+
+```js
+import {
+  resolvePersonalWorkspace,
+  planPersonalGeneration,
+  materializePersonalGeneration,
+  composePersonalWorkspace,
+} from '@mnstry/atelier/personal-workspace'
+
+const resolved = resolvePersonalWorkspace({ folder, personalHome })
+if (resolved.status === 'resolved') {
+  const plan = planPersonalGeneration(resolved)
+  const written = materializePersonalGeneration(plan, { personalHome })
+  const result = composePersonalWorkspace({
+    personalHome,
+    generationId: written.generationId,
+  })
+}
+```
+
+`loadPersonalManifest` and `loadPersonalOverlay` read and validate private
+files. `resolvePersonalWorkspace` returns `resolved` or `none`; conflicting
+bindings refuse. `planPersonalGeneration` is pure and accepts only a resolved
+input from this module. These operations write nothing. Failures throw
+`PersonalWorkspaceRefusal`, with a stable `code` and a sanitized message.
+No paths, source excerpts, or graph diagnostic text are included in refusals.
+
+Of the composition operations, only `materializePersonalGeneration` writes. (The
+selection and restore operations below write their own records and, on an explicit
+confirmed restore, the authored inputs.) It creates
+`generations/<generationId>/` under the explicit private home. The id is a
+digest of canonical schema-tagged manifest and overlay inputs, declared
+stable references, and the canonical private-home location. Moving that home
+produces a new generation; historical generations remain untouched. Compose
+of a generation recording the old home refuses `generation-relocated`. Planning does not pretend to discover source nodes.
+Materialization writes exclusive files to a private staging directory, fsyncs
+them, verifies references through the canonical graph, and atomically renames
+the generation. A failed reference check discards only that attempt's staging.
+An interruption can leave a reported `stale-staging` directory; the module
+never prunes it or historical generations automatically.
+
+A committed generation contains `inputs.json`, `atelier.project.json`,
+`shared/atelier.project.json` for independent shared-source comparison, private
+Markdown under `overlay/`, and `generation.json` written last. The latter lists
+every other file and its digest. The whole inventory is checked; additional,
+missing, edited, or symlinked files refuse. Identical existing generations are
+reused; conflicting ones refuse `generation-overwrite-refused`. There is no
+mutable current pointer and no in-place schema migration.
+
+Compose revalidates current authored inputs, roots, identity, the generation,
+and every `(repoId, nodeId)` before returning a graph. Removing enrollment
+while retaining references refuses `retained-removed-reference` before
+planning. Missing or misowned IDs refuse `stale-reference`; path-derived IDs refuse
+`unstable-reference`. Targets must declare an explicit `kg.id`. A source file
+rename preserves references when its stable node ID stays the same. Changed
+inputs refuse use of an old generation; old bytes remain untouched. Authored
+note retention and recipient export are outside this module.
+
+## Selection, inventory and restore
+
+A generation is eligible only while it composes against the current authored
+inputs, roots and enrollment, so at most one generation is eligible at a time.
+These operations record a person's choices about that, and write only under the
+private home. They never delete authored inputs, generations or records; they
+remove only their own temporary files. Every failure is a
+`PersonalWorkspaceRefusal` with a stable code and no path.
+
+- `selectPersonalGeneration({ personalHome, generationId, confirm })` records an
+  explicit choice of the eligible generation. `confirm` is
+  `selectionConfirmDigest({ generationId, previous })`, computed over the head
+  that `readPersonalSelection` returns, so a choice shown against an older history
+  does not apply. Selections are append-only, numbered, hash-chained records under
+  `selections/`, each written completely before it is published, so a crash leaves
+  only a temporary file. Concurrent selections refuse `selection-concurrent`. An
+  ineligible generation refuses with its composition code, such as
+  `stale-generation`.
+- `readPersonalSelection({ personalHome })` returns the current selection and
+  whether it is still eligible. A selection never keeps a generation eligible after
+  its inputs, roots or enrollment change. The chain proves internal consistency
+  only: an edited record whose successors were not re-linked, a gap, or a
+  reordering refuses `selection-history-corrupt`. Truncating, or consistently
+  rewriting, any trailing run of records (up to the whole history) yields another
+  valid chain; it changes the returned `head`, so a host that needs to detect it
+  keeps the head it last observed and compares it.
+- `inventoryPersonalHome({ personalHome })` lists what these operations write, for
+  review before any deletion the person chooses: the authored files, each
+  generation with its eligibility, interrupted staging directories, every
+  selection and restore record, and any leftover temporary file, with sizes and
+  digests. An unreadable, oversized, non-regular or symlinked entry (authored
+  file, generation record or selection record) is listed without a digest, and a
+  corrupt selection history is flagged rather than failing the inventory.
+  Temporary files include restore aside copies (`.restore-<uuid>-aside-<file>.json`).
+  It is read-only.
+- `planPersonalRestore({ personalHome, generationId })` plans restoring the
+  authored manifest and overlay that an earlier generation recorded. The
+  generation's `inputs.json` must reproduce its id from this private home, or the
+  plan refuses `generation-corrupt`; an oversized record refuses
+  `generation-inputs-too-large`. **A restore never widens enrollment or
+  bindings:** a repository the target enrolls must be enrolled now with the same
+  root and remote, and every binding it declares must be declared now. Otherwise
+  it refuses `rollback-readmits-repository` or `rollback-identity-changed` (with
+  the repository ids) or `rollback-readds-binding`, before any write.
+  Re-admission is the person's fresh edit; afterwards the same restore is
+  evaluated normally. The plan validates the target files and carries a summary
+  of the enrollment and bindings it removes and whether each file changes. A
+  restore that only narrows proceeds. Restored files are written in the
+  generation's canonical form (sorted keys, no indentation), not the person's
+  original formatting; planning and restoring briefly write private `.validate-*`
+  and `.restore-*` copies of authored data, which are removed afterwards and
+  listed by the inventory if a crash leaves them.
+- `restorePersonalInputs(plan, { personalHome, confirm: plan.confirm })` accepts
+  only a plan returned by `planPersonalRestore`. It reads the current authored
+  files once, validates those exact bytes, requires them to match the plan, and
+  re-runs the widening check on them; inputs changed after planning refuse
+  `authored-input-changed`. It keeps those exact bytes in an append-only record
+  under `restores/`, stages and validates both restored files, then replaces each
+  by compare-and-swap: the current file is moved aside and verified to be the
+  bytes it read, and the restored file is linked into place, which fails if
+  another writer recreated the name. On any mismatch, or if the moved file cannot
+  be read (for example it is now oversized), it is put back, or kept as a listed
+  temporary file if its name was taken meanwhile, and the restore refuses
+  `authored-input-changed`. Writers that replace or recreate the file by path keep
+  their bytes. A writer still holding an open handle on the old file and editing
+  it in place can write into the moved copy, which a completed swap removes. The
+  name is briefly absent during each swap. A rerun after an interruption between
+  swaps completes the files not yet restored. If a crash leaves an authored name
+  absent while its moved copy remains, planning and restoring refuse
+  `restore-interrupted`. The moved copy is listed by the inventory, and the
+  restore record under `restores/` holds the replaced bytes, so the person can put
+  the file back before trying again. A restore does
+  not change the selection; selecting the restored generation is the person's next
+  explicit act.
+
+Retention follows the person's decision: withdrawn material stops being eligible
+immediately, while authored history, generations and these records stay until the
+person reviews the inventory and explicitly confirms deletion. No deletion
+operation is provided yet.
+
+## Canonical graph and offline checks
+
+Composition uses the existing supported project loader, project validation,
+and canonical graph builder. Generated project paths are explicit and
+relative to the generation, with a conservative private read boundary; this
+never upgrades source authority. The graph includes shared source nodes and
+private interpretation nodes, with declared `related` edges. Private aliases
+and preferences do not rewrite source titles, facts, or classifications.
+Private nodes are excluded from ordinary Markdown link scanning and targeting;
+only their explicitly declared stable references create edges. A second build
+through the same canonical API uses a generated config containing only shared
+roots, in the private generation. Shared nodes, edges, and link diagnostics must
+match the composed result, or `shared-facts-changed` refuses publication/output. Complex tags
+round-trip through block-list frontmatter. Blank, padded, and duplicate tags
+refuse `malformed-input` instead of being silently normalized. Untagged private
+nodes receive the
+fixed `personal-interpretation` tag instead of inferred shared-domain tags.
+Generated scalars escape Unicode line separators. Composition verifies every private
+node’s planned identity, title, classification, explicit ID, type, status, audience,
+tags, relations, and declared edges; a mismatch refuses `overlay-semantics-mismatch`.
+Saved views are stored selections, not executable queries or policy rules.
+
+Bounded local Git reads are required for identity and the canonical ignore
+census. No network, provider lookup, `gh`, Git fetch, hook execution, service,
+database, credential operation, or shell is requested. The module refuses
+ambient `GIT_*` variables, fsmonitor helpers in local, global, XDG, or system
+configuration, and failed independent
+ignore listings. It checks that ignored sources never enter the graph even
+when the shared builder's ignore call fails open, including ignored sidecars.
+An enrolled root must equal its Git worktree top level; a nested directory
+refuses `repo-root-mismatch` before planning or writes.
+Every module-owned Git probe disables fsmonitor. Its configuration probe uses
+Git boolean-or-string typing so a valueless enabled setting is refused too.
+On macOS, ignored-path comparisons normalize both Git and census spellings to
+NFC, including sidecar paths and parent directories. Observed remote URLs are
+sanitized before comparison; the authored identity must already be sanitized,
+without user information, query parameters, or fragments. Credential-bearing
+authored remote values refuse `remote-credentials-refused` and are never copied
+to generations or returned observations. Project inputs have pinned
+arguments and environment, no ambient overlays, and no path discovery.
+
+Private generation roots must be outside every worktree, verified by ancestor
+`.git` checks and a local Git probe. The overlay census must equal exactly the
+materialized overlay documents. Private roots must be owned by the current
+POSIX user and not writable by others. All roots, ancestors, and authored files
+must be free of symlinks. Windows private-root qualification is not implemented
+and refuses `private-root-unverifiable`.
+
+Current source evidence hashes regular files with 64 KiB reads rather than whole
+asset allocations. Unavailable or changing file evidence refuses `source-read-failed`
+without returning local paths. This observation is not a transactional source snapshot.
+
+## Evidence and limits
+
+The tests use invented temporary repositories and private homes. They verify
+canonical nodes and edges, unchanged source trees and authored inputs,
+determinism, removal, identity replacement, closed schemas, ignore failure,
+unsafe roots, corrupted generations, and interrupted writes. This proves the
+bounded module behavior, not installed host enforcement or human acceptance.
+
+`sourceRevisions` reports digests observed from the current canonical census
+after the build. Shared repositories remain live, mutable files: this is not a
+transactional snapshot or an upstream Git revision. Concurrent writers can
+change source bytes between graph reads. Consumers requiring an immutable
+source snapshot must supply one through a separately governed host boundary.
+Similarly, checks in this module are not an OS sandbox, defense against a
+hostile filesystem owner, or protection from concurrent root replacement.
+
+The returned coverage is `manifest-only`, with `enforcement: none` for direct
+filesystem access, disclosure, effects, and host sandboxing. A harness with
+repository access still needs the applicable host and runtime boundaries.
+Integration, independent review, hosted CI, publication, installation,
+consent/effect enforcement, and acceptance are separate gates.

package/docs/practical-judgment.md

@@ -0,0 +1,92 @@
+# Practical Judgment and practice adoption
+
+Practical Judgment supports deciding what matters and what is fitting in a
+particular situation. It also supports cultivation: contrasting cases, warranted
+exceptions, questions, distinct voices and reflection on consequences. A useful
+deliberation can remain open or produce an action without producing a rule.
+
+`@mnstry/atelier/judgment` validates portable cases and native architecture
+decision snapshots. `inspectPracticalCase` preserves purpose, values, evidence,
+alternatives, dissent, cultivation exercises and reconsideration conditions.
+It does not score wisdom. The invented workshop fixtures demonstrate an open
+deliberation and a decision whose implementation is still planned.
+
+## Architecture decisions
+
+`importArchitectureDecision({decision, sourceText})` verifies a declared native
+source digest. Repository identity, ADR identity and source location stay intact.
+The adapter does not allocate ADR numbers, authenticate an approver or infer
+implementation from acceptance. Decision status, implementation evidence and
+evidence currency remain separate. `renderArchitectureDecision` produces a
+readable snapshot; its text does not replace the source repository's native form.
+
+`prepareJudgmentContribution` preserves the typed case or decision inside an
+ordinary Knowledge contribution. Review and activation still use the existing
+Knowledge writer. `createJudgmentDependency` revalidates that typed payload and
+the accepted contribution before issuing the existing Build handoff. Decision
+imports additionally require matching native source bytes. The resulting
+handoff retains the native states; it grants no implementation or approval
+authority. Revisions use new Knowledge contributions and normal supersession,
+review and dependency reconsideration. Do not change an old record in place.
+
+## From feedback to intrinsic practice
+
+The [learning lifecycle](learning.md) captures an observation, proposes a scoped
+lesson, records an exact decision, then activates the accepted version for a
+named harness. `capabilityEventToLearningInput` bridges version-bound capability
+metadata into that lifecycle. It retains the reported cause, binding, release,
+session and evidence digest. It neither invents a user quotation nor certifies
+causality. A harness feedback wrapper can preserve causes that the older
+capability event vocabulary cannot express.
+
+For accepted instruction artifacts, use `atelier practice plan`, inspect the
+returned text and exact plan digest, then `practice apply`. Requests are JSON
+on stdin in the intended Git repository. Private state must be ignored under
+`.atelier-local/`. The request names `workspaceId`, `scope`, `harnessId`,
+`lessonId`, `target`, `slot` and `mode` (`adopt` or `retire`). Apply additionally
+names `confirm`, the current plan digest.
+
+The reference profile manages one marked block in a scoped `AGENTS.md` or
+`CLAUDE.md`. It preserves surrounding text, states applicability and exceptions,
+and leaves instruction precedence and tool permissions with the host. Skills
+continue through capability releases and Skill Steward; checks remain inert
+until an owning implementation explicitly realizes them. This adapter does not
+execute a lesson as code or update arbitrary configuration files.
+
+Re-plan and apply to adopt a reviewed revision into the same slot. Guidance is
+preserved literally, including dollar signs; other slots and surrounding text
+remain intact. Re-adopting unchanged guidance records the current adoption
+without exchanging the destination file, and interrupted recording can recover.
+
+Planning binds the complete current destination bytes and learning selection.
+Applying refuses local drift, unowned slots, changed scope, ambiguous markers
+and ineligible learning. The POSIX reference adapter uses non-overwriting
+creation or the existing atomic file-exchange primitive. Displaced bytes remain
+in private recovery storage. Unavailable exchange or volume mismatch refuses.
+An interrupted operation is inspected with `practice status` and resumed with
+`practice recover` using the pending plan digest. Concurrent changes remain
+visible for reconciliation. If the source differs from both planned states,
+`practice abandon` can retain the journal and recovery bytes without editing the
+source. It requires the plan digest and the current destination digest reported
+by status. Then prepare a new plan. Applied changes must be reconciled before
+retirement; never delete recovery state to force an apply.
+
+`practice context` takes target, slot, session, scope and harnessId. It returns
+only current selected guidance and writes a context-delivery receipt. The
+receipt means that the calling consumer received those exact bytes. A host must
+actually integrate this seam; it does not establish that an agent obeyed them.
+Assess changed behavior with applicable and inapplicable tasks afterward.
+
+Withdrawal immediately excludes future calls through this context API. A
+previously written instruction file still needs an explicit retirement plan.
+`practice status` reports that discrepancy. A host that reads the file directly
+does not inherit live withdrawal checks automatically. Separate repositories
+make separate adoptions; another repository's customization is preserved.
+
+## Open core and host responsibilities
+
+All local inspection, adoption, history and recovery are usable without a hosted
+account. Identity assertions and digests establish local consistency, not remote
+authentication. Production hosts supply their own identity, access, scheduling,
+actual conversation delivery and durable runtime acceptance. Personal or private
+learning is not implicitly exported to a public graph or capability package.

package/docs/progressive-ingestion-acceptance.md

@@ -0,0 +1,89 @@
+# 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.