@common-agent/reputations 0.0.0-stage → 0.1.0

package/dist/ledger.d.ts

@@ -0,0 +1,92 @@
+import { type ScoredEvent } from "./score.js";
+/** The prev_hash of a chain's first entry. */
+export declare const GENESIS = "genesis";
+/**
+ * The ledger's actions (§4.1). This bureau writes enrolled, withdrew, fact and
+ * attested today; the rest are the standard's, named so a reader of any
+ * chain knows them: amended (an enrollment's capabilities changed), probed
+ * (§4.3), stopped (§4.6), nda_claimed, nda_answered and nda_resolved (§4.8),
+ * excluded (§6.4) and corrected (§10, a data-error repair appended, never a
+ * rewrite).
+ */
+export type LedgerAction = "enrolled" | "amended" | "withdrew" | "fact" | "attested" | "probed" | "stopped" | "nda_claimed" | "nda_answered" | "nda_resolved" | "excluded" | "corrected";
+export declare const LEDGER_ACTIONS: readonly LedgerAction[];
+/** Evidence source, ranked. Higher rank wins the interaction (§6.3).
+ *  `value` is the §6.6 value judgment: an attestation like a review, so it
+ *  outranks the mechanical layers the same way — but it never competes with
+ *  one, because the two cannot both exist for the same engagement (a
+ *  document either names deliverables or it does not). `floor_miss` (Agent
+ *  SoW §5.14) sits with `form_check`: both are mechanical verdicts derived
+ *  from the engagement record, and either outranks the bare task fact.
+ *  `interview` (SPEC.md §3.3.1) ranks with `task` — moot in practice, since
+ *  interview outcomes sit outside the scoring table and its interaction ids
+ *  collide with nothing, but a rank above 1 could let a non-scoring entry
+ *  suppress a scoring one if an id ever did collide. `dispute` (§4.4: a fact,
+ *  recorded and never scored) ranks 0, below everything, so even a dispute
+ *  fact whose interaction id collided with a task's could never take that
+ *  task's place; its ids are the dispute's own besides. */
+export declare const SOURCE_RANK: Record<string, number>;
+export interface LedgerEntry {
+    subject: string;
+    seq: number;
+    at: string;
+    action: LedgerAction;
+    capability: string;
+    detail: string;
+    prev_hash: string;
+    entry_hash: string;
+    /**
+     * How entry_hash was made. 1, or absent: this bureau's first construction,
+     * lowercase hex SHA-256 over the canonical JSON of the entry with prev_hash
+     * inside it. 2: the standard's (§4.1), base64 SHA-256 over the canonical
+     * JSON of the entry without the two hash fields, its detail as an object,
+     * followed by prev_hash. A chain may hold both; each entry says which.
+     */
+    hash_v?: 1 | 2;
+}
+/** The hash an entry should carry, by its hash_v. `canonical` is the platform's canonical JSON, which made the first construction's bytes. */
+export declare function entryHashOf(entry: Omit<LedgerEntry, "entry_hash">, canonical?: (v: unknown) => string): string;
+/** Walk one subject's chain start to end, recomputing every link, whichever construction each entry used. */
+export declare function verifyChainEntries(rows: readonly LedgerEntry[], canonical?: (v: unknown) => string): {
+    ok: boolean;
+    count: number;
+    brokenAt?: number;
+};
+export interface EnrollmentInfo {
+    state: "UNENROLLED" | "ENROLLED" | "WITHDRAWN";
+    enrolled_at?: string;
+    withdrew_at?: string;
+    /** Withdrawal takes effect after cooling-off (§3.3); until then evidence
+     *  continues to land and the subject still reads as enrolled. */
+    withdrawal_effective_at?: string;
+}
+export interface PoolResult {
+    events: ScoredEvent[];
+    declined: number;
+    scoredInteractions: number;
+    silentFailures: number;
+    attesterAnchors: Map<string, number>;
+    /** How many scored events are §6.6 value judgments. The report's
+     *  `value_judgment_share` is a WEIGHT share and comes from scorePool; this
+     *  count is what decides whether the field is required at all. */
+    valueJudgments: number;
+    /** SPEC §10.8a: failures the platform attributed to the CLIENT — the caller
+     *  did not furnish something the offering declared it needed. Recorded and
+     *  never scored, and counted here so that "not scored" does not become
+     *  "invisible": a reader can see that the ending happened without it costing
+     *  the provider anything. */
+    notFurnished: number;
+    oldest?: string;
+    newest?: string;
+}
+/** Enrollment state from a subject's enrollment acts, in chain order (§3).
+ *  Cooling-off: a withdrawal only takes effect `coolingOffDays` after it was
+ *  filed. */
+export declare function enrollmentFromActs(acts: readonly LedgerEntry[], nowMs: number, coolingOffDays?: number): EnrollmentInfo;
+/**
+ * The quality pool drawn from evidence rows (§7.1). Per interaction, the
+ * highest-ranked evidence class scores (§6.3); everything stays in the
+ * ledger regardless. De-duplication is per interaction across all the rows
+ * given, so the same rule serves one subject and an organisation's agents.
+ */
+export declare function poolFromEntries(rows: readonly LedgerEntry[]): PoolResult;

