testguard-cli 0.15.1 → 0.17.0

package/spec/GATE-SEMANTICS.md

@@ -1,5 +1,129 @@
 # Gate semantics
 
+## Declared claim origins
+
+Status rechecks every recorded automatic-discovery dependency hash, including
+negative candidate tests, barrels and resolver configuration. Edited, deleted,
+unreadable or non-regular/escaping inputs make the evidence stale without
+rewriting its verdicts. Legacy omission remains readable but does not establish
+a complete origin-policy freshness binding. Rechecking recorded dependencies
+alone does not detect a newly added test/configuration: native test-universe
+recomputation remains required before origin-policy activation.
+
+Canonical and recorded claim sources share the closed kinds `spec`, `adr`,
+`annotation`, `comment`, `manual`, `doc`, `bug`, `incident`, `review`, `inferred`.
+These are declarations, not authentication of independence, chronology,
+production occurrence or correctness. The optional reference remains opaque
+metadata (at most 512 characters); verification does not fetch it. Producer
+provenance and measured test independence are separate signals.
+Adding kinds does not change verdicts, baseline/fingerprint identity or default
+gates. Existing ranking weights stay unchanged; new kinds use the existing 0.9
+fallback, not an invented strength hierarchy. Existing documents remain valid
+under the candidate reader; older closed-schema readers reject new kinds.
+Optional `origins` summaries on evidence, status and brief have closed kind
+buckets and safe nonnegative integer counts. Distinct claim buckets plus
+`mixed` equal the claim total; record buckets equal the record total. Status
+uses `basis: declared`, omits records, has zero mixed claims and binds its
+total to current `counts.claims`, even when evidence is stale. Evidence and
+brief use `basis: recorded` and require record counts. Evidence validation
+recomputes from every actual record regardless of verdict: each claim ID
+counts once, with conflicting source kind OR reference counted as one mixed
+claim. Object-key order is not a conflict; absent and empty references differ.
+Brief totals bind to the complete summary, not its capped/filtered items.
+Status and brief omit the source projections needed to independently validate
+their kind split; arithmetic validity is not source authentication. Legacy
+documents without summaries remain valid; old closed readers reject them.
+Status supplies current declared origins once validated claims are available,
+including empty, unprobed, invalid-anchor and stale-evidence states. Probe
+evidence and evidence-backed briefs supply recorded origins from all records,
+including killed and non-killed records, before caps or baseline/floor filtering.
+Human status/probe/brief text and Markdown label the basis and print "declared
+origins, not authenticated independence". Evidence-free briefs and projects
+without a claims file omit the summary rather than inventing declarations.
+Probe JSON retains status's current declared basis; saved evidence has its own
+recorded basis. These informational fields do not change states, next actions,
+exit codes, fingerprints or default gates. Opt-in origin policy remains pending.
+
+## Explicit annotation authoring
+
+Ordinary `claims` reports a separate `annotationAdvisory` with distinct sorted
+`missingIds` and informational `notes`; status uses its existing informational
+`notes`. Missing links reduce discoverability and annotation reconciliation,
+not exact-anchor validation. Advice supplies `testguard claims --annotate` for
+read-only preview; it never changes state, next verification action, verdicts,
+source kinds or exit codes. Annotation-sourced missing IDs still retain the
+existing claims drift error. Scanned occurrences are lexical links, not proof
+of intent, source ownership or authenticated provenance.
+Status advisory scanning is bounded to 10,000 directory entries, 1,000 files,
+64 directory levels, 256 KiB per file and 2 MiB total read bytes. Read failures,
+unsafe file identities or limits produce unavailable advice, never a claim
+that an ID is absent from an incomplete scan. Verification state/next still
+comes from its existing inputs. For custom claims, preserve the original
+`--claims` argument when following the preview suggestion.
+Scanner and placement ID prefixes use mandatory separators between repeated
+alphanumeric groups, avoiding overlapping quantifiers on tokens lacking a
+hyphen without changing the supported identifier vocabulary.
+
+`claims --annotate` previews file-header placement without writes. Add `--apply`
+to explicitly apply a newly computed plan; a previous invocation's preview is
+not a saved approval token. Repeated/comma-separated `--claim` selects IDs;
+unknown or empty IDs are usage errors, never an implicit all-claims selection.
+Authoring flags are valid only on `claims`; `--apply` requires `--annotate`.
+Authoring rejects unrelated inspection/output switches and writes results only
+to stdout. It never updates claims metadata, evidence or baselines.
+
+The closed `annotations` document describes authoring, not verification. It
+contains selected IDs, admitted target/action summaries, refusals and, for
+apply, touched/verified/unchanged files and explicit failure/recovery details.
+It excludes source/proposed contents, inode identities, hashes and absolute
+source/root paths. Preview exits 0 when applicable, 2 when refused. Apply exits
+0 only for a fully verified apply (including idempotent no-op), 2 for refusal or
+partial failure. Invalid invocation exits 3. No authoring result changes probe
+verdicts, rank, coverage, source-kind declarations or authentication of intent.
+Failure reasons are stage-specific public summaries: raw syscall details can
+contain absolute input paths and remain private, never passed through to JSON.
+
+Placement supports JavaScript/TypeScript and Python file-level line-comment
+headers, not symbol ownership. Exact anchors remain checked without annotations.
+Every selected target must pass conservative path, regular-file, UTF-8/newline,
+anchor and size admission: 2 MiB per original/proposed file and 16 MiB aggregate
+charged before reads plus proposal growth. Any refusal blocks all writes.
+Preserve BOM, shebang, Python encoding cookies, newline style, inode and mode.
+Only leading line-comment headers are placement witnesses, not string contents.
+
+Apply reloads actual claims under an exclusive owned lock, replays all targets,
+and fsyncs owner-only originals/manifest outside the canonical project before
+writing. Recheck claims and targets immediately before each non-truncating
+descriptor write; verify output, distinguish potentially touched from verified
+files, and retain private recovery on partial failure. Reject the actual claims
+file as a target, root/descendant symlinks and recovery inside the checkout.
+Resolve parent aliases to bind the actual root. Never reclaim another writer's
+lock or automatically roll back over an editor's changes. Stage and fsync the
+final recovery journal before final naming. This is recoverable, not atomic:
+arbitrary same-inode editors and process/power failure can race or interrupt
+writes; directory durability across power loss is not guaranteed.
+
+## Fault-specific defender selection
+
+A fault's `defendedBy`, when present, overrides its claim's declaration.
+An explicit empty fault list requests discovery and never falls back to the
+claim. Without a fault override, a non-empty claim list is inherited; otherwise
+defenders are discovered. New evidence records `defenders.selectionSource` as
+`fault`, `claim`, or `discovery`, alongside the actual requested and resolved
+sets. Empty requests use discovery and carry `discovered: true`, including an
+explicit empty fault override. Non-empty requests are never marked discovered.
+Dirty-input preflight, runner ownership, mock-awareness, input hashing and
+baseline caching all operate on each fault's selected defender set.
+
+Changing requested globs, resolved files or selection origin invalidates verdict
+reuse. Legacy evidence remains readable but cannot authorize a new fault-level
+override. A strict resolved subset after a previous kill is reported by `claims`
+as a narrowing warning and requires re-probing; it is not a new verdict.
+Cost reports include per-fault recorded run durations and selection origin.
+Shared defenders identify the actual fault records that selected each file,
+including multiple faults within one claim. File costs remain overlapping upper
+bounds, not additive shares. Existing total/per-claim budget ceilings are unchanged.
+
 How a Guard-spec tool decides whether CI goes red. Shared by every tool that
 adopts the spec; each tool may add stricter rules, never looser ones.
 
