@zanii/custody-verdicts 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,204 @@
+# @zanii/custody-verdicts
+
+**The one verifier.** Zanii Custody's hard rule is *one verifier, two surfaces*: the
+subject page (zanii-id) and `@zanii/cli` import this same package and call the same
+function. Never two implementations of the verdict logic: two drift, and the drift
+always favours the vendor.
+
+Verdicts are **computed, never stored**. `computeVerdicts` derives eight verdict rows
+at view time, in the reader's browser or the auditor's terminal, from the evidence
+itself: a `SubjectHistory` from `@zanii/subject` whose receipts were already verified
+offline (signature + delegation + scope), plus an optional evidence bag.
+
+```ts
+import { computeVerdicts, computeAnchorLag, TRAINING_MANIFEST_TAG } from '@zanii/custody-verdicts';
+
+const rows = await computeVerdicts(history);             // history = await fetchSubjectHistory(tag)
+const lag = computeAnchorLag(history.sth, new Date());   // seconds; null when unknown
+```
+
+`TRAINING_MANIFEST_TAG` (`"zanii:training-manifests"`) is the well-known ledger tag
+under which declared training manifests are published. The page and the CLI fetch that
+slice to build the row-4 training evidence bag (`ExtraEvidence.training`).
+
+`computeVerdicts` is async for one reason: rows 3 and 6 check claims through injected
+verifiers (`@zanii/attest`'s quote verifier, `@zanii/residency`'s region verifier)
+that may be async. Still pure: no network, no clock.
+
+## The eight rows
+
+Always in this order; each `{ id, label, state, detail }`, with `detail` the
+plain-language working the page renders verbatim:
+
+| id | label | `proven` when | `failed` when | otherwise |
+|---|---|---|---|---|
+| `purpose` | Used only for its declared purpose | history verified AND every embedded payload is a well-formed custody touch (`verifyTouch`), retention shred (`verifyKeyDestruction`), or one of the rows 6-8 evidence payloads (structurally checked) | any offline check failed or any payload malformed | empty slice → `cannot determine` |
+| `self_sovereign` | You can check this yourself | every receipt verified offline AND the `sth` verifies | any offline check fails; bad sth | empty slice / no sth → `cannot determine` |
+| `human_read` | Nobody read it | a SIGNED coverage attestation (sig + trusted signer when pinned + `attestationHash` binding + enclave quote via injected verifier) proves all egress paths receipt-gated for the whole window | any receipt shows a human actor; the attestation is unsigned, badly signed, from an unrecognized signer, unbound, malformed, or its quote is disproven | `not covered`: "No coverage attestation for this window"; no quote verifier injected → `cannot determine` |
+| `trained_on` | Never used to train a model | `@zanii/train`'s `verifyAbsence` passes for this subject's tag against a declared manifest anchored BEFORE the run attestation | the proof does not verify, names another ref, or the manifest is malformed | no declared run → `not covered`: "No declared training runs to check against"; wrong anchor order / missing times → `cannot determine` |
+| `copy_kept` | No copy was kept | every object touched in the slice has a shred receipt bound to its ref (payload `ref` = the touch's ref) that passes its own offline check AND `verifyKeyDestruction`, and any image evidence matches | a presented shred receipt fails either check; image evidence mismatches or is incomplete | none bound to a touched object's ref → `not covered`: "No key-destruction record on file."; some objects covered, some not → `cannot determine` |
+| `residency` | Data stayed in its declared region | EVERY custody touch has a verified in-set claim (a claim with a `ref` binds every touch of that object; a ref-less claim covers the touches at its own timestamp), every region signal authenticates (injected `verifyRegion`), and `detectCrossings` finds no exit | a verified claim's region is outside the allow-set (a border crossing), or a claim is malformed, invalid, or rides on an unverified receipt | no claims → `not covered`: "No residency attestations on record" (self-declared claims are not attestations and say so); empty slice, any touch without a claim, no `jurisdiction` config, or no injected `verifyRegion` → `cannot determine` |
+| `subprocessor` | Only declared third parties touched it | every custody-touch junction and recorded transfer resolves to a declared party under a named agreement (`verifyTransfers` against the reader-pinned list, plus a junction/transfer divergence check) | any `undeclared` receiver, any transfer without an agreement id, any malformed record, or a junction naming a destination with no matching declared transfer | none recorded → `not covered`: "No onward transfers declared or recorded"; destinations on record but no reader-provided `declaredSubprocessors` → `cannot determine` |
+| `minimization` | Only what was needed was taken | every recorded access proof verifies (`verifyMinimization`) against its committed minimum field set, and every commitment record recomputes to its recorded commitment (`verifyFieldSet`) | any `excess` access (a field outside the declared minimum), a widened-after-commitment set, or a malformed record | no commitments → `not covered`: "No minimum-field commitments on record"; empty slice, commitments without access proofs, access proofs without commitments, or an access proof against an unknown commitment → `cannot determine` |
+
+Four states: `proven`, `not covered`, `failed`, `cannot determine`. The last three are
+as first-class as the first: a missing proof is not a clean result, and nothing here
+ever renders "never" out of a database column.
+
+On an **empty slice** (zero receipts) rows 1-2 answer `cannot determine` and rows 3-5
+stay grey regardless of evidence: there is nothing to cover. Row 3 with a coverage
+attestation over an empty slice answers `cannot determine` (coverage over nothing
+proves nothing about this subject's data); row 4 answers `not covered`; row 5's
+evidence lives in the slice, so an empty slice has none. Rows 6 and 8 answer
+`cannot determine` on an empty slice (there is no window to cover); row 7's evidence
+lives in the slice, so an empty slice answers `not covered`.
+
+## Evidence shapes
+
+`ExtraEvidence` (`{ coverage?, training?, destructionImage?, jurisdiction?,
+declaredSubprocessors? }`) carries the evidence and reader-side trust roots that do
+not live in the slice; everything is checked offline, here, in this one place,
+against the real producers' shapes:
+
+- **`training`** (row 4) is `{ manifest, anchoredAt, runAttestedAt, absenceProof }`:
+  `@zanii/train`'s `TrainingManifest` and `AbsenceProof` (sorted-Merkle over
+  covering-gap pair leaves, reusing core's RFC 6962 inclusion proofs). The manifest
+  anchor must precede the run attestation, or the ordering cannot be trusted.
+- **`destructionImage`** (row 5, optional) is `{ attestation, publishedImageHash }`: a
+  claimed destruction-image attestation plus the image hash the operator published.
+  What is checked here is **bag-internal consistency only**, via `@zanii/attest`'s
+  `attestationHash` convention (the published image hash is `attestationHash` of the
+  published attestation record): a mismatch is `failed`, a match appends the
+  attested-image line to the proven detail. A match does NOT by itself prove the
+  destruction ran under that image: nothing yet binds the shred receipt to the
+  attestation, and the attestation's quote is not verified on this path. The full
+  binding ships with the enclave phase. The destruction record itself needs no bag
+  entry: it is the `@zanii/retention` shred receipt carried in the subject's slice
+  (signature-covered embedded payload, target `data.retention.shred`), bound to the
+  subject by slice membership and to the OBJECT by ref: a shred counts only for an
+  object whose custody touches carry the same payload `ref`, and `proven` requires a
+  verified bound shred for every object the slice touches (partial coverage answers
+  `cannot determine`; a shred bound only to unrelated refs answers `not covered`).
+  Its salted `subject_commitment` can later be proven to name the subject by
+  revealing the salt.
+- **`coverage`** (row 3) is a signed coverage attestation
+  (`{ v: 1, type: 'coverage.attestation', allPathsGated, windowStart, windowEnd,
+  imageHash, attestation, signer, sig, trustedSigners? }`): every egress path
+  receipt-gated (the `@zanii/broker` invariant) for a window, bound to an attested
+  image hash, signed by the platform key. Verified fail-closed: signature and (when
+  pinned) trusted signer, then the `attestationHash` binding, then
+  `verifyAttestation` with the caller's injected quote verifier
+  (pass it as `computeVerdicts(history, evidence, { verifyQuote })`). Without an
+  injected verifier the quote stays unknown and the row can only reach
+  `cannot determine`, never `proven`.
+- **`jurisdiction`** (row 6) is `string[]`: the declared jurisdiction as an allow-set
+  of region codes (`@zanii/residency`'s `allowedRegions`). Reader-side configuration,
+  never producer-supplied (same trust rule as `coverage.trustedSigners`).
+- **`declaredSubprocessors`** (row 7) is `string[]`: the declared subprocessor list
+  that onward transfers and custody junctions are checked against. Reader-side
+  configuration, never producer-supplied.
+
+## Row 6: "Data stayed in its declared region"
+
+Mechanism: residency claim payloads in the slice (`@zanii/residency`'s
+`buildResidencyClaim` shape, embedded signature-covered exactly like the row-5 shred
+payloads) are checked with `verifyResidency` against the reader-pinned
+`jurisdiction` allow-set and the caller's injected `verifyRegion` (pass it as
+`computeVerdicts(history, evidence, { verifyRegion })`), which authenticates the
+region signal (a cloud provider identity document, a TEE geo signal) and returns the
+trusted region. `detectCrossings` then runs over the verified touch sequence: any
+exit from the allow-set is a border crossing and a red, never silent.
+
+`proven` requires per-touch coverage, never a window span: EVERY custody touch in the
+slice must be covered by a verified in-set claim. A claim carrying a `ref` binds to
+every touch of that object; a ref-less claim is time-scoped and covers the touches
+made at its own timestamp. Every region signal must authenticate inside the
+allow-set, no claim may be malformed or unverified, and no crossings may be
+detected. A claim whose region source is self-declared (the operator asserted its
+own region) is not an attestation: it is not counted as evidence, and when every
+claim is self-declared the row answers `not covered` and says so.
+
+The limit: the proof is only as strong as the injected geo trust root. A proven row
+means "signals your verifier trusts placed every touch inside your declared
+jurisdiction"; it cannot prove residency your geo source cannot. A touch with no
+claim answers `cannot determine`, never `proven`.
+
+## Row 7: "Only declared third parties touched it"
+
+Mechanism: transfer records in the slice (`@zanii/subprocessor`'s `buildTransfer`
+shape) are checked with `verifyTransfers` against the reader-pinned
+`declaredSubprocessors` list, and every custody-touch junction
+(`@zanii/data-custody`'s `junction` field) must name a destination with a matching
+declared transfer: a divergence between the custody trail and the transfer record is
+a red, never silent.
+
+`proven` requires: every recorded transfer's receiver is declared, every transfer
+carries an agreement id (stricter than the producer, which requires an id only for
+dpa/scc), no record is malformed, and every junction resolves to a declared party
+under a named agreement.
+
+The limit: this proves the transfers that were recorded. An off-record leak (a
+processor that received plaintext and emitted no transfer receipt) cannot be caught
+here; that residual is the enclave problem, unchanged. And an agreement id is a
+reference, not a guarantee the counterparty honored it. Senders are not checked:
+`verifyTransfers` runs without a controller, so an undeclared `from` is
+indistinguishable from the origin and goes unchecked.
+
+## Row 8: "Only what was needed was taken"
+
+Mechanism: field-set commitment records in the slice (`@zanii/minimization`'s
+`commitFieldSet` output carried as a `minimization.commit` payload) are recomputed
+with `verifyFieldSet` (a mismatch means the declared minimum was widened after the
+commitment was recorded), and every access proof (`buildAccessProof` shape) is
+checked with `verifyMinimization` against its committed field set: any accessed
+field outside the declared minimum is a flagged excess, a red.
+
+`proven` requires: every commitment record recomputes to its recorded commitment and
+every recorded access stayed inside its committed minimum. Commitments without
+access proofs, access proofs without commitments, or an access proof whose
+commitment is not on record answer `cannot determine`: an unchecked access is
+unknown, not clean.
+
+The limit: this proves declared-vs-accessed: that the agent stayed inside the
+minimum that was committed. It does not prove the minimum was well-chosen (a
+judgement, not a cryptographic fact), and it proves the recorded accesses: an
+off-record read is the enclave problem, unchanged.
+
+## Trust roots: who may attest coverage
+
+The same reader-side rule now guards three trust roots: `coverage.trustedSigners`
+(row 3), `jurisdiction` (row 6), and `declaredSubprocessors` (row 7). All three are
+reader-side configuration, merged into the evidence by the subject page or the CLI
+from its OWN deployment config, never from producer-supplied data: an attacker who
+could name their own signer, their own jurisdiction, or their own subprocessor list
+would attest anything.
+
+A coverage attestation is only as good as the key that signs it. The producer side
+(enclave phase) signs with the platform's coverage-signing key; the reader side, the
+subject page and the CLI, pins the platform's coverage-signing DID(s) and merges them
+into the evidence as `coverage.trustedSigners` before calling `computeVerdicts`. Two
+rules make this a real trust root rather than a formality:
+
+- **The list is reader-side configuration.** It must never come from
+  producer-supplied data: an attacker who could name their own key trusted would
+  attest anything. For the same reason `trustedSigners` is NOT part of the signed
+  record; it is excluded from the signature preimage and merged in after signing.
+- **An unknown signer is never `proven`.** When `trustedSigners` is present, a
+  coverage attestation signed by any other DID is `failed` ("coverage attestation
+  from an unrecognized signer"); an empty list trusts no one. When it is absent (day
+  one), any well-formed did:key signer authenticates, and the remaining checks
+  decide. Deployments should always pin once the enclave phase ships.
+
+**Row 3's producer side ships with the enclave phase.** `@zanii/attest` +
+`@zanii/broker` produce signed coverage attestations there. Until then the evidence
+does not exist, the row answers `not covered`, and `proven` is unreachable: that is
+the design, not a gap. A "nobody read it" claim without hardware attestation would be
+our word, not evidence.
+
+## Guarantees
+
+- Pure: no network, no clock (`computeAnchorLag` takes `now` from the caller). Async
+  only for the injected verifiers (enclave quote, region signal).
+- Never throws: malformed input yields honest `cannot determine` / `not covered` /
+  `failed` rows with reasons (verification paths return results; creation paths throw).
+- No verdict is ever stored or served; the ledger serves raw evidence only.

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { type SignedTreeHead } from '@zanii/core';
+import { type AbsenceProof, type TrainingManifest } from '@zanii/train';
+import { type Attestation, type QuoteVerifier } from '@zanii/attest';
+import { type RegionVerifier } from '@zanii/residency';
+import type { SubjectHistory } from '@zanii/subject';
+export type { AbsenceProof, TrainingManifest } from '@zanii/train';
+export type { Attestation, QuoteVerifier } from '@zanii/attest';
+export type { RegionVerifier, ResidencyClaim } from '@zanii/residency';
+export type { Agreement, Transfer } from '@zanii/subprocessor';
+export type { AccessProof } from '@zanii/minimization';
+/**
+ * The well-known ledger tag under which declared training manifests are published.
+ * The subject page and the CLI fetch that slice to build the row-4 training evidence
+ * bag (`ExtraEvidence.training`).
+ */
+export declare const TRAINING_MANIFEST_TAG = "zanii:training-manifests";
+/** The four verdict states. The last three are as loud as the first. */
+export type VerdictState = 'proven' | 'not covered' | 'failed' | 'cannot determine';
+export type VerdictId = 'purpose' | 'self_sovereign' | 'human_read' | 'trained_on' | 'copy_kept' | 'residency' | 'subprocessor' | 'minimization';
+export interface VerdictRow {
+    id: VerdictId;
+    label: string;
+    state: VerdictState;
+    /** Plain-language working: which receipts were computed over, why this state. Rendered verbatim. */
+    detail: string;
+}
+/**
+ * Coverage attestation for the "nobody read it" line: a SIGNED record asserting that
+ * every egress path to the data was receipt-gated (the `@zanii/broker` invariant) for
+ * the whole window, bound to the attested image whose code enforced it. The signature
+ * covers every field but `sig`; `imageHash` must equal `attestationHash(attestation)`
+ * (`@zanii/attest`'s convention), and the embedded attestation is verified through
+ * `verifyAttestation` with the caller's injected quote verifier. Anything unsigned or
+ * malformed is never `proven`. The producer side ships with the enclave phase
+ * (`@zanii/attest` + `@zanii/broker`); until then this evidence does not exist and the
+ * row answers `not covered`, by design.
+ */
+export interface CoverageEvidence {
+    v: 1;
+    type: 'coverage.attestation';
+    /** Every egress path was receipt-gated; partial coverage is no coverage. */
+    allPathsGated: boolean;
+    /** ISO timestamp: start of the gated window. */
+    windowStart: string;
+    /** ISO timestamp: end of the gated window. */
+    windowEnd: string;
+    /** `attestationHash` of the embedded attestation: the image the claim is bound to. */
+    imageHash: string;
+    /** The full attestation record (`@zanii/attest`'s `Attestation`). */
+    attestation: Attestation;
+    /** did:key of the platform key that signed this attestation. */
+    signer: string;
+    /** `ed25519:<hex>` over the canonical record minus `sig`. */
+    sig: string;
+    /**
+     * Optional trust root: the deployment's pinned coverage-signing DIDs. The reader
+     * (subject page / CLI) sets this from its OWN configuration, never from
+     * producer-supplied data; otherwise an attacker could attest with their own key and
+     * name it trusted. Not part of the signed record (excluded from the signature
+     * preimage). When present, a signer not in the list is `failed`; an empty list
+     * trusts no one. When absent, any well-formed did:key signer is accepted.
+     */
+    trustedSigners?: string[];
+}
+/**
+ * A declared, anchored training run plus `@zanii/train`'s absence proof. Ordering is
+ * the whole claim: the manifest anchor must PRECEDE the run attestation. A manifest
+ * anchored afterwards could have been written to exclude the subject.
+ */
+export interface TrainingEvidence {
+    /** The run's sorted-Merkle training manifest (`@zanii/train`'s `TrainingManifest`). */
+    manifest: TrainingManifest;
+    /** ISO timestamp when the manifest root was anchored. */
+    anchoredAt: string;
+    /** ISO timestamp of the run attestation. */
+    runAttestedAt: string;
+    /** `@zanii/train`'s `AbsenceProof` for this subject's tag, verified against the manifest. */
+    absenceProof: AbsenceProof;
+}
+/**
+ * Optional image evidence for the "no copy was kept" line: a CLAIMED destruction-image
+ * attestation plus the image hash the operator published for it. What is checked here
+ * is bag-internal consistency only, via `@zanii/attest`'s `attestationHash` convention
+ * (the published image hash is `attestationHash` of the published attestation record):
+ * a mismatch is `failed`. A match does NOT by itself prove the destruction ran under
+ * that image: nothing yet binds the shred receipt to the attestation, and the
+ * attestation's quote is not verified on this path. Full binding ships with the
+ * enclave phase.
+ */
+export interface DestructionImageEvidence {
+    /** The attestation (`@zanii/attest`'s `Attestation`) claimed for the destruction image. */
+    attestation: Attestation;
+    /** The published image hash: `attestationHash` of the published attestation record. */
+    publishedImageHash: string;
+}
+/**
+ * Optional evidence bag for rows 3–5. Row 5 needs no bag entry for the destruction
+ * record itself: the shred receipts are read from the subject's slice, each already
+ * signature-covered and offline-verified. `destructionImage` only checks a claimed
+ * destruction-image attestation against the published image hash.
+ */
+export interface ExtraEvidence {
+    coverage?: CoverageEvidence;
+    training?: TrainingEvidence;
+    destructionImage?: DestructionImageEvidence;
+    /**
+     * Row 6 trust root: the declared jurisdiction as an allow-set of region codes
+     * (`@zanii/residency`'s `allowedRegions`, e.g. `['AE', 'me-central-1']`). READER
+     * configuration (deployment-side), never producer-supplied: the same trust rule as
+     * `coverage.trustedSigners`, or a producer could declare the whole world in bounds.
+     * When absent, residency claims can reach `cannot determine`, never `proven`. An
+     * empty array allows no region: every verified claim is a crossing.
+     */
+    jurisdiction?: string[];
+    /**
+     * Row 7 trust root: the declared subprocessor list (the parties onward transfers
+     * may name). READER configuration, never producer-supplied, same trust rule as
+     * `coverage.trustedSigners`. When absent, transfers or junctions on record reach
+     * `cannot determine`, never `proven`. An empty array declares no one.
+     */
+    declaredSubprocessors?: string[];
+}
+/** Caller-injected verifiers: the enclave quote verifier for row 3, the region
+ *  signal verifier for row 6. */
+export interface VerdictOptions {
+    /**
+     * Platform-specific enclave quote verifier (`@zanii/attest`'s `QuoteVerifier`).
+     * Without it a signed coverage attestation can reach `cannot determine`, never
+     * `proven`: the quote stays unknown, and unknown is not verified.
+     */
+    verifyQuote?: QuoteVerifier;
+    /**
+     * Region signal verifier (`@zanii/residency`'s `RegionVerifier`): authenticates a
+     * claim's region attestation (a cloud provider identity document, a TEE geo
+     * signal) and returns the trusted region. Without it residency claims can reach
+     * `cannot determine`, never `proven`.
+     */
+    verifyRegion?: RegionVerifier;
+}
+/**
+ * Compute the eight verdict rows from an offline-verified subject history. Pure: no
+ * network, no clock. Async only because row 3's coverage attestation is checked
+ * through `@zanii/attest`'s `verifyAttestation` and row 6's residency claims through
+ * `@zanii/residency`'s `verifyResidency`, whose injected verifiers may be async;
+ * pass them via `options.verifyQuote` / `options.verifyRegion`. Never throws:
+ * malformed input yields honest `cannot determine` / `not covered` / `failed` rows
+ * with reasons. Rows are always returned in this fixed order: purpose,
+ * self_sovereign, human_read, trained_on, copy_kept, residency, subprocessor,
+ * minimization.
+ */
+export declare function computeVerdicts(history: SubjectHistory, evidence?: ExtraEvidence, options?: VerdictOptions): Promise<VerdictRow[]>;
+/**
+ * Seconds between the signed tree head's timestamp and `now` (the caller supplies
+ * `now`; this package has no clock). The page shows anchor lag: four minutes vs
+ * four hours is a property the reader is entitled to see. Null when unknown (no sth,
+ * no timestamp, unparseable). Negative means the sth is newer than the caller's
+ * clock: possible skew, shown as-is.
+ */
+export declare function computeAnchorLag(sth: Record<string, unknown> | SignedTreeHead | undefined | null, now: Date | string | number): number | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}