@zanii/blackbox 0.3.0 → 0.5.0

package/dist/session/index.js

@@ -6,7 +6,19 @@ import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { argsHash } from "../approvals/index.js";
 import { attest, isReadOnly } from "../attest/index.js";
+import { buildPayment, ftaPayload, screeningPayload, } from "../finance/index.js";
+import { decisionPayload } from "../gov/index.js";
+import { accessPayload, checkEpisodeTag, recommendationPayload, verifyHealthSignature, } from "../health/index.js";
+import { memoryEntry } from "../memory/index.js";
+/** spec/preflight.md §1 (L3): with an `egress` item, the SDK checks it here, on the agent's host. */
+async function withEgress(p) {
+    if (![...(p.require ?? []), ...(p.optional ?? [])].includes("egress"))
+        return p;
+    const { url, open } = await checkEgress({ timeoutMs: 3000 });
+    return { ...p, egress: { url, open } };
+}
 /** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
 export async function checkEgress(options = {}) {
     const url = options.url ?? "https://example.com";
@@ -71,7 +83,9 @@ export async function session(options) {
                 ...(o.replay ? { replay: o.replay } : {}),
                 ...(o.tenant ? { tenant: o.tenant } : {}),
                 ...(o.authority ? { authority: o.authority } : {}),
-                ...(o.preflight ? { preflight: o.preflight } : {}),
+                ...(o.environment ? { environment: o.environment } : {}),
+                ...(o.holdStreams !== undefined ? { hold_streams: o.holdStreams } : {}),
+                ...(o.preflight ? { preflight: await withEgress(o.preflight) } : {}),
                 ...(o.drill ? { drill: o.drill } : {}),
                 sdk: true, // this SDK will report the session's model calls (L2.3.2)
             });
@@ -103,6 +117,10 @@ export class BlackboxSession {
     timers = [];
     closed = false;
     landings = 0;
+    /** spec/approvals.md §2: approved tools with arguments, until their call is reported. */
+    approved = new Map();
+    /** spec/agents.md §4: the memory chain's tip. */
+    memoryLast = null;
     /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
     static disabled(options, reason) {
         const s = new BlackboxSession(options, "", "", false);
@@ -208,8 +226,82 @@ export class BlackboxSession {
     step(name, data) {
         this.event("step", name, data);
     }
+    /**
+     * spec/gov.md §2: a decision about a person, under the rulebook `manifestHash`, the person named
+     * only by their subject tag. Returns the factors' nonce (keep it to disclose them in a dispute).
+     * Throws on a decision that can't be lawful evidence: no rulebook, a bad kind, no tag.
+     */
+    decision(kind, o) {
+        if (!/^sha256:[0-9a-f]{64}$/.test(o.subjectTag))
+            throw new Error("subjectTag must be a subject tag (subjectTag(did, authority))");
+        const { payload, nonce } = decisionPayload({
+            kind,
+            manifestHash: o.manifestHash,
+            outcome: o.outcome,
+            ts: new Date().toISOString(),
+            ...(o.factors !== undefined ? { factors: o.factors } : {}),
+            ...(o.appealBy !== undefined ? { appealBy: o.appealBy } : {}),
+        });
+        this.event("decision", kind, { decision: payload, subject_tag: o.subjectTag });
+        return { nonce };
+    }
+    /** spec/health.md §2: who accessed a patient's record (an episode tag, never the seed), and why. */
+    healthAccess(o) {
+        const tag = checkEpisodeTag(o.episodeTag);
+        const { payload, nonce } = accessPayload({ ...o, ts: new Date().toISOString() });
+        this.event("health.access", "access", { payload, episode_tag: tag });
+        return { nonce };
+    }
+    /** spec/health.md §2: a model's recommendation under a protocol. `hash` is what the clinician signs. */
+    recommendation(o) {
+        const tag = checkEpisodeTag(o.episodeTag);
+        const { payload, nonce, hash } = recommendationPayload({ ...o, ts: new Date().toISOString() });
+        this.event("health.recommendation", "recommendation", { payload, episode_tag: tag });
+        return { nonce, hash };
+    }
+    /** spec/health.md §2: a clinician's signed confirmation (clinicianConfirmation). Throws on a bad signature. */
+    clinicianConfirmation(episodeTag, payload) {
+        this.signedHealth(episodeTag, payload, "confirmation");
+    }
+    /** spec/health.md §2: an emergency access, signed by the clinician (breakGlass). Loud on purpose. */
+    breakGlass(episodeTag, payload) {
+        this.signedHealth(episodeTag, payload, "break_glass");
+    }
+    signedHealth(episodeTag, payload, kind) {
+        const tag = checkEpisodeTag(episodeTag);
+        if (payload.kind !== kind || !verifyHealthSignature(payload, tag))
+            throw new Error(`not a ${kind} signed by the clinician it names, for this episode`);
+        this.event(`health.${kind}`, kind, { payload, episode_tag: tag });
+    }
+    /** spec/finance.md §2: a payment, exact (minor units), with its settlement reference. Throws on a bad amount. */
+    payment(input) {
+        this.event("payment", input.rail, buildPayment(input));
+    }
+    /** spec/finance.md §3: a counterparty screening (screenCounterparty), before paying them. */
+    screening(result) {
+        this.event("kya.screening", result.did, screeningPayload(result, new Date().toISOString(), this.id));
+    }
+    /** spec/finance.md §4: a tax filing the agent prepared. It never files; a Tax Agent does. */
+    ftaPrepared(o) {
+        this.event("fta.prepared", o.filingType, ftaPayload({ ...o, action: "prepared", by: o.by ?? this.id }));
+    }
+    /** spec/finance.md §4: the prepared filing handed to a licensed Tax Agent. */
+    ftaHandoff(o) {
+        this.event("fta.handoff", o.filingType, ftaPayload({ ...o, action: "handoff", by: o.by ?? this.id }));
+    }
     toolCall(name, args) {
-        this.event("tool.call", name, args === undefined ? undefined : { args });
+        // spec/approvals.md §2: the first call after an approval names it, with what it ran
+        const approvalId = this.approved.get(name);
+        if (approvalId !== undefined)
+            this.approved.delete(name);
+        this.event("tool.call", name, args === undefined && approvalId === undefined
+            ? undefined
+            : {
+                ...(args !== undefined ? { args } : {}),
+                ...(approvalId !== undefined
+                    ? { approval_id: approvalId, args_sha256: argsHash(args ?? null) }
+                    : {}),
+            });
     }
     toolResult(name, result) {
         this.event("tool.result", name, result);
@@ -277,6 +369,30 @@ export class BlackboxSession {
     contextChange(change) {
         this.event("context.change", change.kind, { ...change });
     }
+    /** spec/findings.md §11 (H3): pin the documents the agent read, by hash; the content never leaves.
+     * Each doc is `{id, uri?, version?}` with its `content` (hashed here) or its `sha256`. */
+    retrieved(docs) {
+        const out = [];
+        for (const d of docs.slice(0, 100)) {
+            if (typeof d?.id !== "string" || d.id.length < 1)
+                continue;
+            const bytes = typeof d.content === "string" ? Buffer.from(d.content) : d.content;
+            const sha256 = bytes
+                ? `sha256:${createHash("sha256").update(bytes).digest("hex")}`
+                : d.sha256;
+            if (typeof sha256 !== "string" || !/^sha256:[0-9a-f]{64}$/.test(sha256))
+                continue;
+            out.push({
+                id: d.id.slice(0, 256),
+                ...(typeof d.uri === "string" ? { uri: d.uri.slice(0, 2048) } : {}),
+                ...(typeof d.version === "string" ? { version: d.version.slice(0, 128) } : {}),
+                sha256,
+                ...(bytes ? { bytes: bytes.length } : {}),
+            });
+        }
+        if (out.length)
+            this.event("retrieved", undefined, { docs: out });
+    }
     /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
      * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
      * check failed is FALSE_SUCCESS (spec/findings.md §6). */
@@ -338,8 +454,22 @@ export class BlackboxSession {
         this.event("screen", undefined, data, { attachment: { contentType: type, bytes: image } });
     }
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
-    memoryWrite(memoryId, summary) {
-        this.event("memory.write", undefined, { memory_id: memoryId, ...(summary ? { summary } : {}) });
+    /** spec/agents.md §4: with `content`, the write also carries Zanii's memory entry (a salted
+     * commitment, chained after `prev`, else this session's last entry). Keep the salt it returns. */
+    memoryWrite(memoryId, summary, opts) {
+        const data = { memory_id: memoryId, ...(summary ? { summary } : {}) };
+        let made;
+        if (opts) {
+            made = memoryEntry({
+                ...opts,
+                ts: new Date().toISOString(),
+                prev: opts.prev ?? this.memoryLast,
+            });
+            this.memoryLast = made.payload;
+            data.entry = made.payload;
+        }
+        this.event("memory.write", undefined, data);
+        return made && { entry: made.payload, salt: made.salt };
     }
     memoryRevoke(memoryId, reason) {
         this.event("memory.revoke", undefined, { memory_id: memoryId, ...(reason ? { reason } : {}) });
@@ -392,21 +522,43 @@ export class BlackboxSession {
         }
         return null;
     }
+    /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,
+     * for an app that streams the answer by itself: `{seq, risks, hold}`. `hold` says whether the
+     * server would hold it. `null` when there's no answer yet or the gateway can't be asked. */
+    async checkAnswer(seq) {
+        if (!this.enabled)
+            return null;
+        const at = seq === undefined ? "latest" : String(seq);
+        try {
+            const r = await send("GET", this.options.url, `/v1/sessions/${this.id}/answers/${at}/risk`, this.token);
+            if (r.status === 200)
+                return r.json;
+            if (r.status !== 404)
+                this.fail("rejected", `checking the answer: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.fail("network", `checking the answer: ${message(error)}`);
+        }
+        return null;
+    }
     /** spec/approvals.md §2: asks a second person before running one of the agent's own risky tools,
      * and waits (polling) for the answer. Never throws. Only `"approved"` means go ahead; anything
      * else (`rejected`, `timeout`, or `error` when the gateway can't be asked) means don't. */
     async requestApproval(tool, options = {}) {
-        return this.ask("approvals", { tool, ...(options.args ? { args: options.args } : {}) }, options);
+        const { status, id } = await this.ask("approvals", { tool, ...(options.args ? { args: options.args } : {}) }, options);
+        if (status === "approved" && options.args && id)
+            this.approved.set(tool, id);
+        return status;
     }
     /** N2 (idea C2): asks a person to let this session use a gateway tool its policy denies (the
      * denial's `requires.tool`, e.g. `mcp__files__delete`). A yes is a standing grant for the
      * session: retry the call. Answers like `requestApproval`. Never throws. */
     async requestPermission(tool, options = {}) {
-        return this.ask("permissions", { tool }, options);
+        return (await this.ask("permissions", { tool }, options)).status;
     }
     async ask(route, body, options) {
         if (!this.enabled)
-            return "error";
+            return { status: "error" };
         try {
             const r = await post(this.options.url, `/v1/sessions/${this.id}/${route}`, this.token, {
                 ...body,
@@ -415,21 +567,21 @@ export class BlackboxSession {
             const id = r.json.approval_id;
             if (r.status !== 201 || typeof id !== "string") {
                 this.fail("rejected", `asking for an approval: the gateway answered ${r.status}`);
-                return "error";
+                return { status: "error" };
             }
             const deadline = Date.now() + (options.timeoutMs ?? 310_000);
             while (Date.now() < deadline) {
                 const s = await send("GET", this.options.url, `/v1/sessions/${this.id}/approvals/${id}`, this.token);
                 const status = s.json.status;
                 if (status === "approved" || status === "rejected" || status === "timeout")
-                    return status;
+                    return { status, id };
                 await sleep(options.pollMs ?? 1_000);
             }
-            return "timeout";
+            return { status: "timeout", id };
         }
         catch (error) {
             this.fail("network", `asking for an approval: ${message(error)}`);
-            return "error";
+            return { status: "error" };
         }
     }
     /** Audit S8: `await using s = await session(…)` closes the session when the scope ends. */

package/dist/sla/index.d.ts

@@ -0,0 +1,61 @@
+type Obj = Record<string, unknown>;
+type Commitments = {
+    min_actions?: number;
+    max_actions?: number;
+    max_gap_ms?: number;
+};
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export declare function buildSlaBody(o: {
+    provider: string;
+    client: string;
+    scope: string;
+    window: {
+        start: string;
+        end: string;
+    };
+    commitments: Commitments;
+    price?: {
+        amount: string;
+        currency: string;
+    };
+    createdAt: string;
+    ref?: string;
+}): Obj;
+/** One party signs the terms. Collect the provider's and the client's. */
+export declare const signSla: (body: Obj, did: string, privateKey: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSla: (body: Obj, signatures: Array<{
+    did: string;
+    sig: string;
+}>) => {
+    body: Obj;
+    signatures: {
+        did: string;
+        sig: string;
+    }[];
+};
+export declare const slaHash: (sla: Obj) => string;
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export declare function verifySla(sla: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export declare function assessCompliance(sla: Obj, receipts: readonly unknown[], asOf?: string): {
+    ok: boolean;
+    breaches: {
+        kind: string;
+        detail: string;
+    }[];
+    metrics: {
+        actions: number;
+        max_gap_ms: number | null;
+    };
+};
+export {};

package/dist/sla/index.js

@@ -0,0 +1,197 @@
+// Service agreements proven from receipts (spec/anchoring.md §14): Zanii's SLA, co-signed terms
+// whose compliance is computed from the provider's consecutive receipt chain, the same verdict for
+// everyone (@zanii/sla). Pure; mirrors sdks/python/src/zanii_blackbox/sla.py; pinned by
+// spec/vectors/sla.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid, receiptHash, scopeCovers, verifyReceipt, } from "@zanii/core";
+import { parseMoney } from "../finance/index.js";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const ms = (ts) => {
+    if (typeof ts !== "string")
+        return null;
+    const t = Date.parse(ts);
+    return Number.isNaN(t) ? null : t;
+};
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export function buildSlaBody(o) {
+    if (!o.provider || !o.client)
+        throw new Error("provider and client are required");
+    if (o.provider === o.client)
+        throw new Error("provider and client must differ");
+    if (!o.scope)
+        throw new Error("scope is required (the target pattern the service receipts match)");
+    const start = ms(o.window.start);
+    const end = ms(o.window.end);
+    if (start === null || end === null)
+        throw new Error("window start/end must be ISO timestamps");
+    if (start >= end)
+        throw new Error("window start must be before end");
+    if (ms(o.createdAt) === null)
+        throw new Error("created_at must be an ISO timestamp");
+    const c = { ...o.commitments };
+    for (const [k, v] of Object.entries(c))
+        if (v !== undefined && v !== null && !isCount(v))
+            throw new Error(`commitment ${k} must be a non-negative integer`);
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        throw new Error("an SLA with no commitments commits to nothing");
+    if (c.min_actions != null && c.max_actions != null && c.min_actions > c.max_actions)
+        throw new Error("min_actions must not exceed max_actions");
+    return {
+        v: 1,
+        type: "sla",
+        provider: o.provider,
+        client: o.client,
+        scope: o.scope,
+        window: { start: o.window.start, end: o.window.end },
+        commitments: c,
+        created_at: o.createdAt,
+        ...(o.price ? { price: parseMoney(o.price.amount, o.price.currency) } : {}),
+        ...(o.ref !== undefined ? { ref: o.ref } : {}),
+    };
+}
+/** One party signs the terms. Collect the provider's and the client's. */
+export const signSla = (body, did, privateKey) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(privateKey, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSla = (body, signatures) => ({
+    body,
+    signatures,
+});
+export const slaHash = (sla) => jcsHash(sla);
+const sigValid = (body, did, sig) => {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    return Boolean(pub && m && ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex")));
+};
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export function verifySla(sla) {
+    const reasons = [];
+    const e = (sla ?? {});
+    const b = e.body ?? {};
+    if (b.v !== 1 || b.type !== "sla")
+        reasons.push("not an sla (v1)");
+    const { provider, client } = b;
+    if (!provider || !client || provider === client)
+        reasons.push("missing/invalid parties");
+    if (!b.scope)
+        reasons.push("missing scope");
+    const w = (b.window ?? {});
+    const start = ms(w.start);
+    const end = ms(w.end);
+    if (start === null || end === null || start >= end)
+        reasons.push("invalid window");
+    const c = (b.commitments ?? {});
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        reasons.push("no commitments");
+    if (reasons.length === 0)
+        for (const [party, role] of [
+            [provider, "provider"],
+            [client, "client"],
+        ]) {
+            const s = (e.signatures ?? []).find((x) => x.did === party);
+            if (!s)
+                reasons.push(`missing signature from ${role}`);
+            else if (!sigValid(b, String(s.did), s.sig))
+                reasons.push(`invalid signature from ${role}`);
+        }
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export function assessCompliance(sla, receipts, asOf) {
+    const agreement = verifySla(sla);
+    if (!agreement.ok)
+        return {
+            ok: false,
+            breaches: agreement.reasons.map((r) => ({ kind: "INVALID_RECEIPT", detail: `sla: ${r}` })),
+            metrics: { actions: 0, max_gap_ms: null },
+        };
+    const b = sla.body;
+    const breaches = [];
+    const winStart = ms(b.window.start);
+    const winEnd = ms(b.window.end);
+    if (asOf !== undefined && ms(asOf) === null)
+        throw new Error("as_of must be an ISO timestamp");
+    const asOfMs = Math.min(asOf !== undefined ? ms(asOf) : winEnd, winEnd);
+    // a stable sort, as Python's sorted
+    const sorted = receipts
+        .map((r, i) => ({ r, i, t: ms(r.ts) ?? 0 }))
+        .sort((x, y) => x.t - y.t || x.i - y.i)
+        .map((x) => x.r);
+    for (const r of sorted) {
+        let check;
+        try {
+            check = verifyReceipt(r);
+        }
+        catch (error) {
+            check = { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!check.ok)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: check.error || "invalid receipt",
+                receipt: receiptHash(r),
+            });
+        else if (r.agent_id !== b.provider)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: `receipt by ${r.agent_id}, not the provider`,
+                receipt: receiptHash(r),
+            });
+    }
+    for (let i = 1; i < sorted.length; i++)
+        if (sorted[i].prev !== receiptHash(sorted[i - 1]))
+            breaches.push({
+                kind: "INCOMPLETE_RECORD",
+                detail: `chain break between receipts #${i - 1} and #${i} — the slice is not the provider's consecutive record`,
+                receipt: receiptHash(sorted[i]),
+            });
+    const matching = sorted.filter((r) => {
+        const t = ms(r.ts);
+        return (t !== null && winStart <= t && t <= winEnd && scopeCovers(String(b.scope), r.target || ""));
+    });
+    const c = b.commitments;
+    if (c.min_actions != null && matching.length < c.min_actions)
+        breaches.push({
+            kind: "TOO_FEW_ACTIONS",
+            detail: `${matching.length} matching actions < committed minimum ${c.min_actions}`,
+        });
+    if (c.max_actions != null && matching.length > c.max_actions)
+        breaches.push({
+            kind: "TOO_MANY_ACTIONS",
+            detail: `${matching.length} matching actions > committed maximum ${c.max_actions}`,
+        });
+    let maxGap = null;
+    if (matching.length > 0) {
+        const times = matching.map((r) => ms(r.ts));
+        const gaps = [[times[0] - winStart, null]];
+        for (let i = 1; i < times.length; i++)
+            gaps.push([times[i] - times[i - 1], matching[i - 1]]);
+        const last = times[times.length - 1];
+        if (asOfMs > last)
+            gaps.push([asOfMs - last, matching[matching.length - 1]]);
+        maxGap = Math.max(...gaps.map(([g]) => g));
+        if (c.max_gap_ms != null)
+            for (const [g, after] of gaps)
+                if (g > c.max_gap_ms)
+                    breaches.push({
+                        kind: "MAX_GAP_EXCEEDED",
+                        detail: `${g}ms of silence > committed max ${c.max_gap_ms}ms`,
+                        ...(after ? { receipt: receiptHash(after) } : {}),
+                    });
+    }
+    else if (c.max_gap_ms != null && asOfMs - winStart > c.max_gap_ms)
+        breaches.push({
+            kind: "MAX_GAP_EXCEEDED",
+            detail: `no matching actions for ${asOfMs - winStart}ms > committed max ${c.max_gap_ms}ms`,
+        });
+    return {
+        ok: breaches.length === 0,
+        breaches,
+        metrics: { actions: matching.length, max_gap_ms: maxGap },
+    };
+}

package/dist/succession/index.d.ts

@@ -0,0 +1,50 @@
+export type SuccessionReason = "rotation" | "compromise" | "retirement";
+export interface SuccessionBody {
+    v: 1;
+    type: "succession";
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: SuccessionReason;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}
+export interface Succession {
+    body: SuccessionBody;
+    signatures: Array<{
+        did: string;
+        sig: string;
+    }>;
+}
+export declare function buildSuccessionBody(input: {
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: string;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}): SuccessionBody;
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export declare const signSuccession: (body: SuccessionBody, did: string, seed: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSuccession: (body: SuccessionBody, signatures: Succession["signatures"]) => Succession;
+export declare const successionHash: (s: Succession) => string;
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export declare function verifySuccession(s: unknown): {
+    ok: boolean;
+    reasons: string[];
+    cosigned: boolean;
+};
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export declare function verifyLineage(successions: unknown[], did: string): {
+    ok: boolean;
+    reasons: string[];
+    lineage: string[];
+};