package/dist/ledger.js

@@ -0,0 +1,157 @@
+/**
+ * The pure rules of the bureau's ledger (Agent Reputations §3, §4, §6.3).
+ *
+ * The ledger itself, the bureau's store,
+ * stores the entries and keeps each subject's hash chain. What does not need
+ * a database lives here: the entry and result shapes, which evidence wins an
+ * interaction when evidence disagrees, how the scoring pool is drawn from the
+ * evidence, and what a subject's enrollment acts add up to. Each takes rows
+ * and returns a value, so anyone holding the rows computes the same answer.
+ *
+ * The shapes are an earlier bureau's own, from before 0.6.0; pool.ts holds
+ * the standard's.
+ */
+import { createHash } from "node:crypto";
+import { OUTCOME_VALUES, UNSCORED_OUTCOMES } from "./score.js";
+import { jcs } from "./signing.js";
+/** The prev_hash of a chain's first entry. */
+export const GENESIS = "genesis";
+export const LEDGER_ACTIONS = [
+    "enrolled", "amended", "withdrew", "fact", "attested", "probed", "stopped",
+    "nda_claimed", "nda_answered", "nda_resolved", "excluded", "corrected",
+];
+/** Evidence source, ranked. Higher rank wins the interaction (§6.3).
+ *  `value` is the §6.6 value judgment: an attestation like a review, so it
+ *  outranks the mechanical layers the same way — but it never competes with
+ *  one, because the two cannot both exist for the same engagement (a
+ *  document either names deliverables or it does not). `floor_miss` (Agent
+ *  SoW §5.14) sits with `form_check`: both are mechanical verdicts derived
+ *  from the engagement record, and either outranks the bare task fact.
+ *  `interview` (SPEC.md §3.3.1) ranks with `task` — moot in practice, since
+ *  interview outcomes sit outside the scoring table and its interaction ids
+ *  collide with nothing, but a rank above 1 could let a non-scoring entry
+ *  suppress a scoring one if an id ever did collide. `dispute` (§4.4: a fact,
+ *  recorded and never scored) ranks 0, below everything, so even a dispute
+ *  fact whose interaction id collided with a task's could never take that
+ *  task's place; its ids are the dispute's own besides. */
+export const SOURCE_RANK = { task: 1, form_check: 2, floor_miss: 2, interview: 1, dispute: 0, review: 3, value: 3 };
+/** The hash an entry should carry, by its hash_v. `canonical` is the platform's canonical JSON, which made the first construction's bytes. */
+export function entryHashOf(entry, canonical = jcs) {
+    if ((entry.hash_v ?? 1) === 2) {
+        const { prev_hash, ...rest } = entry;
+        const body = jcs({ ...rest, detail: JSON.parse(entry.detail) });
+        return createHash("sha256").update(body + prev_hash, "utf8").digest("base64");
+    }
+    // The first construction hashed the row as it was stored, which held no hash_v.
+    const { hash_v: _v, ...v1 } = entry;
+    return createHash("sha256").update(canonical(v1)).digest("hex");
+}
+/** Walk one subject's chain start to end, recomputing every link, whichever construction each entry used. */
+export function verifyChainEntries(rows, canonical) {
+    let prev = GENESIS;
+    for (const row of rows) {
+        const { entry_hash, ...rest } = row;
+        if (row.prev_hash !== prev || entryHashOf(rest, canonical) !== entry_hash)
+            return { ok: false, count: rows.length, brokenAt: row.seq };
+        prev = entry_hash;
+    }
+    return { ok: true, count: rows.length };
+}
+/** Enrollment state from a subject's enrollment acts, in chain order (§3).
+ *  Cooling-off: a withdrawal only takes effect `coolingOffDays` after it was
+ *  filed. */
+export function enrollmentFromActs(acts, nowMs, coolingOffDays = 30) {
+    if (!acts.length)
+        return { state: "UNENROLLED" };
+    let enrolledAt;
+    let withdrewAt;
+    for (const act of acts) {
+        if (act.action === "enrolled") {
+            enrolledAt = act.at;
+            withdrewAt = undefined;
+        }
+        else {
+            withdrewAt = act.at;
+        }
+    }
+    if (withdrewAt) {
+        const effective = new Date(Date.parse(withdrewAt) + coolingOffDays * 86_400_000).toISOString();
+        if (nowMs >= Date.parse(effective)) {
+            return { state: "WITHDRAWN", enrolled_at: enrolledAt, withdrew_at: withdrewAt, withdrawal_effective_at: effective };
+        }
+        return { state: "ENROLLED", enrolled_at: enrolledAt, withdrew_at: withdrewAt, withdrawal_effective_at: effective };
+    }
+    return { state: "ENROLLED", enrolled_at: enrolledAt };
+}
+/**
+ * The quality pool drawn from evidence rows (§7.1). Per interaction, the
+ * highest-ranked evidence class scores (§6.3); everything stays in the
+ * ledger regardless. De-duplication is per interaction across all the rows
+ * given, so the same rule serves one subject and an organisation's agents.
+ */
+export function poolFromEntries(rows) {
+    const byInteraction = new Map();
+    // When each interaction ended (§7.2): its fact's ended_at, or the fact's own
+    // time for a fact recorded without one. Every event about the interaction,
+    // an attestation signed weeks later included, takes that age.
+    const endedAt = new Map();
+    let anonSeq = 0;
+    const parsed = rows.map((row) => ({
+        row,
+        d: JSON.parse(row.detail),
+    }));
+    for (const { row, d } of parsed) {
+        if (row.action === "fact" && d.interaction_id && !endedAt.has(d.interaction_id))
+            endedAt.set(d.interaction_id, d.ended_at ?? row.at);
+    }
+    for (const { row, d } of parsed) {
+        const id = d.interaction_id ?? `anon_${anonSeq++}`;
+        const rank = SOURCE_RANK[d.source ?? "task"] ?? 1;
+        const prev = byInteraction.get(id);
+        if (!prev || rank >= prev.rank) {
+            byInteraction.set(id, { outcome: d.outcome ?? d.derived_outcome ?? "", at: endedAt.get(id) ?? d.ended_at ?? row.at, rank, evaluator: d.evaluator, source: d.source });
+        }
+    }
+    const result = {
+        events: [],
+        declined: 0,
+        scoredInteractions: 0,
+        silentFailures: 0,
+        attesterAnchors: new Map(),
+        valueJudgments: 0,
+        notFurnished: 0,
+    };
+    for (const best of byInteraction.values()) {
+        if (best.evaluator) {
+            result.attesterAnchors.set(best.evaluator, (result.attesterAnchors.get(best.evaluator) ?? 0) + 1);
+        }
+        if (best.outcome === "DECLINED") {
+            result.declined += 1;
+            continue;
+        }
+        if (best.outcome === "NOT_FURNISHED")
+            result.notFurnished += 1;
+        if (UNSCORED_OUTCOMES.has(best.outcome))
+            continue;
+        const value = OUTCOME_VALUES[best.outcome];
+        // An outcome with no quality value — EXHAUSTED, TERMINATED,
+        // NOT_FURNISHED — is recorded and not scored (§4.4, SPEC §10.8a).
+        // Skipping it here is the whole mechanism: it never becomes an event, so
+        // it can never read as a failure however it got into the chain. This is
+        // what keeps a customer's lapsed licence off the provider's record.
+        if (value === undefined)
+            continue;
+        const isValue = best.source === "value";
+        result.events.push({ value, at: best.at, ...(isValue ? { value_judgment: true } : {}) });
+        if (isValue)
+            result.valueJudgments += 1;
+        result.scoredInteractions += 1;
+        if (best.outcome === "FAILED_SILENT")
+            result.silentFailures += 1;
+        if (!result.oldest || best.at < result.oldest)
+            result.oldest = best.at;
+        if (!result.newest || best.at > result.newest)
+            result.newest = best.at;
+    }
+    return result;
+}