@@ -87,6 +211,17 @@ Rules that follow from the table:
    the fault is probed again: the cost of re-measuring is a run, the cost of
    the other direction is a verdict nobody measured.
 
+   **Claim metadata is also an input to reuse.** The recorded claim id,
+   statement, severity, source (including its reference), and optional
+   producer must match the current claim. Object-key order is not a change;
+   field values and producer presence are. Metadata edits make `status`
+   stale and require a fresh probe, even when the fault and defender inputs
+   are identical. A reused record must never be silently relabelled as a
+   different requirement or origin. Legacy records remain readable; missing
+   metadata cannot establish equality with a current declaration. This
+   does not change verdicts or baseline fingerprints, and a source label
+   still does not authenticate independent intent.
+
 9. **The fault must be the code that ran.** A green baseline proves the
    harness is not reporting everything as broken. It proves nothing about the
    opposite direction: a fault the interpreter never executes leaves the
@@ -446,6 +581,69 @@ Security- and money-shaped path names are explicit tie-breaking signals, never
 semantic claims about a file. Churn, path risk and claim coverage remain raw
 facts: they are never collapsed into one health score.
 
+### Intent-first scaffold authoring
+
+Unannotated generated draft groups use unfinished `TODO-CLAIM-N` identifiers,
+not file/function-shaped names. Allocation is deterministic in scan order and
+reserves explicit annotations and supplied existing IDs before choosing ordinals.
+It never copies unrelated existing metadata into a generated placeholder. Explicit
+claim IDs/annotations retain their existing behavior; neither annotations nor
+placeholder IDs authenticate intent. Grouping remains mechanical candidate
+organization, not invariant ownership. Sweep's pooled allocator keeps repeated
+per-file placeholders distinct without changing fault content. Existing claims
+and recorded evidence are not renamed. The claims schema/validator is unchanged:
+these are valid draft IDs and still require supplied intent and review/probing.
+
+Explicit `scaffold <source...> --into <existing-draft.json> --claim <ID>` appends
+mechanically derived faults only to that existing selected claim. Preview JSON
+is a conforming claims document (the existing claims schema and validator), not
+verification evidence. `--json` creates no files, locks or recovery. Without it,
+only the explicitly selected disposable draft is updated; unchanged repeats
+preserve exact bytes/mtime. Supplied statements/origins/metadata and existing
+faults/sibling claims remain intact. Review and probe are still required.
+
+`--into` is scaffold-only, singular and requires one nonempty existing claim ID
+and at least one source. Repeated/comma selections, `--out`, `--claims` and any
+explicit unrelated option refuse with usage exit 3 before reading/writing.
+Help/version retain their normal early-exit behavior. Ordinary scaffold remains
+one-file; annotation `--apply` retains its separate claims-only meaning.
+
+Refuse canonical `testguard.claims.json` names and built-in evidence/baseline
+destinations, unsafe aliases/symlinks/hardlinks/nested projects and nonregular
+inputs. Admission limits are 32 sources, 2 MiB per source/draft, 16 MiB aggregate
+source bytes, 4096 generated proposals and 2 MiB serialized output. Caps refuse,
+never truncate proposals. These are not whole-command performance guarantees.
+
+Changed drafts require a cooperative owned exclusive lock, current input replay,
+external private original/started/result recovery journals, nofollow descriptor
+publication through `writeSpecDoc`, short-write handling, fsync and exact
+byte/schema/path/source verification. Refusal, stale inputs, partial writes,
+verification or cleanup/journal failure exit 2, report recovery when available,
+and never print updated success. No automatic rollback, stale-lock reclamation,
+atomic multi-file snapshot or power-loss transaction is promised. Exit 0 means
+authoring completed, not defended coverage. Private recovery is not evidence.
+
+Sweep pools per-file drafts before selection. Repeated claim IDs from equal
+basenames/functions or annotations do not merge unrelated claims: reserve all
+original IDs, then allocate unused numeric suffixes to collisions in full
+target-path/original-ID order, within the existing 128-character limit. Metadata,
+fault IDs, injection anchors and defenders are preserved. Drafts, selected probe
+claims and finding lookup share these identities. This affects fresh collision
+cases only; existing documents, verdicts, caps and exit rules remain compatible.
+
+Scaffold's mechanically generated new claims declare `source.kind: inferred`,
+including proposals grouped by an annotation. Their TODO asks for intended
+observable behavior from a requirement, ADR, bug or incident: inputs, expected
+outcome and forbidden outcome. Existing supplied claim metadata retains its
+statement and declared origin under the existing `--claim` rules. Derived fault
+provenance remains derived. No automatic source promotion or canonical write.
+
+Human CLI, status authoring actions and the installed skill hand off independent
+intent authoring. Record a supplied source kind/ref; when unavailable keep
+inferred. References and annotations do not authenticate intent and are never
+fetched. Passing tests do not establish independent intent. State, next action,
+verdict and exit-code semantics are unchanged; this is authoring guidance.
+
 When existing evidence is clean but more source modules are unclaimed than
 claimed, the next action is to scaffold the highest-churn unclaimed module.
 Earlier correctness states still win: invalid anchors, stale evidence and
