@sanning/proof 0.17.0 → 0.19.0

package/dist/evidence.js

@@ -1019,6 +1019,10 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
     let gatewayUnavailable = false;
     let uncheckedKind = false;
     let uncheckedId = false;
+    // Simulated witnesses against witnesses of any other kind, counted over the
+    // checkpoints that name one, as `refetchStamps` counts stamps.
+    let simulated = 0;
+    let onChainKinds = 0;
     if (onChainChecked) {
         if (typeof fetchImpl !== "function") {
             gatewayUnavailable = true;
@@ -1060,6 +1064,10 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
                     cpr.errors.push("checkpoint has no anchor_ref -- not yet witnessed, nothing to re-fetch");
                     continue;
                 }
+                if (cpr.anchorRef.kind === SIMULATED_WITNESS_KIND)
+                    simulated++;
+                else
+                    onChainKinds++;
                 const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
                 cpr.onChain = outcome.onChain;
                 cpr.onChainOk = outcome.onChain?.onChainOk ?? null;
@@ -1127,7 +1135,10 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
         bodyHashOk: true,
         signatureOk: true,
         bodyType,
-        onChainChecked,
+        // A run whose only witnessed checkpoints are simulated looked nothing up
+        // on a chain, so it is not counted as checked on one (the stamp rule in
+        // `refetchStamps`). The checkpoints stay not checked and the run partial.
+        onChainChecked: onChainChecked && !(simulated > 0 && onChainKinds === 0),
         checkpoints: checkpointResults,
         events: eventResults,
         assertedStatus,
@@ -1939,6 +1950,8 @@ async function refetchStamps(stamps, witnessed, options, errors) {
     let gatewayUnavailable = false;
     let uncheckedKind = false;
     let uncheckedId = false;
+    let simulated = 0;
+    let onChainKinds = 0;
     for (let i = 0; i < stamps.length; i++) {
         const st = stamps[i];
         const witnessedHex = witnessed[i];
@@ -1946,6 +1959,10 @@ async function refetchStamps(stamps, witnessed, options, errors) {
         // nothing a gateway could confirm or deny. Left as `onChain: null`.
         if (st.anchorRef === null || witnessedHex === undefined)
             continue;
+        if (st.anchorRef.kind === SIMULATED_WITNESS_KIND)
+            simulated++;
+        else
+            onChainKinds++;
         const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
         st.onChain = outcome.onChain;
         st.onChainOk = outcome.onChain?.onChainOk ?? null;
@@ -1968,8 +1985,22 @@ async function refetchStamps(stamps, witnessed, options, errors) {
         // unreachable note would fail a stamp for a gateway being down.
         st.ok = st.ok && st.onChainOk !== false;
     }
+    // A simulated witness is a sandbox plane's stand-in for a chain: there is no
+    // chain to look it up on, so it is never counted as checked on one.
+    // It stays not checked like any kind this verifier has no adapter for, and
+    // the run stays undetermined; what changes is that a run whose only
+    // witnesses are simulated no longer says it checked anything on a chain.
+    if (simulated > 0 && onChainKinds === 0) {
+        return { onChainChecked: false, gatewayUnavailable, uncheckedKind, uncheckedId };
+    }
     return { onChainChecked, gatewayUnavailable, uncheckedKind, uncheckedId };
 }
+/**
+ * The `anchor_ref.kind` a sandbox plane writes for a witness it simulated
+ * (chain id `sanning-sandbox`). Never looked up and never counted as checked
+ * on a chain.
+ */
+export const SIMULATED_WITNESS_KIND = "simulated";
 // How many `sanning.evidence.export/v2` wrappers deep the source bundle may be
 // nested before this path gives up. verifyEvidenceBundle's canonicalization
 // depth bound already rejects a pathological bundle, but the unwrap must be

package/dist/exit-codes.d.ts

@@ -3,6 +3,14 @@ export declare const EXIT_FAILED = 1;
 export declare const EXIT_MALFORMED = 2;
 export declare const EXIT_UNDETERMINED = 3;
 export declare const EXIT_MIXED = 4;
+/**
+ * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
+ * case holding a record signed `environment: "dev"`, or a run over records
+ * that are ALL signed `dev` whose only unsettled witnesses are simulated.
+ * Not a verdict word: the verdict stays what the checks established
+ * (`sandboxExit`). No flag turns 5 into 0.
+ */
+export declare const EXIT_SANDBOX = 5;
 /**
  * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
  * `undetermined` is the name of 3, and never a word here.
@@ -15,3 +23,13 @@ export declare const EXIT_CODES_HELP: string;
  * nothing can render, so it exits 2, never 0.
  */
 export declare function exitCodeFor(verdict: unknown): number;
+/**
+ * The code a verb exits with once the environment marker is read. 5 where the
+ * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
+ * 5 where the run is undetermined only because a simulated witness could not
+ * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
+ * EVERY record is signed `dev`, so a production or mixed pack carrying a
+ * simulated witness keeps 3; the code unchanged everywhere else. A failure
+ * stays 1, malformed 2 and mixed 4.
+ */
+export declare function sandboxExit(code: number, environmentMarker: string | null, onlySimulatedUnsettled?: boolean): number;

package/dist/exit-codes.js

@@ -15,6 +15,14 @@ export const EXIT_FAILED = 1;
 export const EXIT_MALFORMED = 2;
 export const EXIT_UNDETERMINED = 3;
 export const EXIT_MIXED = 4;
+/**
+ * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
+ * case holding a record signed `environment: "dev"`, or a run over records
+ * that are ALL signed `dev` whose only unsettled witnesses are simulated.
+ * Not a verdict word: the verdict stays what the checks established
+ * (`sandboxExit`). No flag turns 5 into 0.
+ */
+export const EXIT_SANDBOX = 5;
 /**
  * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
  * `undetermined` is the name of 3, and never a word here.
@@ -37,6 +45,7 @@ export const EXIT_CODES_HELP = [
     "  2  usage or malformed",
     "  3  undetermined: partial, pending, incomplete or not_found",
     "  4  mixed: more than one outcome, none failed; read the exceptions",
+    "  5  sandbox: a record is signed environment dev; would be 0, or only a simulated witness is unchecked",
 ].join("\n");
 /**
  * The exit code of a verdict word. A word outside the eight is a verdict
@@ -48,3 +57,19 @@ export function exitCodeFor(verdict) {
     }
     return EXIT_MALFORMED;
 }
+/**
+ * The code a verb exits with once the environment marker is read. 5 where the
+ * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
+ * 5 where the run is undetermined only because a simulated witness could not
+ * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
+ * EVERY record is signed `dev`, so a production or mixed pack carrying a
+ * simulated witness keeps 3; the code unchanged everywhere else. A failure
+ * stays 1, malformed 2 and mixed 4.
+ */
+export function sandboxExit(code, environmentMarker, onlySimulatedUnsettled = false) {
+    if (code === EXIT_VERIFIED && environmentMarker !== null)
+        return EXIT_SANDBOX;
+    if (code === EXIT_UNDETERMINED && environmentMarker === "dev" && onlySimulatedUnsettled)
+        return EXIT_SANDBOX;
+    return code;
+}

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyEnvelope, } from "./verifier.js";
-export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+export { jcsParse } from "./verifier.js";
+export { exceedsTextDepth, hasNonFiniteNumber, jcsParseWithinLimits, MAX_READ_DEPTH } from "./verifier.js";
+export { bytesToHex, deriveOperatorAddress, ed25519Refusal, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
 export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, CO_SIGNATURES_NOTE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, coSignaturesPresent, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
 export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
 export { PACK_GRADE_CAUSE_KINDS, PACK_VERDICTS, accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
-export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSION_V3, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
 export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, DeclarationContentKind, DeclarationDeviation, DeclarationDeviationKind, DeclarationNote, DeclarationNoteKind, DeclarationRole, DeclarationVerdict, PackRecord, } from "./declaration.js";
 export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_RECORD_STATUSES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_RELIANCE_HANDOFF_CLAUSE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, CO_SIGNATURES_PRESENT, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, WITNESS_TIME_CACHED, WITNESS_TIME_RECORDED, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
@@ -18,9 +20,11 @@ export { CASE_FILE_FINDING_KINDS, CASE_FILE_INDEX_NAME, CASE_FILE_VERSION, HOW_T
 export type { CaseFileFinding, CaseFileFindingKind, CaseFileIndexReading, } from "./case-file.js";
 export { FILE_MATCH_SCOPE, NOT_READ_REASONS, SKIPPED_REASONS, fileMatchToJson, matchCaseFiles, matchFiles, notAccountedFor, renderFileMatch, } from "./file-match.js";
 export type { FileCommitment, FileMatchPack, FileMatchReading, MatchedFile, NotRead, NotReadReason, OfferedFile, SkippedFile, SkippedReason, UnmatchedFile, } from "./file-match.js";
-export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
-export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
-export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChainLinks, readChains, renderChainFinding, } from "./chain.js";
+export type { ChainFinding, ChainFindingKind, ChainLink, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
+export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_SANDBOX, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, sandboxExit, } from "./exit-codes.js";
+export { SANDBOX_HEADLINE, SANDBOX_LINE, SANDBOX_TITLE, environmentMarker, onlySimulatedUnsettled, packEnvelopes, } from "./environment.js";
+export type { EnvironmentMarker } from "./environment.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 export { AGENT_PROOF_SPEC_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";

package/dist/index.js

@@ -18,7 +18,16 @@
 // mutable accept-set would be a runtime-widenable kernel. Additive — no
 // existing export changes.
 export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyEnvelope, } from "./verifier.js";
-export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+// The strict reader of bytes that claim to be JCS, the twin of Python's public
+// `canonicalize.jcs_loads`. The enclave attestation adapters read a token's
+// JSON through it, so they refuse what the kernel refuses. Additive.
+export { jcsParse } from "./verifier.js";
+// The same reader within the enclave readers' limits (enclave-attestation
+// section 2.1): depth checked on the bytes first, every number finite. The
+// adapters read a token's header and claims and the manifest through it.
+// Additive.
+export { exceedsTextDepth, hasNonFiniteNumber, jcsParseWithinLimits, MAX_READ_DEPTH } from "./verifier.js";
+export { bytesToHex, deriveOperatorAddress, ed25519Refusal, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 // Evidence-bundle verification (specs/evidence-bundle.md): the signed
 // sanning.evidence/v1 wrapper carrying the sanning.anchor.trace/v3 body. The CLI
@@ -67,7 +76,7 @@ export { PACK_GRADE_CAUSE_KINDS, PACK_VERDICTS, accountDisclosure, completenessN
 // Pure: data in, data out, no I/O. `gradePack` takes the result as an
 // optional fourth argument, so a surface gets one verdict; omitting it is the
 // pre-§5.4 behavior, unchanged. Additive: no existing export changes.
-export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSION_V3, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
 // The case (src/case.ts): one verdict over SEVERAL packs, across organizations
 // (anchor#198). The layer above the declaration, and the closure for what a
 // declaration cannot reach.
@@ -126,20 +135,27 @@ export { FILE_MATCH_SCOPE, NOT_READ_REASONS, SKIPPED_REASONS, fileMatchToJson, m
 // `vectors/chain-reading.json` beside the pack-grading table for the same
 // reason: a rule consumers must agree with needs a statement they can fetch.
 //
-// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// It returns FINDINGS, never a verdict, and it feeds no status on its own: a
+// pack's signed v3 declaration can claim a chain complete and in order, and
+// `checkDeclaration` holds that claim to the links `readChainLinks` reads
+// (evidence-bundle.md 5.4.2 rule 11). Chain links are
 // deletion/reorder-evidence for the events present and NOT a completeness proof
 // (`anchor/docs/profile-sanning.events-v2.md` §5), drop the last N events of a
 // chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
 // every surface prints the same limit rather than paraphrasing it into a claim.
 // Additive — no existing export changes.
-export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChainLinks, readChains, renderChainFinding, } from "./chain.js";
 // The `proof export` composer (specs/evidence-export.md §5, phase 2): produce a
 // signed, offline-verifiable sanning.evidence.export/v2 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The
 // inverse of verifyEvidenceBundle's verifyExportBody dispatch.
 // One exit-code table for every verb (0.13.0): the verdict word to the exit
 // code, and the help text every verb prints. Additive.
-export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
+export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_SANDBOX, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, sandboxExit, } from "./exit-codes.js";
+// Sandbox evidence: the environment marker over the envelopes a pack or case
+// holds (envelope-spec §2, the `environment_marker` MAY), and the headline and
+// line both commands print for it. Additive.
+export { SANDBOX_HEADLINE, SANDBOX_LINE, SANDBOX_TITLE, environmentMarker, onlySimulatedUnsettled, packEnvelopes, } from "./environment.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 // Agent inclusion-proof bundle verification: the
 // sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so

package/dist/run-adapters.d.ts

@@ -0,0 +1,10 @@
+import { type EnclaveAdapter } from "./run.js";
+/** Import a module by name. A parameter so a test can watch what is asked for. */
+export type Importer = (name: string) => Promise<unknown>;
+/**
+ * The adapters this environment holds, loaded from `ADAPTER_MODULES` and
+ * nothing else. A module counts only when it exports the provider it was
+ * loaded for as `provider`, a `check` function, and the failure kinds it
+ * declares as `kinds` (`declaredKinds`).
+ */
+export declare function loadInstalledAdapters(importer?: Importer): Promise<Map<string, EnclaveAdapter>>;

package/dist/run-adapters.js

@@ -0,0 +1,35 @@
+// Loading the enclave attestation adapters a reader has installed. Kept out of
+// `index.ts` on purpose: it imports packages by name, which a browser bundle
+// cannot resolve, and only the command line needs it. `run.ts` imports nothing.
+//
+// The packages are named by `ADAPTER_MODULES` and by nothing else: a provider
+// id read from a pack is never turned into a module name.
+import { ADAPTER_MODULES, declaredKinds } from "./run.js";
+const dynamicImport = (name) => import(/* @vite-ignore */ name);
+/**
+ * The adapters this environment holds, loaded from `ADAPTER_MODULES` and
+ * nothing else. A module counts only when it exports the provider it was
+ * loaded for as `provider`, a `check` function, and the failure kinds it
+ * declares as `kinds` (`declaredKinds`).
+ */
+export async function loadInstalledAdapters(importer = dynamicImport) {
+    const found = new Map();
+    for (const [provider, name] of Object.entries(ADAPTER_MODULES)) {
+        let module;
+        try {
+            module = await importer(name);
+        }
+        catch {
+            continue;
+        }
+        const m = module;
+        if (m !== null &&
+            typeof m === "object" &&
+            m.provider === provider &&
+            typeof m.check === "function" &&
+            declaredKinds(m) !== null) {
+            found.set(provider, m);
+        }
+    }
+    return found;
+}

package/dist/run.d.ts

@@ -0,0 +1,209 @@
+import { type SideContentMap } from "./side-content.js";
+export declare const ATTESTATION_VERSION = "sanning.enclave-attestation/v1";
+export declare const BINDING_VERSION = "sanning.run-binding/v1";
+export declare const POLICY_VERSION = "sanning.enclave-policy/v1";
+export declare const MANIFEST_VERSION = "sanning.run-manifest/v1";
+export declare const RUN_OPENED = "runner.run_opened";
+export declare const RUN_CLOSED = "runner.run_closed";
+export declare const PROVIDER_GCP = "gcp-confidential-space";
+export declare const PROVIDER_FLARE = "flare-fcc";
+/**
+ * The fixed table: provider id to the package that answers for it. A provider
+ * id read from a pack is looked up HERE and nowhere else, so a pack naming `os`
+ * or `../x` loads nothing.
+ */
+export declare const ADAPTER_MODULES: Readonly<Record<string, string>>;
+/** Printed after an enclave line whose token was checked. Never a state. */
+export declare const REVOCATION_SENTENCE: string;
+export declare const ENCLAVE_STATES: readonly ["confirmed", "differs", "not_checked"];
+export declare const RUN_ACCOUNT_STATES: readonly ["closed", "differs", "not_closed"];
+/** Why an enclave line reads `not_checked`. */
+export declare const ENCLAVE_NOT_CHECKED_KINDS: readonly ["no_adapter", "no_attestation", "unknown_version", "no_policy", "policy_unreadable", "adapter_failed", "no_opening_record"];
+/** The provider-neutral checks that make a line `differs`, in line order. */
+export declare const ENCLAVE_DIFFERS_KINDS: readonly ["attestation_malformed", "subject_key_not_signer", "manifest_not_content", "binding_other_run", "binding_other_manifest", "binding_other_keys", "signed_at_outside_tolerance", "manifest_content_mismatch", "manifest_unreadable", "case_hash_differs", "agent_record_under_runner_key"];
+/** The kinds an adapter may answer with; any other reads `adapter_failed`. */
+export declare const ENCLAVE_NOTE_KINDS: readonly ["no_issue_time", "manifest_withheld", "stamp_unwitnessed"];
+/**
+ * Every kind and note the kernel itself names. An adapter declares its own
+ * failure kinds (its `kinds`, section 9); none of them may be one of these, so
+ * an adapter can never speak for a neutral check.
+ */
+export declare const NEUTRAL_KINDS: ReadonlySet<string>;
+export declare const ACCOUNT_FINDING_KINDS: readonly ["record_not_listed", "listed_record_absent", "more_than_one_closing_record", "closing_malformed"];
+/**
+ * Why the online line (`flare-fcc` only, section 8) reads `not_checked`:
+ * nothing was decided. `adapter_failed` is the kernel's.
+ */
+export declare const ONLINE_NOT_CHECKED_KINDS: readonly ["adapter_failed", "evidence_not_confirmed", "no_contracts", "manifest_withheld", "manifest_unreadable", "chain_unavailable", "not_final"];
+/** Why the online line reads `differs`: the chain answered, and it does not match. */
+export declare const ONLINE_DIFFERS_KINDS: readonly ["instruction_count", "instruction_other_extension", "instruction_other_machine", "instruction_other_operation", "instruction_other_message", "transaction_failed", "log_malformed", "run_opened_differs", "run_opened_count", "machine_not_production", "machine_other_extension", "code_not_supported", "call_reverted"];
+export declare const ACCOUNT_NOTE_KINDS: readonly ["agent_key_unknown", "runner_record_under_agent_key", "runner_record_bytes_withheld", "payload_hashes_absent", "unacknowledged_record_absent"];
+/**
+ * Whether `s`, the text between a host's brackets, is an IPv6 address as the
+ * WHATWG URL Standard's IPv6 parser accepts one (RFC 4291 text form), in
+ * lowercase. A step for step port of the parser, the twin of Python's
+ * `is_ipv6_text` and the runner's `run.IsPlaneOrigin`.
+ */
+export declare function isIpv6Text(s: string): boolean;
+/** The object does not read under the one spelling. The message is the reason. */
+export declare class AttestationRefused extends Error {
+}
+/** `attestation_version` is a string this reader does not know. */
+export declare class UnknownAttestationVersion extends AttestationRefused {
+}
+/** `sanning.run-binding/v1`, read strictly from the evidence. */
+export interface Binding {
+    runId: string;
+    manifestHash: string;
+    runnerPublicKey: string;
+    agentPublicKey: string;
+    credentialPublicKey: string;
+    caseHash: string;
+    /**
+     * The plane's origin the runner claimed the run from (section 4). Carried,
+     * not compared: the plane refuses a claim whose binding names another plane.
+     */
+    plane: string;
+    request: Readonly<Record<string, unknown>>;
+}
+/** `sanning.enclave-attestation/v1`, read strictly. */
+export interface Attestation {
+    runnerPublicKey: string;
+    agentPublicKey: string;
+    manifestHash: string;
+    runId: string;
+    provider: string;
+    evidence: Readonly<Record<string, unknown>>;
+    /** The binding the evidence carries, for a registered provider; else null. */
+    binding: Binding | null;
+}
+/**
+ * Read the `enclave_attestation` member of an opening record strictly. Throws
+ * `UnknownAttestationVersion` for a version string this reader does not know,
+ * and `AttestationRefused` for anything else that is not the one spelling.
+ */
+export declare function readAttestation(value: unknown): Attestation;
+/** `readAttestation` over bytes that must be `JCS(object)`. */
+export declare function readAttestationJson(raw: Uint8Array): Attestation;
+/**
+ * What an adapter answers (checks 2 to 6 and 8). `binding` is the binding the
+ * adapter verified its evidence commits to: `confirmed` without one is outside
+ * the contract and reads `adapter_failed`, because the kernel runs checks 7
+ * and 11 on that binding. Each kind is one the adapter declares in `kinds`.
+ */
+export interface AdapterResult {
+    state: (typeof ENCLAVE_STATES)[number];
+    kinds?: readonly string[];
+    /** The verified token's issue time, seconds since the epoch, or null. */
+    issuedAt?: number | null;
+    imageId?: string | null;
+    hwModel?: string | null;
+    tokenChecked?: boolean;
+    binding?: Binding | null;
+}
+/**
+ * An adapter: the provider it answers for, the failure kinds it declares, its
+ * check, and optionally the online line.
+ */
+export interface EnclaveAdapter {
+    provider: string;
+    kinds: readonly string[];
+    check(attestation: Attestation, options: {
+        policy: Readonly<Record<string, unknown>>;
+        at: string | null;
+    }): AdapterResult | Promise<AdapterResult>;
+    online?(attestation: Attestation, options: {
+        policy: Readonly<Record<string, unknown>>;
+        at: string | null;
+        manifest: Uint8Array | null;
+        rpc: string;
+    }): OnlineLine | Promise<OnlineLine>;
+}
+/**
+ * The online line (section 8): what the chain says of a `flare-fcc` opening,
+ * read by the adapter at the offline line's evaluation time. `confirmed`
+ * carries no kind; `not_checked` and `differs` carry one. It moves nothing.
+ */
+export interface OnlineLine {
+    state: (typeof ENCLAVE_STATES)[number];
+    kinds: string[];
+}
+export interface EnclaveLine {
+    state: (typeof ENCLAVE_STATES)[number];
+    kinds: string[];
+    notes: string[];
+    reason: string | null;
+    provider: string | null;
+    evaluatedAt: string | null;
+    evaluation: "stamp" | "token_issue_time" | null;
+    tokenChecked: boolean;
+}
+export interface AccountEntry {
+    kind: string;
+    eventId: string | null;
+}
+export interface RunAccountLine {
+    state: (typeof RUN_ACCOUNT_STATES)[number];
+    findings: AccountEntry[];
+    notes: AccountEntry[];
+    closingEventId: string | null;
+    reason: string | null;
+}
+export interface RunReading {
+    /** The pack by the reader's name for it; two packs can share one (A43). */
+    packRef: string;
+    /** The pack's position among the packs read, as the case reading's `pack_index`. */
+    packIndex: number;
+    eventId: string;
+    runnerPublicKey: string;
+    agentPublicKey: string | null;
+    enclave: EnclaveLine;
+    account: RunAccountLine;
+    /** The online line, where the reader asked for one and the adapter reads the chain; else null. */
+    online: OnlineLine | null;
+}
+export interface RunsReading {
+    runs: RunReading[];
+}
+/** One pack, as `readCase` takes it. */
+export interface RunPack {
+    ref: string;
+    bundle: unknown;
+    content?: SideContentMap | null;
+}
+/**
+ * The time the token is evaluated at (7): the interval end of a stamp that
+ * holds the opening record and whose witness the reader's lookup confirmed;
+ * otherwise null, the token's own issue time.
+ */
+/**
+ * @internal For the kernel's own tests: the enclave line of one opening record,
+ * verified as the caller says, under a provider table the caller names. It is
+ * how a test reaches a provider outside `ADAPTER_MODULES`; `readRuns` always
+ * reads under `ADAPTER_MODULES`.
+ */
+export declare function enclaveLineForTest(record: Record<string, unknown>, publicKey: string, content: Uint8Array | null, policy: unknown, adapters: ReadonlyMap<string, EnclaveAdapter>, table: Readonly<Record<string, string>>): Promise<EnclaveLine>;
+/**
+ * The failure kinds an adapter declares as its `kinds`: an array of snake_case
+ * strings, at least one, none of them a kind or note the kernel names
+ * (`NEUTRAL_KINDS`). `null` where the declaration is not of that form, an
+ * empty one included, and then the adapter is not loaded.
+ */
+export declare function declaredKinds(adapter: unknown): ReadonlySet<string> | null;
+export declare function readRuns(packs: readonly RunPack[], options?: {
+    policy?: unknown;
+    adapters?: ReadonlyMap<string, EnclaveAdapter> | null;
+    /** A chain endpoint for the online line, handed to an adapter that reads one. */
+    rpc?: string | null;
+    /**
+     * For each pack by position, the `stamp_ref` of every stamp whose witness
+     * the caller looked up and the public record confirmed (the on-chain
+     * half's `confirm`). A token is evaluated at a stamp's interval end only
+     * there, and at its own issue time otherwise. Absent: no lookup.
+     */
+    witnessed?: readonly (readonly string[] | null | undefined)[] | null;
+}): Promise<RunsReading>;
+/** The enclave line, the revocation sentence where a token was checked, and the online line. */
+export declare function renderEnclaveLines(r: RunReading): string[];
+/** The run-account line (specs/run-records.md). */
+export declare function renderAccountLine(r: RunReading): string;