package/dist/nda-claims.d.ts

@@ -0,0 +1,141 @@
+export declare const NDA_CLAIM_TAG = "fdbk-nda-claim-v1";
+/** The kinds of disclosure record a claim may cite (§4.8). */
+export declare const DISCLOSURE_KINDS: readonly ["rfp_release", "sow_task", "delivery"];
+export type DisclosureKind = (typeof DISCLOSURE_KINDS)[number];
+/** The claim body a claimant signs (§4.8). */
+export interface NdaClaim {
+    nda: {
+        id: string;
+        version: number;
+        digest: string;
+        ref?: string;
+    };
+    claimant: {
+        agent: string;
+        handle?: string;
+    };
+    respondent: {
+        agent: string;
+        handle?: string;
+    };
+    categories: string[];
+    disclosures: Array<{
+        kind: DisclosureKind;
+        digest: string;
+        at: string;
+    }>;
+    found: {
+        at: string;
+        material_digest: string;
+        note?: string;
+    };
+    breach_at: string | null;
+    at: string;
+}
+/** The bytes the claimant signs: the tag, a line feed, and the JCS of the claim. */
+export declare function claimSignedBytes(claim: NdaClaim): Uint8Array;
+/**
+ * The claim's digest, which answers, acknowledgments and withdrawals sign
+ * over: `sha256:` and the hex SHA-256 of the claim's JCS. §4.8 names a claim's
+ * digest without defining it; this is the definition this bureau uses, the
+ * one Agent NDA uses for an agreement.
+ */
+export declare function claimDigest(claim: NdaClaim): string;
+/** What is wrong with a claim's shape, or nothing. */
+export declare function claimProblems(x: unknown): string[];
+/**
+ * The one spelling a bureau keeps an agent key in, the nkey, whichever way a
+ * claim spells it, so one agent is never two subjects. Null for a string that
+ * is not an agent key.
+ */
+export declare function nkeyOf(agent: string): string | null;
+/** Whether `sigB64` (padded base64 Ed25519) is `key`'s signature over `bytes`; `key` an nkey or padded base64. */
+export declare function signedByKey(bytes: Uint8Array, key: string, sigB64: string): boolean;
+/** Check 1, in part: the claimant's key signed the claim (padded base64 Ed25519). Resolving the key's identity is the bureau's. */
+export declare function claimSignedBy(claim: NdaClaim, sigB64: string): boolean;
+/** The salted hash a ledger entry carries in place of an anchor (§4.1). */
+export declare function saltedAnchorHash(anchor: string, salt: string): string;
+/** Check 8, the window: from the first disclosure the claim cites until the filing period has passed after the duties ended. */
+export declare function withinClaimWindow(x: {
+    disclosedAt: readonly string[];
+    dutiesEndAt: string;
+    filedAt: string;
+    filingPeriodDays: number;
+}): boolean;
+/** The filing period this bureau publishes (§4.8, §10): the recommended 365 days; never under 90. */
+export declare const FILING_PERIOD_DAYS = 365;
+/** Check 9: claims that share this key are one claim, the later an amendment of the earlier. */
+export declare function amendmentKey(x: {
+    claimantAnchorHash: string;
+    ndaDigest: string;
+    respondent: string;
+}): string;
+export declare const NDA_ANSWER_TAG = "fdbk-nda-answer-v1";
+export declare const NDA_ACK_TAG = "fdbk-nda-ack-v1";
+export declare const NDA_WITHDRAW_TAG = "fdbk-nda-withdraw-v1";
+/** The respondent's answer: over the claim's digest and the answer text. */
+export interface NdaAnswer {
+    claim: string;
+    text: string;
+}
+/** The respondent's acknowledgment of the breach. A seat that names an organization carries the signer's mandate. */
+export interface NdaAck {
+    claim: string;
+    mandate?: string;
+}
+/** The claimant's withdrawal. */
+export interface NdaWithdrawal {
+    claim: string;
+}
+/** At most this many characters in an answer: it is stored and shown, never scored. */
+export declare const MAX_ANSWER_CHARS = 4000;
+/** The bytes an answer, acknowledgment or withdrawal is signed over: its tag, a line feed, and the JCS of the body. */
+export declare function ndaActBytes(tag: typeof NDA_ANSWER_TAG | typeof NDA_ACK_TAG | typeof NDA_WITHDRAW_TAG, body: NdaAnswer | NdaAck | NdaWithdrawal): Uint8Array;
+/** The four bases on which a claim is upheld, and only these. */
+export declare const UPHOLD_BASES: readonly ["acknowledged", "arbiter", "owners", "court"];
+export type UpholdBasis = (typeof UPHOLD_BASES)[number];
+/** What an `nda_resolved` entry records. `lapsed` is never recorded: it is how an open claim stands after the open period. */
+export declare const RESOLUTIONS: readonly ["upheld", "dismissed", "withdrawn", "set_aside"];
+export type Resolution = (typeof RESOLUTIONS)[number];
+/** How a claim stands. */
+export type ClaimState = "open" | "lapsed" | Resolution;
+/** The open period this bureau publishes (§4.8, §10): the recommended 365 days. */
+export declare const OPEN_PERIOD_DAYS = 365;
+/** The record period this bureau publishes: the recommended five years; never under 1095 days. */
+export declare const RECORD_PERIOD_DAYS = 1825;
+export declare const MIN_RECORD_PERIOD_DAYS = 1095;
+export declare const MIN_FILING_PERIOD_DAYS = 90;
+/**
+ * Why a resolution may not follow the state a claim is in, or null when it
+ * may. A claim leaves open (or lapsed, since a resolution after the open
+ * period still lands) only once: upheld, dismissed or withdrawn. Only an
+ * upheld breach can be set aside, and a set-aside claim stays set aside.
+ */
+export declare function resolutionRefusal(current: ClaimState, outcome: Resolution): string | null;
+/**
+ * How a claim stands on one day, from what its entries record: the latest
+ * resolution, or open until the open period has passed from filing and
+ * lapsed after; when it last moved (its filing, an answer or a resolution);
+ * and whether it is still within the record period from that latest entry,
+ * after which it leaves reports and stays in the excerpts.
+ */
+export declare function claimStanding(x: {
+    filedAt: string;
+    answeredAt: readonly string[];
+    resolutions: ReadonlyArray<{
+        outcome: Resolution;
+        basis?: string;
+        at: string;
+    }>;
+    nowMs: number;
+    openPeriodDays?: number;
+    recordPeriodDays?: number;
+}): {
+    state: ClaimState;
+    basis?: string;
+    resolvedAt?: string;
+    answers: number;
+    lastAnsweredAt?: string;
+    latestAt: string;
+    inRecord: boolean;
+};