@@ -559,6 +757,48 @@ evidence; they simply do not turn CI red.
 
 ## Exit codes
 
+### Explicit declared-origin policy result contract
+
+Optional `originPolicy` on evidence, status and brief (and status's probe `run`)
+records an explicitly selected eligible-kind set, not authenticated independence.
+Legacy absence is not a pass. `probe --require-origin <kinds>` selects a
+repeatable comma-separated nonempty set from the closed source vocabulary.
+It requires a complete current-project run with confirm >= 3 and refuses
+`--claim`, `--allow-empty`, explicit `--ref` and `--ignore-dirty` as usage errors
+before loading or writing. No policy is inferred when the option is absent.
+After measurement, the command reloads current claims and collects the current
+native runner universe under the same command budget, then binds targets,
+resolved defenders and current discovery dependencies. Missing bindings or
+discovery failure yields unavailable; custom/static runner universes cannot
+certify this boundary. Expired command budgets still write no partial result.
+This is point-in-time admission, not an atomic filesystem snapshot. Stored
+results are not freshness authority. Offline status reuses only the recorded
+eligible-kind selection, recomputes current declarations/complete identities,
+and marks freshness unavailable without executing native discovery. This is
+an audit projection, not implicit activation of a new gate: the existing
+status state, next action and exit remain unchanged. Briefs preserve the
+recorded policy before baseline filtering or item caps, labeled recorded-run
+only and not current freshness. No absent policy is synthesized. A zero-item
+cap cannot turn unproven faults into an all-defended message.
+
+The closed result carries `state` (`passed`, `failed`, `unavailable`), sorted
+unique `eligibleKinds`, current `claims`/`faults` denominators, sorted unique
+`ineligibleClaims`, unique `nonKilledFaults` (`claimId`, `faultId` only), and
+sorted unique `unavailableReasons`. References and paths are excluded.
+Refusal reasons require unavailable; otherwise any ineligible claim or
+non-killed fault requires failed. Only a nonempty failure-free universe can
+pass. Baseline debt and severity floors cannot suppress policy failures.
+
+Evidence validation binds actual non-killed identities, and, for an available
+policy, unique recorded denominators, recorded eligibility, unmixed origins and
+confirmed injection. Validation cannot authenticate current metadata or disk
+freshness: evaluation must separately bind the complete current fault universe
+and existing input freshness. Projected status/brief bind denominators, not
+hidden source declarations. Brief policy describes its recorded run only.
+Completed probe JSON with unavailable policy exits 2; failed policy or ordinary
+new findings exits 1; passed policy without ordinary findings exits 0.
+Partial/provisional invocations cannot carry an origin policy.
+
 | Code | Meaning |
 |---|---|
 | `0` | No new gating findings at or above the severity floor. |
@@ -577,3 +817,79 @@ output is the existing `no-claims` status document, without run metadata;
 it never reports a clean measurement. Missing or invalid claims still fail,
 and selected claims cannot be silently skipped. Run `gate` separately to
 enforce coverage of changed files during adoption. Integrations must opt in.
+
+## Read-only authoring input (candidate)
+
+`authoring-input` is metadata-only inspection, never claims or evidence. Its
+closed purpose/verification/next fields explicitly state that verification was
+not performed and independent intent remains to be supplied. Documents expose
+only bounded project-relative file/hash/byte metadata, not text or absolute
+roots. A digest or schema-valid report does not authenticate intent or freshness.
+
+Fix inputs retain exact same-width commit/parent/path identities, untrusted
+single-line subjects, selected root/nested scope and full partition accounting.
+Visible rows exclude private/delegated names; their count stays in the total.
+Deleted and unsupported rows cannot become supported source. Validators reject
+duplicate/unsafe/private paths, inconsistent status/mode/zero-ID relations,
+disposition/count mismatches, unsafe subjects and resource overruns. Empty
+documents/inventories are admitted input metadata, not successful verification.
+Readers cannot infer actual history completeness or current input admission
+from shape alone; the runtime must use admitted local inputs without promotion.
+
+`scaffold --from-document <local-text-path>` or `--from-fix <full-commit-ID>`
+selects exactly one read-only authoring input. Both token dispatch and direct
+handler entry reject repetition, mixed modes, positional sources and unrelated
+explicit options (only JSON/help/version may accompany selection). Normal
+help/version early exits remain unchanged. Usage refusal exits 3; input admission
+or validated planning failure exits 2 with no success stdout. Success exits 0
+for inspection only, never coverage. Both JSON and human modes are stdout-only.
+JSON uses the validated metadata-only report; human rendering omits text,
+subjects, absolute roots and historical filenames while retaining full fix
+partition counts. Both name verification as not performed and require supplied
+independent intent before reviewing/probing faults. One elapsed budget covers
+input reads and validated serialization; scope resolution never retries with
+fresh time. Existing ordinary scaffold/append/probe behavior is unchanged.
+
+## Resource controls and measurement
+
+Built-in runners default to one worker. `--workers N` raises the worker ceiling
+for Vitest, Jest and Playwright; `--serial` overrides it to one. Python remains
+serial and disables pytest-xdist without installing or enabling any plugin.
+Faults and mixed-runner partitions remain sequential. This is a worker ceiling,
+not OS CPU/memory containment; test-created threads, native libraries and custom
+`--runner-cmd` commands manage their own concurrency. Native discovery is bounded
+and uses one worker where applicable.
+
+Runner stdout is drained without retention; stderr retains only its last 65,536
+characters. Complete JSON reports are read under the existing 16 MiB discovery
+report admission limit. An oversized, unreadable or incomplete report is an error,
+never an assertion kill. No confirmation count or verdict rule changes.
+
+Cancellation terminates only registered children and their attributable process
+trees, waits up to one second for close, restores live mutations and removes the
+registered scratch worktrees. It exits 130 without publishing partial evidence.
+Reparented daemons remain outside the portable containment guarantee. Git
+subprocesses have a 30-second hard deadline; the whole-command budget remains
+cooperative around synchronous setup, and bounded OS cleanup can outlive it.
+
+Optional `run.measurements` records monotonic elapsed time, fresh runner execution
+time, invocation count and remaining setup/discovery/other overhead. Each real
+runner invocation is charged once, including negative controls and mixed-runner
+partitions; reused records and cached baselines create no invocation charge.
+`elapsedMs = runnerMs + overheadMs`. Optional `run.workers` records the built-in
+worker ceiling and must be one for serial execution; custom commands omit it.
+Native evidence reuse requires the same recorded worker ceiling and serial policy.
+Older native evidence with no worker ceiling is remeasured; native and opaque
+custom-command policies are not interchangeable.
+`status.cost.measurements` copies these measurements when available. Historical
+`totalMs` and cost gates retain their existing record attribution, including
+reused durations and repeated shared baseline durations. Older evidence has no
+measured breakdown; consumers must not infer it from record totals.
+
+The existing Python interpreter cache is reset at probe and replay entry and
+reused within that invocation. Uncached adapter resolution consumes the same
+live per-run deadline as test execution.
+
+The regression suite caps outer concurrency at two workers in CI. Interactive
+runs reserve one available CPU and use at most two workers; a two-core machine
+therefore uses one. Nested built-in runners retain their one-worker default.

package/spec/README.md

@@ -1,7 +1,14 @@
 # claimspec — the contract spine
 
-Nine formats for declaring what must be true about a codebase, recording the
-evidence that tried to falsify it, and gating only what is new.
+The candidate optional `originPolicy` result is a closed declared-origin policy
+audit on evidence/status/brief. It is not independent-origin authentication or
+current freshness authority. `probe --require-origin` explicitly evaluates it
+against current native/input bindings. Offline status recomputes declarations
+without certifying freshness; brief preserves labeled recorded-run policy
+before filtering/caps. See GATE-SEMANTICS.md.
+
+Shared formats for declaring what must be true about a codebase, recording the
+evidence that tried to falsify it, gating only what is new, and explicit authoring.
 
 They are shared as *formats*, not as code. The first tools to adopt them are
 [`docguard-cli`](https://www.npmjs.com/package/docguard-cli) (Node ESM) and
@@ -33,6 +40,8 @@ that carry claims, baselines, scoping and briefs do not care.
 | `status` | [`schemas/status.schema.json`](schemas/status.schema.json) | Where the project is and what happens next — the single machine-readable truth every human rendering derives from. Surfaces faults whose content changed since they were probed, and changed files that carry no claim. |
 | `replay` | [`schemas/replay.schema.json`](schemas/replay.schema.json) | Would this suite have caught the bugs that already escaped? Replays real fix commits: revert the source, remove the test the fix shipped, run what remains. A replayed bug is ground truth — a human already confirmed it was a defect — which is what a fault model is calibrated against. |
 | `gate` | [`schemas/gate.schema.json`](schemas/gate.schema.json) | Claim coverage of one change: which changed files carry a claim, which are excused (and by which ignore entry), which are unclaimed. The delta gate for code that has no claim yet. |
+| `annotations` | [`schemas/annotations.schema.json`](schemas/annotations.schema.json) | Explicit file-header authoring preview/apply, refusals and recoverable partial failures. Never verification, a probe verdict, or authentication of intent; internal source contents are excluded. |
+| `authoring-input` | [`schemas/authoring-input.schema.json`](schemas/authoring-input.schema.json) | Candidate metadata-only document/fix input handoff. No source text, origin assignment, claims or verification; historical partitions retain excluded/deleted/unsupported counts. CLI exposure remains pending. |
 
 Shared definitions (verdicts, fault classes, provenance, annotations) live in
 [`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —
@@ -48,6 +57,22 @@ rule is in `GATE-SEMANTICS.md`.
 
 Schemas are JSON Schema 2020-12 and identified as `urn:claimspec:v1:<kind>`.
 
+Claim sources share `common#/$defs/claimSourceKind`: `spec`, `adr`, `annotation`,
+`comment`, `manual`, `doc`, `bug`, `incident`, `review`, `inferred`. They declare
+intent origin, not authenticated independence or an evidence-strength ranking.
+References remain opaque metadata; producer provenance is separate. Existing
+documents remain readable, but old closed-schema readers reject the new kinds.
+Optional `origins` contracts on status, evidence and brief separate distinct
+claim counts from record counts. Evidence validation recomputes every kind and
+mixed declaration from all records; status/brief can validate only arithmetic
+and document totals because source projections are omitted. References are
+never echoed in these summaries. Legacy documents without them remain valid;
+older closed readers reject the additive field. Status emits current declared
+origins; probe evidence and evidence-backed briefs emit recorded origins before
+filtering/caps. Human renderings label these declarations as unauthenticated.
+Opt-in origin policy is available on complete confirmed candidate probes;
+offline projections remain audits, never current native freshness. See `GATE-SEMANTICS.md`.
+
 ## Conformance
 
 `lib/validate.mjs` validates a document of any kind: JSON Schema first, then

package/spec/lib/authoring-input.mjs

@@ -0,0 +1,40 @@
+import { extname } from 'node:path';
+
+const PRIVATE = new Set(['.local', '.wolf', '.git', '.testguard', 'graphify-out']);
+const SOURCE = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+
+/** Shape validation runs first. These checks cannot authenticate the actual input. */
+export function authoringInputErrors(doc) {
+  const errors = [];
+  const fail = (path, message) => errors.push({ path, message });
+  const checkPath = (file, path) => {
+    if (Buffer.byteLength(file) > 4096 || file.includes('\\') || /[\x00-\x1f\x7f-\x9f]/.test(file) || /^[A-Za-z]:/.test(file) || file.split('/').some(part => !part || part === '.' || part === '..' || PRIVATE.has(part))) fail(path, 'input path must be bounded, canonical and outside private/tooling namespaces');
+  };
+  if (Buffer.byteLength(JSON.stringify(doc)) > 1024 * 1024) fail('/', 'authoring input report exceeds byte limit');
+  const input = doc.input;
+  if (input.kind === 'document') {
+    checkPath(input.file, '/input/file');
+    if (!['.md', '.txt', '.rst', '.adoc'].includes(extname(input.file))) fail('/input/file', 'document format is unsupported');
+    return errors;
+  }
+  if (input.commit.length !== input.parent.length || input.commit === input.parent) fail('/input/parent', 'fix requires a distinct same-width parent identity');
+  if (Buffer.byteLength(input.subject) > 1024 || /[\x00-\x1f\x7f-\x9f]/.test(input.subject)) fail('/input/subject', 'commit subject must be bounded untrusted single-line text');
+  const { total, supported, deleted, unsupported, excluded } = input.counts;
+  if (total !== supported + deleted + unsupported + excluded || input.paths.length !== supported + deleted + unsupported) fail('/input/counts', 'complete path partition must retain excluded/deleted/unsupported denominators');
+  const seen = new Set(), actual = { supported: 0, deleted: 0, unsupported: 0 };
+  input.paths.forEach((row, i) => {
+    const path = `/input/paths/${i}`;
+    checkPath(row.file, `${path}/file`);
+    if (seen.has(row.file)) fail(`${path}/file`, 'visible path is duplicated');
+    seen.add(row.file);
+    if (row.oldId.length !== input.commit.length || row.newId.length !== input.commit.length) fail(path, 'path object identities must match commit width');
+    const oldZero = /^0+$/.test(row.oldId), newZero = /^0+$/.test(row.newId);
+    if ((row.oldMode === '000000') !== oldZero || (row.newMode === '000000') !== newZero ||
+      (row.status === 'A' ? !oldZero || newZero : row.status === 'D' ? oldZero || !newZero : oldZero || newZero)) fail(path, 'mode, status and zero identity must agree');
+    const disposition = row.status === 'D' ? 'deleted' : !['100644', '100755'].includes(row.newMode) || !SOURCE.has(extname(row.file)) ? 'unsupported' : 'supported';
+    if (row.disposition !== disposition) fail(`${path}/disposition`, 'disposition must derive from actual status, mode and supported extension');
+    actual[row.disposition]++;
+  });
+  if (actual.supported !== supported || actual.deleted !== deleted || actual.unsupported !== unsupported) fail('/input/counts', 'visible disposition counts must reproduce every path');
+  return errors;
+}

package/spec/lib/origins.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+
+// One vocabulary for admission and reporting; never an evidence-strength order.
+const common = JSON.parse(readFileSync(new URL('../schemas/common.schema.json', import.meta.url), 'utf8'));
+export const CLAIM_SOURCE_KINDS = Object.freeze([...common.$defs.claimSourceKind.enum]);
+const kindSet = new Set(CLAIM_SOURCE_KINDS);
+const counts = () => Object.fromEntries(CLAIM_SOURCE_KINDS.map((kind) => [kind, 0]));
+
+// Consumers validate their full document first. These narrow guards prevent
+// malformed direct calls from silently manufacturing a meaningful summary.
+function declaration(claim) {
+  const source = claim?.source;
+  if (typeof claim?.id !== 'string' || !claim.id || !kindSet.has(source?.kind)
+    || Object.keys(source).some((key) => key !== 'kind' && key !== 'ref')
+    || (Object.hasOwn(source, 'ref') && (typeof source.ref !== 'string' || source.ref.length > 512))) {
+    throw new TypeError('origin summary needs valid claim identities and declared sources');
+  }
+  return { kind: source.kind, ...(Object.hasOwn(source, 'ref') ? { ref: source.ref } : {}) };
+}
+
+/** Current declarations only: fault multiplicity cannot inflate claim counts. */
+export function declaredOriginSummary(claims) {
+  const byKind = counts();
+  const seen = new Set();
+  for (const claim of claims) {
+    const source = declaration(claim);
+    if (seen.has(claim.id)) throw new TypeError('duplicate declared claim identity');
+    seen.add(claim.id);
+    byKind[source.kind]++;
+  }
+  return { basis: 'declared', claims: { total: seen.size, byKind, mixed: 0 } };
+}
+
+/** Actual recorded projections only; no current-claims relabeling or filtering. */
+export function recordedOriginSummary(records) {
+  const recordKinds = counts();
+  const claims = new Map();
+  for (const record of records) {
+    const source = declaration(record.claim);
+    recordKinds[source.kind]++;
+    const previous = claims.get(record.claim.id);
+    if (!previous) claims.set(record.claim.id, { source, mixed: false });
+    else if (!isDeepStrictEqual(previous.source, source)) previous.mixed = true;
+  }
+  const byKind = counts();
+  let mixed = 0;
+  for (const claim of claims.values()) {
+    if (claim.mixed) mixed++;
+    else byKind[claim.source.kind]++;
+  }
+  return {
+    basis: 'recorded', claims: { total: claims.size, byKind, mixed },
+    records: { total: records.length, byKind: recordKinds },
+  };
+}