package/dist/nda-claims.js

@@ -0,0 +1,168 @@
+/**
+ * Claims of breach of an Agent NDA (Agent Reputations §4.8), the parts that
+ * are pure: the claim document, its signed bytes and digest, its shape, the
+ * claimant's signature, the claim window (check 8), and the key that makes a
+ * later claim an amendment of an earlier one (check 9); the signed answers,
+ * acknowledgments and withdrawals; the resolutions a claim may take and in
+ * what order; and the open and record periods, which say how a claim stands
+ * on a given day.
+ *
+ * Checks 2, 3, 4, 6 and 7 read the agreement itself, which is the Agent NDA
+ * core's to read; the bureau's host asks it and hands the answers in. This
+ * core uses no other core.
+ */
+import { createHash } from "node:crypto";
+import { USER_KEY_RE, decodeSignature, nkeyFromRaw, rawFromBase64Key, rawUserKey, verifyRaw } from "@common-agent/crypto";
+import { jcs } from "./signing.js";
+export const NDA_CLAIM_TAG = "fdbk-nda-claim-v1";
+/** The kinds of disclosure record a claim may cite (§4.8). */
+export const DISCLOSURE_KINDS = ["rfp_release", "sow_task", "delivery"];
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const INSTANT = (s) => typeof s === "string" && Number.isFinite(Date.parse(s));
+/** The bytes the claimant signs: the tag, a line feed, and the JCS of the claim. */
+export function claimSignedBytes(claim) {
+    return new TextEncoder().encode(`${NDA_CLAIM_TAG}\n${jcs(claim)}`);
+}
+/**
+ * The claim's digest, which answers, acknowledgments and withdrawals sign
+ * over: `sha256:` and the hex SHA-256 of the claim's JCS. §4.8 names a claim's
+ * digest without defining it; this is the definition this bureau uses, the
+ * one Agent NDA uses for an agreement.
+ */
+export function claimDigest(claim) {
+    return `sha256:${createHash("sha256").update(jcs(claim)).digest("hex")}`;
+}
+/** What is wrong with a claim's shape, or nothing. */
+export function claimProblems(x) {
+    const out = [];
+    const c = x;
+    if (!c || typeof c !== "object")
+        return ["a claim is a JSON object"];
+    const nda = c.nda;
+    if (!nda || typeof nda.id !== "string" || !Number.isInteger(nda.version) || typeof nda.digest !== "string" || !DIGEST.test(nda.digest)) {
+        out.push("nda names the agreement: id, version, and the sha256: digest of the completed agreement");
+    }
+    for (const side of ["claimant", "respondent"]) {
+        const p = c[side];
+        if (!p || typeof p.agent !== "string" || !rawKey(p.agent))
+            out.push(`${side} names an agent key, as an nkey or padded base64`);
+        else if (p.handle !== undefined && (typeof p.handle !== "string" || p.handle.length > 320))
+            out.push(`${side}.handle is a handle`);
+    }
+    if (!Array.isArray(c.categories) || !c.categories.length || !c.categories.every((k) => typeof k === "string" && k))
+        out.push("categories names at least one category");
+    if (!Array.isArray(c.disclosures) || !c.disclosures.length)
+        out.push("disclosures cites at least one record");
+    else
+        for (const d of c.disclosures) {
+            if (!d || !DISCLOSURE_KINDS.includes(d.kind) || typeof d.digest !== "string" || !DIGEST.test(d.digest) || !INSTANT(d.at)) {
+                out.push(`each disclosure names its kind (${DISCLOSURE_KINDS.join(", ")}), the sha256: digest of its record, and the instant the record states`);
+                break;
+            }
+        }
+    const found = c.found;
+    if (!found || !INSTANT(found.at) || typeof found.material_digest !== "string" || !DIGEST.test(found.material_digest))
+        out.push("found says when, and the sha256: digest of what was found");
+    if (c.breach_at !== null && !INSTANT(c.breach_at))
+        out.push("breach_at is an instant, or null");
+    if (!INSTANT(c.at))
+        out.push("at is the instant of filing");
+    return out;
+}
+/** An agent key's raw bytes, from a user nkey whose checksum holds or from padded base64. Null when it is neither. */
+function rawKey(agent) {
+    return USER_KEY_RE.test(agent) ? rawUserKey(agent) : rawFromBase64Key(agent);
+}
+/**
+ * The one spelling a bureau keeps an agent key in, the nkey, whichever way a
+ * claim spells it, so one agent is never two subjects. Null for a string that
+ * is not an agent key.
+ */
+export function nkeyOf(agent) {
+    const raw = rawKey(agent);
+    return raw ? nkeyFromRaw(raw) : null;
+}
+/** Whether `sigB64` (padded base64 Ed25519) is `key`'s signature over `bytes`; `key` an nkey or padded base64. */
+export function signedByKey(bytes, key, sigB64) {
+    // One spelling per signature: base64 whose spare bits are set in its last
+    // character names the same bytes another way, and would let one act be
+    // recorded twice, so only the canonical spelling decodes.
+    return verifyRaw(rawKey(key), bytes, decodeSignature(sigB64, "base64"));
+}
+/** Check 1, in part: the claimant's key signed the claim (padded base64 Ed25519). Resolving the key's identity is the bureau's. */
+export function claimSignedBy(claim, sigB64) {
+    return signedByKey(claimSignedBytes(claim), claim.claimant.agent, sigB64);
+}
+/** The salted hash a ledger entry carries in place of an anchor (§4.1). */
+export function saltedAnchorHash(anchor, salt) {
+    return `sha256:${createHash("sha256").update(`${salt}\n${anchor.toLowerCase()}`).digest("hex")}`;
+}
+/** Check 8, the window: from the first disclosure the claim cites until the filing period has passed after the duties ended. */
+export function withinClaimWindow(x) {
+    const first = Math.min(...x.disclosedAt.map((a) => Date.parse(a)));
+    const filed = Date.parse(x.filedAt);
+    const closes = Date.parse(x.dutiesEndAt) + x.filingPeriodDays * 86_400_000;
+    return Number.isFinite(first) && Number.isFinite(filed) && filed >= first && filed <= closes;
+}
+/** The filing period this bureau publishes (§4.8, §10): the recommended 365 days; never under 90. */
+export const FILING_PERIOD_DAYS = 365;
+/** Check 9: claims that share this key are one claim, the later an amendment of the earlier. */
+export function amendmentKey(x) {
+    return `${x.claimantAnchorHash}|${x.ndaDigest}|${x.respondent}`;
+}
+// ── Answers, acknowledgments and withdrawals (§4.8) ─────────────────────────
+export const NDA_ANSWER_TAG = "fdbk-nda-answer-v1";
+export const NDA_ACK_TAG = "fdbk-nda-ack-v1";
+export const NDA_WITHDRAW_TAG = "fdbk-nda-withdraw-v1";
+/** At most this many characters in an answer: it is stored and shown, never scored. */
+export const MAX_ANSWER_CHARS = 4000;
+/** The bytes an answer, acknowledgment or withdrawal is signed over: its tag, a line feed, and the JCS of the body. */
+export function ndaActBytes(tag, body) {
+    return new TextEncoder().encode(`${tag}\n${jcs(body)}`);
+}
+// ── Resolutions and the periods (§4.8) ──────────────────────────────────────
+/** The four bases on which a claim is upheld, and only these. */
+export const UPHOLD_BASES = ["acknowledged", "arbiter", "owners", "court"];
+/** What an `nda_resolved` entry records. `lapsed` is never recorded: it is how an open claim stands after the open period. */
+export const RESOLUTIONS = ["upheld", "dismissed", "withdrawn", "set_aside"];
+/** The open period this bureau publishes (§4.8, §10): the recommended 365 days. */
+export const OPEN_PERIOD_DAYS = 365;
+/** The record period this bureau publishes: the recommended five years; never under 1095 days. */
+export const RECORD_PERIOD_DAYS = 1825;
+export const MIN_RECORD_PERIOD_DAYS = 1095;
+export const MIN_FILING_PERIOD_DAYS = 90;
+/**
+ * Why a resolution may not follow the state a claim is in, or null when it
+ * may. A claim leaves open (or lapsed, since a resolution after the open
+ * period still lands) only once: upheld, dismissed or withdrawn. Only an
+ * upheld breach can be set aside, and a set-aside claim stays set aside.
+ */
+export function resolutionRefusal(current, outcome) {
+    if (outcome === "set_aside")
+        return current === "upheld" ? null : `only an upheld breach is set aside, and this claim is ${current}`;
+    return current === "open" || current === "lapsed" ? null : `this claim is already ${current}`;
+}
+/**
+ * How a claim stands on one day, from what its entries record: the latest
+ * resolution, or open until the open period has passed from filing and
+ * lapsed after; when it last moved (its filing, an answer or a resolution);
+ * and whether it is still within the record period from that latest entry,
+ * after which it leaves reports and stays in the excerpts.
+ */
+export function claimStanding(x) {
+    const last = x.resolutions.at(-1);
+    const filed = Date.parse(x.filedAt);
+    const state = last ? last.outcome : x.nowMs > filed + (x.openPeriodDays ?? OPEN_PERIOD_DAYS) * 86_400_000 ? "lapsed" : "open";
+    const instants = [x.filedAt, ...x.answeredAt, ...x.resolutions.map((r) => r.at)];
+    const latestAt = instants.reduce((a, b) => (Date.parse(b) > Date.parse(a) ? b : a));
+    const lastAnsweredAt = x.answeredAt.length ? x.answeredAt.reduce((a, b) => (Date.parse(b) > Date.parse(a) ? b : a)) : undefined;
+    return {
+        state,
+        ...(last?.basis ? { basis: last.basis } : {}),
+        ...(last ? { resolvedAt: last.at } : {}),
+        answers: x.answeredAt.length,
+        ...(lastAnsweredAt ? { lastAnsweredAt } : {}),
+        latestAt,
+        inRecord: x.nowMs <= Date.parse(latestAt) + (x.recordPeriodDays ?? RECORD_PERIOD_DAYS) * 86_400_000,
+    };
+}

package/dist/nda-record.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The NDA record (Agent Reputations §4.9): the part of a report that shows
+ * the claims of breach about a subject, as dated findings and counts, and,
+ * for the readers rule 6 names, the claims it filed. Pure: the bureau reads
+ * each claim's standing from its ledger (nda-claims.ts says how a claim
+ * stands) and this decides what a reader may be shown of it.
+ *
+ * What a report never shows (rule 4) is never an input here: no agreement
+ * identifier or digest, no claimant identity, no note, no answer text, no
+ * record a claim cites. `agreement` and `respondent` below only group upheld
+ * claims, and nothing of either reaches the output.
+ */
+import { type ClaimState } from "./nda-claims.js";
+/** One claim, with its amendments, as the NDA record reads it. */
+export interface ClaimView {
+    state: ClaimState;
+    basis?: string;
+    resolvedAt?: string;
+    filedAt: string;
+    answers: number;
+    lastAnsweredAt?: string;
+    /** Inside the record period from its latest entry. Outside it, the claim leaves reports. */
+    inRecord: boolean;
+    categories: readonly string[];
+    direction: string;
+    claimantAnchorHash: string;
+    /** The salted hash of the claimant's operator, where the bureau knew it: claimants that share one count once. */
+    claimantOperatorHash?: string;
+    /** With `respondent`, groups several upheld claims on one agreement against one respondent into one entry (rule 1). Never shown. */
+    agreement: string;
+    respondent: string;
+}
+export interface NdaRecordUpheld {
+    upheld_at: string;
+    basis: string;
+    categories: string[];
+    direction: string;
+    claimant_anchor_hash: string;
+    answered: boolean;
+    answered_at?: string;
+}
+/** The claims a party filed in the record period, in each state (rule 6). */
+export interface NdaFiledCounts {
+    open: number;
+    upheld: number;
+    dismissed: number;
+    withdrawn: number;
+    set_aside: number;
+    lapsed: number;
+}
+export interface NdaRecord {
+    record_days: number;
+    upheld: NdaRecordUpheld[];
+    open: {
+        count: number;
+        claimants: number;
+        earliest: string | null;
+        answered: number;
+    };
+    closed: {
+        dismissed: number;
+        withdrawn: number;
+        set_aside: number;
+        lapsed: number;
+    };
+    /**
+     * Only in the party's own subject-scoped excerpt, and in a respondent's
+     * excerpt beside a claim the party filed (rule 6, Agent Reputations
+     * 0.10.0-draft). Never in a report another reader can fetch: there it
+     * would move at the moment the respondent's open count does, and tell a
+     * poller who filed against whom.
+     */
+    filed?: NdaFiledCounts;
+}
+/** The counts of a party's filings in the record period, in each state (rule 6). */
+export declare function filedCounts(filed: readonly ClaimView[]): NdaFiledCounts;
+/**
+ * The NDA record of a subject from the claims against it. Rejected claims
+ * are never inputs (they appear in the two parties' excerpts and nowhere
+ * else), and only claims inside the record period are shown. `filed`, the
+ * claims the subject filed, is given only for a reader rule 6 serves it to.
+ */
+export declare function ndaRecord(about: readonly ClaimView[], opts?: {
+    recordDays?: number;
+    filed?: readonly ClaimView[];
+}): NdaRecord;