@common-agent/reputations 0.0.0-stage → 0.1.0

package/dist/nda-record.js

@@ -0,0 +1,83 @@
+/**
+ * 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 { RECORD_PERIOD_DAYS } from "./nda-claims.js";
+const later = (a, b) => (!a ? b : !b ? a : Date.parse(b) > Date.parse(a) ? b : a);
+const count = (vs, s) => vs.filter((v) => v.state === s).length;
+/** How many distinct claimants: those that share an anchor or an operator are one (rule 2). */
+function distinctClaimants(views) {
+    const parent = views.map((_, i) => i);
+    const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+    const seen = new Map();
+    views.forEach((v, i) => {
+        for (const k of [`a:${v.claimantAnchorHash}`, ...(v.claimantOperatorHash ? [`o:${v.claimantOperatorHash}`] : [])]) {
+            const j = seen.get(k);
+            if (j === undefined)
+                seen.set(k, i);
+            else
+                parent[find(i)] = find(j);
+        }
+    });
+    return new Set(views.map((_, i) => find(i))).size;
+}
+/** The counts of a party's filings in the record period, in each state (rule 6). */
+export function filedCounts(filed) {
+    const shown = filed.filter((v) => v.inRecord);
+    return {
+        open: count(shown, "open"),
+        upheld: count(shown, "upheld"),
+        dismissed: count(shown, "dismissed"),
+        withdrawn: count(shown, "withdrawn"),
+        set_aside: count(shown, "set_aside"),
+        lapsed: count(shown, "lapsed"),
+    };
+}
+/**
+ * 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 function ndaRecord(about, opts = {}) {
+    const shown = about.filter((v) => v.inRecord);
+    // 1. Upheld breaches, one entry per agreement and respondent, with the latest date.
+    const byAgreement = new Map();
+    for (const v of shown.filter((x) => x.state === "upheld")) {
+        const k = `${v.agreement}|${v.respondent}`;
+        byAgreement.set(k, [...(byAgreement.get(k) ?? []), v]);
+    }
+    const upheld = [...byAgreement.values()].map((vs) => {
+        const latest = vs.reduce((a, b) => (Date.parse(b.resolvedAt ?? b.filedAt) > Date.parse(a.resolvedAt ?? a.filedAt) ? b : a));
+        const answeredAt = vs.reduce((a, v) => later(a, v.lastAnsweredAt), undefined);
+        return {
+            upheld_at: latest.resolvedAt ?? latest.filedAt,
+            basis: latest.basis ?? "",
+            categories: [...new Set(vs.flatMap((v) => v.categories))].sort(),
+            direction: latest.direction,
+            claimant_anchor_hash: latest.claimantAnchorHash,
+            answered: vs.some((v) => v.answers > 0),
+            ...(answeredAt ? { answered_at: answeredAt } : {}),
+        };
+    }).sort((a, b) => Date.parse(b.upheld_at) - Date.parse(a.upheld_at));
+    // 2. Open claims, as counts only.
+    const open = shown.filter((v) => v.state === "open");
+    const earliest = open.reduce((a, v) => (!a || Date.parse(v.filedAt) < Date.parse(a) ? v.filedAt : a), null);
+    return {
+        record_days: opts.recordDays ?? RECORD_PERIOD_DAYS,
+        upheld,
+        open: { count: open.length, claimants: distinctClaimants(open), earliest, answered: open.filter((v) => v.answers > 0).length },
+        // 3. Closed claims, in the states they ended in.
+        closed: { dismissed: count(shown, "dismissed"), withdrawn: count(shown, "withdrawn"), set_aside: count(shown, "set_aside"), lapsed: count(shown, "lapsed") },
+        // 6. Only for the readers rule 6 names.
+        ...(opts.filed ? { filed: filedCounts(opts.filed) } : {}),
+    };
+}

package/dist/pool.d.ts

@@ -0,0 +1,59 @@
+/** One ledger event, as §4 writes it. Only the members the pool reads are named. */
+export type LedgerEvent = {
+    seq: number;
+    action: "fact";
+    interaction_id: string;
+    ended_at: string;
+    derived_outcome: string;
+} | {
+    seq: number;
+    action: "attested";
+    interaction_id: string;
+    outcome: string;
+    excluded?: boolean;
+} | {
+    seq: number;
+    action: "probed";
+    interaction_id: string;
+    ended_at: string;
+    result: "PASS" | "FAIL";
+} | {
+    seq: number;
+    action: string;
+    interaction_id?: string;
+    [k: string]: unknown;
+};
+/** One scored event of the pool: its outcome, where it came from, its value and its weight. */
+export interface PoolEntry {
+    interaction_id: string;
+    outcome: string;
+    from: "fact" | "attested" | "probed";
+    v: number;
+    w: number;
+    value_judgment?: boolean;
+}
+/** The codes on which there was no work to judge (§6.2 rule 5): an attestation about one is rejected. */
+export declare const NO_WORK: Set<string>;
+/**
+ * The pool of §7.1 for one (subject, capability), from that pair's events.
+ *
+ * - A fact scores its derived outcome, unless an attestation overrides it.
+ * - An attestation is rejected without a fact for its interaction (§6.2
+ *   rule 1), on an interaction with no work (rule 5), or when it names
+ *   NDA_BREACH (rule 6). A later attestation for one interaction is an
+ *   amendment, and only the last one scores (rule 3). An excluded
+ *   attestation (§6.4) does not score, and the derived outcome stands.
+ * - A probe scores PASS as 1 and FAIL as 0.
+ * - Every other action (stops, claims of breach and their resolution, and the
+ *   rest) never enters a pool, and neither does an outcome §5 gives no value.
+ *
+ * Every event's age runs from the `ended_at` of the interaction it scores to
+ * the evaluation instant (§7.2): an attestation takes its interaction's age,
+ * however late it was signed. A value judgment's weight is multiplied by
+ * K_value (§7.6).
+ */
+export declare function poolFromEvents(events: readonly LedgerEvent[], opts: {
+    evaluatedAt: string | number;
+    halfLifeDays?: number;
+    kValue?: number;
+}): PoolEntry[];

package/dist/pool.js

@@ -0,0 +1,77 @@
+/**
+ * The quality pool of Agent Reputations §7.1, drawn from ledger events in the
+ * standard's shape (§4): which events score, with what value and weight.
+ *
+ * A ledger that still keeps the earlier shape draws its pool with ledger.ts,
+ * and moves to this one when it takes the standard's actions. The published vectors
+ * (fdbk-score-1) are written in this shape, and run against it.
+ */
+import { HALF_LIFE_DAYS, K_VALUE, OUTCOME_VALUES, VALUE_OUTCOMES } from "./score.js";
+/** The codes on which there was no work to judge (§6.2 rule 5): an attestation about one is rejected. */
+export const NO_WORK = new Set(["DECLINED", "REFUSED", "REFUSED_UNSTATED", "UNAVAILABLE", "STOPPED"]);
+const DAY_MS = 86_400_000;
+/**
+ * The pool of §7.1 for one (subject, capability), from that pair's events.
+ *
+ * - A fact scores its derived outcome, unless an attestation overrides it.
+ * - An attestation is rejected without a fact for its interaction (§6.2
+ *   rule 1), on an interaction with no work (rule 5), or when it names
+ *   NDA_BREACH (rule 6). A later attestation for one interaction is an
+ *   amendment, and only the last one scores (rule 3). An excluded
+ *   attestation (§6.4) does not score, and the derived outcome stands.
+ * - A probe scores PASS as 1 and FAIL as 0.
+ * - Every other action (stops, claims of breach and their resolution, and the
+ *   rest) never enters a pool, and neither does an outcome §5 gives no value.
+ *
+ * Every event's age runs from the `ended_at` of the interaction it scores to
+ * the evaluation instant (§7.2): an attestation takes its interaction's age,
+ * however late it was signed. A value judgment's weight is multiplied by
+ * K_value (§7.6).
+ */
+export function poolFromEvents(events, opts) {
+    const now = typeof opts.evaluatedAt === "number" ? opts.evaluatedAt : Date.parse(opts.evaluatedAt);
+    const halfLife = opts.halfLifeDays ?? HALF_LIFE_DAYS;
+    const kValue = opts.kValue ?? K_VALUE;
+    const sorted = [...events].sort((x, y) => x.seq - y.seq);
+    const facts = new Map();
+    for (const e of sorted)
+        if (e.action === "fact")
+            facts.set(e.interaction_id, e);
+    const attestations = new Map();
+    for (const e of sorted) {
+        if (e.action !== "attested")
+            continue;
+        const a = e;
+        const f = facts.get(a.interaction_id);
+        if (!f || NO_WORK.has(f.derived_outcome) || a.outcome === "NDA_BREACH" || a.excluded)
+            continue;
+        attestations.set(a.interaction_id, a);
+    }
+    const weight = (endedAt, code) => {
+        const age = (now - Date.parse(endedAt)) / DAY_MS;
+        return (VALUE_OUTCOMES.has(code) ? kValue : 1) * 2 ** (-age / halfLife);
+    };
+    const out = [];
+    for (const e of sorted) {
+        if (e.action === "fact") {
+            const f = e;
+            const a = attestations.get(f.interaction_id);
+            const outcome = a ? a.outcome : f.derived_outcome;
+            if (!(outcome in OUTCOME_VALUES))
+                continue;
+            out.push({
+                interaction_id: f.interaction_id,
+                outcome,
+                from: a ? "attested" : "fact",
+                v: OUTCOME_VALUES[outcome],
+                w: weight(f.ended_at, outcome),
+                ...(VALUE_OUTCOMES.has(outcome) ? { value_judgment: true } : {}),
+            });
+        }
+        else if (e.action === "probed") {
+            const p = e;
+            out.push({ interaction_id: p.interaction_id, outcome: p.result, from: "probed", v: p.result === "PASS" ? 1 : 0, w: weight(p.ended_at, p.result) });
+        }
+    }
+    return out;
+}

package/dist/ports.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The ports Agent Reputations asks the platform for. None: the bureau keeps
+ * its own ledger and hears about engagements only through the evidence it
+ * records, never through a call from another standard's code.
+ */
+export {};

package/dist/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/report.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The bureau's report (Agent Reputations §8), as data: the signing tags, the
+ * report's shape, and how a capability's block and the whole report are put
+ * together from a pool and a score. Signing the report is the bureau's
+ * (signing.ts holds the bytes), because the key lives with it.
+ *
+ * The shape is the earlier bureau's own `fdbk-report-v1`, from before 0.6.0.
+ */
+import type { NdaRecord } from "./nda-record.js";
+import { type QualityScore } from "./score.js";
+import type { EnrollmentInfo, PoolResult } from "./ledger.js";
+/** The prefix a report is signed under, over its canonical JSON. */
+export declare const REPORT_SIG_PREFIX = "fdbk-report-v1\n";
+/** The colon-joined signed forms of the enrollment acts (§3). */
+export declare const ENROLL_TAG = "fdbk-enroll-v1";
+export declare const WITHDRAW_TAG = "fdbk-withdraw-v1";
+/** §6.6's signed form, colon-joined like the enrollment acts:
+ *  fdbk-value-v1:<interaction_id>:<subject>:<capability>:<outcome>:<amount>:<currency>:<units>:<at> */
+export declare const VALUE_TAG = "fdbk-value-v1";
+/** What an agent signs to enroll at a bureau or to withdraw from it (§3.2):
+ *  the tag, the subject's key, the bureau's URL and the instant, joined by
+ *  colons. The bureau verifies these bytes and the adapter signs them, both
+ *  from here. */
+export declare function enrollmentActText(tag: typeof ENROLL_TAG | typeof WITHDRAW_TAG, subject: string, bureauUrl: string, at: string): string;
+/** A value judgment's signed form (§6.6), the bytes the client signs and the
+ *  bureau verifies. A judgment MAY carry no amount or no units, and an
+ *  absent number signs as an empty position, never as zero. */
+export declare function valueJudgmentText(j: {
+    interactionId: string;
+    seller: string;
+    offering: string;
+    outcome: string;
+    amount: number | null;
+    currency: string;
+    units: number | null;
+    at: string;
+}): string;
+/** How long a report stays good after it is issued. */
+export declare const REPORT_TTL_MS: number;
+export type CapabilityState = "UNENROLLED" | "WITHDRAWN" | "UNPROVEN" | "RATED";
+export interface CapabilityBlock {
+    capability: string;
+    enrollment: string;
+    quality: {
+        lcb?: number;
+        mean?: number;
+        n_eff: number;
+    };
+    candor: {
+        decline_rate: number;
+        silent_failure_rate: number;
+    };
+    evidence: {
+        scored_interactions: number;
+        declined: number;
+        attester_anchors: number;
+        top_anchor_share: number;
+        value_judgments?: number;
+        value_judgment_share?: number;
+        client_not_furnished?: number;
+        oldest?: string;
+        newest?: string;
+    };
+}
+/** What an UNENROLLED subject's capability shows: only that interactions were observed (§8.3). */
+export interface FactsBlock {
+    capability: string;
+    enrollment: "UNENROLLED";
+    facts: {
+        interactions_recorded: number;
+    };
+}
+export interface Report {
+    subject: string;
+    enrollment: string;
+    enrolled_at?: string;
+    withdrew_at?: string;
+    withdrawal_effective_at?: string;
+    capabilities: Array<CapabilityBlock | FactsBlock>;
+    half_life_days: number;
+    unproven_threshold: number;
+    k_value: number;
+    formula_version: string;
+    bureau: string;
+    issued_at: string;
+    expires_at: string;
+    nda?: NdaRecord;
+}
+/** A report in its envelope (§8.1): the bureau's key and signature beside it, and the key's id
+ *  in the 0.6.0 envelope; the envelope from before 0.6.0 carries no id. */
+export interface SignedReport {
+    report: Report;
+    bureau_key: string;
+    bureau_kid?: string;
+    bureau_sig: string;
+}
+/** Per-capability enrollment state (§3.1): UNPROVEN vs RATED is a property
+ *  of the evidence for the capability queried, not of the subject. */
+export declare function capabilityState(info: EnrollmentInfo, nEff: number): CapabilityState;
+/** One capability's block of an enrolled subject's report, from its pool and its score. */
+export declare function capabilityBlock(capability: string, info: EnrollmentInfo, pool: PoolResult, q: QualityScore): CapabilityBlock;
+/** One capability of an UNENROLLED subject: quality is opt-in (§3.1), so only
+ *  the fact that interactions were observed is served, clearly labeled (§8.3). */
+export declare function factsBlock(capability: string, pool: PoolResult): FactsBlock;
+/** The answer to a resolution query (§8), unsigned. */
+export declare function assembleReport(x: {
+    subject: string;
+    info: EnrollmentInfo;
+    capabilities: Array<CapabilityBlock | FactsBlock>;
+    bureau: string;
+    nowMs: number;
+    /** The NDA record (§4.9), served for any subject, enrolled or not, beside the scores and never in them. */
+    nda?: NdaRecord;
+}): Report;
+/**
+ * A report as 0.6.0 writes it (§8.1): one subject and one capability, the
+ * enrollment state for that capability at the top, and the score, candor and
+ * evidence blocks beside it. A facts-only report about an UNENROLLED subject
+ * (§8.3) carries no quality or candor block.
+ */
+export interface CapabilityReport {
+    subject: string;
+    capability: string;
+    enrollment: CapabilityState;
+    enrolled_at?: string;
+    withdrew_at?: string;
+    withdrawal_effective_at?: string;
+    quality?: {
+        lcb?: number;
+        mean?: number;
+        n_eff: number;
+    };
+    candor?: {
+        decline_rate: number;
+        silent_failure_rate: number;
+    };
+    /** This bureau's one fact for a facts-only report: how many interactions it recorded. */
+    facts?: {
+        interactions_recorded: number;
+    };
+    evidence?: {
+        half_life_days: number;
+        oldest?: string;
+        newest?: string;
+        attester_anchors: number;
+        top_anchor_share: number;
+        value_judgments?: number;
+        value_judgment_share?: number;
+        client_not_furnished?: number;
+        /** §7.5: whether a portfolio prior is in effect. This bureau applies none yet. */
+        portfolio_prior: boolean;
+    };
+    formula_version: string;
+    k_value: number;
+    unproven_threshold: number;
+    /** The subject's NDA record (§4.9), the same in every capability's report, and never in its figures. */
+    nda?: NdaRecord;
+    bureau: string;
+    issued_at: string;
+    expires_at: string;
+}
+/**
+ * The answer to a resolution query about one capability (§8.1), unsigned:
+ * the same figures `capabilityBlock` gives, laid out as the standard lays a
+ * report out, with the mandatory context of §8.2 beside every score.
+ */
+export declare function assembleCapabilityReport(x: {
+    subject: string;
+    capability: string;
+    info: EnrollmentInfo;
+    pool: PoolResult;
+    score: QualityScore;
+    bureau: string;
+    nowMs: number;
+    nda?: NdaRecord;
+}): CapabilityReport;

package/dist/report.js

@@ -0,0 +1,147 @@
+import { FORMULA_VERSION, HALF_LIFE_DAYS, K_VALUE, UNPROVEN_THRESHOLD } from "./score.js";
+/** The prefix a report is signed under, over its canonical JSON. */
+export const REPORT_SIG_PREFIX = "fdbk-report-v1\n";
+/** The colon-joined signed forms of the enrollment acts (§3). */
+export const ENROLL_TAG = "fdbk-enroll-v1";
+export const WITHDRAW_TAG = "fdbk-withdraw-v1";
+/** §6.6's signed form, colon-joined like the enrollment acts:
+ *  fdbk-value-v1:<interaction_id>:<subject>:<capability>:<outcome>:<amount>:<currency>:<units>:<at> */
+export const VALUE_TAG = "fdbk-value-v1";
+/** What an agent signs to enroll at a bureau or to withdraw from it (§3.2):
+ *  the tag, the subject's key, the bureau's URL and the instant, joined by
+ *  colons. The bureau verifies these bytes and the adapter signs them, both
+ *  from here. */
+export function enrollmentActText(tag, subject, bureauUrl, at) {
+    return `${tag}:${subject}:${bureauUrl}:${at}`;
+}
+/** A value judgment's signed form (§6.6), the bytes the client signs and the
+ *  bureau verifies. A judgment MAY carry no amount or no units, and an
+ *  absent number signs as an empty position, never as zero. */
+export function valueJudgmentText(j) {
+    return [
+        VALUE_TAG, j.interactionId, j.seller, j.offering, j.outcome,
+        j.amount === null ? "" : String(j.amount),
+        j.currency,
+        j.units === null ? "" : String(j.units),
+        j.at,
+    ].join(":");
+}
+/** How long a report stays good after it is issued. */
+export const REPORT_TTL_MS = 60 * 60 * 1000;
+const round = (x) => Math.round(x * 1000) / 1000;
+/** Per-capability enrollment state (§3.1): UNPROVEN vs RATED is a property
+ *  of the evidence for the capability queried, not of the subject. */
+export function capabilityState(info, nEff) {
+    if (info.state === "UNENROLLED")
+        return "UNENROLLED";
+    if (info.state === "WITHDRAWN")
+        return "WITHDRAWN";
+    return nEff < UNPROVEN_THRESHOLD ? "UNPROVEN" : "RATED";
+}
+/** One capability's block of an enrolled subject's report, from its pool and its score. */
+export function capabilityBlock(capability, info, pool, q) {
+    const state = capabilityState(info, q.n_eff);
+    const anchors = pool.attesterAnchors;
+    const totalAttested = [...anchors.values()].reduce((a, b) => a + b, 0);
+    const top = anchors.size ? Math.max(...anchors.values()) : 0;
+    return {
+        capability,
+        enrollment: state,
+        // The score, only where the evidence has earned the right to be one
+        // (§7.4): an UNPROVEN capability serves its sample size, not a number
+        // dressed as seasoned.
+        ...(state === "RATED" || state === "WITHDRAWN"
+            ? { quality: { lcb: round(q.lcb), mean: round(q.mean), n_eff: round(q.n_eff) } }
+            : { quality: { n_eff: round(q.n_eff) } }),
+        candor: {
+            decline_rate: round(pool.declined / Math.max(1, pool.declined + pool.scoredInteractions)),
+            silent_failure_rate: round(pool.silentFailures / Math.max(1, pool.scoredInteractions)),
+        },
+        evidence: {
+            scored_interactions: pool.scoredInteractions,
+            declined: pool.declined,
+            attester_anchors: anchors.size,
+            top_anchor_share: round(totalAttested ? top / totalAttested : 0),
+            // §8.2: REQUIRED whenever the pool contains a value judgment, and
+            // absent otherwise so its presence means something. It is a share of
+            // the pool's WEIGHT after §7.6, not a count of events.
+            ...(pool.valueJudgments
+                ? { value_judgments: pool.valueJudgments, value_judgment_share: round(q.value_judgment_share) }
+                : {}),
+            // SPEC §10.8a: stops the platform attributed to the caller, because it
+            // checked the named need against what this agent declared. Reported so
+            // that "not scored" does not quietly become "never happened" — a
+            // reader can see the ending and see that it cost the provider nothing.
+            ...(pool.notFurnished ? { client_not_furnished: pool.notFurnished } : {}),
+            ...(pool.oldest ? { oldest: pool.oldest } : {}),
+            ...(pool.newest ? { newest: pool.newest } : {}),
+        },
+    };
+}
+/** One capability of an UNENROLLED subject: quality is opt-in (§3.1), so only
+ *  the fact that interactions were observed is served, clearly labeled (§8.3). */
+export function factsBlock(capability, pool) {
+    return { capability, enrollment: "UNENROLLED", facts: { interactions_recorded: pool.scoredInteractions + pool.declined } };
+}
+/** The answer to a resolution query (§8), unsigned. */
+export function assembleReport(x) {
+    const { info } = x;
+    return {
+        subject: x.subject,
+        enrollment: info.state === "ENROLLED" ? "ENROLLED" : info.state,
+        ...(info.enrolled_at ? { enrolled_at: info.enrolled_at } : {}),
+        ...(info.withdrew_at ? { withdrew_at: info.withdrew_at, withdrawal_effective_at: info.withdrawal_effective_at } : {}),
+        capabilities: x.capabilities,
+        half_life_days: HALF_LIFE_DAYS,
+        unproven_threshold: UNPROVEN_THRESHOLD,
+        // §7.6/§10.3: a bureau MAY choose K_value but MUST publish the value it
+        // uses. Published here, inside the signed bytes, so a consumer
+        // recomputing §7 knows the multiplier that produced the number.
+        k_value: K_VALUE,
+        formula_version: FORMULA_VERSION,
+        ...(x.nda ? { nda: x.nda } : {}),
+        bureau: x.bureau,
+        issued_at: new Date(x.nowMs).toISOString(),
+        expires_at: new Date(x.nowMs + REPORT_TTL_MS).toISOString(),
+    };
+}
+/**
+ * The answer to a resolution query about one capability (§8.1), unsigned:
+ * the same figures `capabilityBlock` gives, laid out as the standard lays a
+ * report out, with the mandatory context of §8.2 beside every score.
+ */
+export function assembleCapabilityReport(x) {
+    const { info, pool } = x;
+    const head = {
+        subject: x.subject,
+        capability: x.capability,
+        ...(info.enrolled_at ? { enrolled_at: info.enrolled_at } : {}),
+        ...(info.withdrew_at ? { withdrew_at: info.withdrew_at, withdrawal_effective_at: info.withdrawal_effective_at } : {}),
+    };
+    const tail = {
+        formula_version: FORMULA_VERSION,
+        k_value: K_VALUE,
+        unproven_threshold: UNPROVEN_THRESHOLD,
+        ...(x.nda ? { nda: x.nda } : {}),
+        bureau: x.bureau,
+        issued_at: new Date(x.nowMs).toISOString(),
+        expires_at: new Date(x.nowMs + REPORT_TTL_MS).toISOString(),
+    };
+    if (info.state === "UNENROLLED") {
+        // §8.3: quality is opt-in; an unenrolled subject's report states facts only.
+        return { ...head, enrollment: "UNENROLLED", facts: factsBlock(x.capability, pool).facts, ...tail };
+    }
+    const block = capabilityBlock(x.capability, info, pool, x.score);
+    return {
+        ...head,
+        enrollment: block.enrollment,
+        quality: block.quality,
+        candor: block.candor,
+        evidence: {
+            half_life_days: HALF_LIFE_DAYS,
+            ...block.evidence,
+            portfolio_prior: false,
+        },
+        ...tail,
+    };
+}

package/dist/score.d.ts

@@ -0,0 +1,110 @@
+/**
+ * fdbk-score-1 — the published scoring formula of the Agent Reputations
+ * specification (§5, §7), the arithmetic of the Agent Reputations core. Pure arithmetic over an event pool: no I/O, no
+ * randomness, no iteration. Anyone holding the events computes the same
+ * numbers, which is the whole point — a score that cannot be recomputed is
+ * an opinion with a haircut.
+ *
+ * The constants are formula constants, not tunables: changing any of them is
+ * a new formula version (fdbk-score-2), never a quiet edit to this one.
+ */
+/** Quality value per outcome code (spec §5). DECLINED and UNREACHABLE carry
+ *  no quality value: declining feeds candor, unreachability feeds facts.
+ *
+ *  VALUE_OK and VALUE_POOR answer a DIFFERENT question — was the spend worth
+ *  it, on engagements where nothing was named that either party could accept
+ *  (§6.6) — and enter the pool at the reduced weight of §7.6. They carry the
+ *  same 1.0/0.0 values as acceptance and rejection; what separates them is
+ *  the weight, not the value. */
+export declare const OUTCOME_VALUES: Record<string, number>;
+/** The two value-judgment codes (§6.6), by name. A value judgment MUST NOT be
+ *  recorded through the acceptance path, and an acceptance MUST NOT be
+ *  recorded through this one; the doors check against this set. */
+export declare const VALUE_OUTCOMES: Set<string>;
+/** Outcomes excluded from the quality pool but still counted elsewhere. */
+export declare const UNSCORED_OUTCOMES: Set<string>;
+export declare const FORMULA_VERSION = "fdbk-score-1";
+export declare const HALF_LIFE_DAYS = 60;
+/** Below this effective sample size a capability is UNPROVEN (§7.4). */
+export declare const UNPROVEN_THRESHOLD = 20;
+/**
+ * §7.6: a value judgment's decay weight is multiplied by this.
+ *
+ * A formula constant of fdbk-score-1, alongside H and the UNPROVEN threshold,
+ * not a tunable. With no artifact to point at, a judgment about whether money
+ * was well spent is more subjective and more disputable than a judgment about
+ * work that was named and delivered, and the honest way to price that is one
+ * number a reader can see and argue with. The spec forbids setting it above
+ * 1.0 and advises against above 0.5; 0.5 is the published default and what
+ * this bureau uses.
+ */
+export declare const K_VALUE = 0.5;
+export interface ScoredEvent {
+    /** Quality value from OUTCOME_VALUES. */
+    value: number;
+    /** ISO timestamp of the interaction's end (decay reference). */
+    at: string;
+    /** True for a §6.6 value judgment: the decay weight is multiplied by
+     *  K_VALUE (§7.6). Absent means an ordinary event at full weight. */
+    value_judgment?: boolean;
+}
+export interface QualityScore {
+    a: number;
+    b: number;
+    mean: number;
+    sd: number;
+    lcb: number;
+    n_eff: number;
+    unproven: boolean;
+    /**
+     * §8.2: the share of the pool's weight, AFTER §7.6, that came from value
+     * judgments. Required in every report whose pool contains one — a reader
+     * who cannot separate acceptances of named work from judgments about
+     * whether a spend was worth it is reading two measurements as one number.
+     */
+    value_judgment_share: number;
+}
+/** Exponential decay weight (§7.2): w = 2^(-age_days / H). Future-dated
+ *  events get weight 1 rather than >1 — clock skew is not extra credit. */
+export declare function decayWeight(atIso: string, nowMs: number, halfLifeDays?: number): number;
+/** The weight one event contributes: the §7.2 decay, times §7.6's K_value
+ *  when the event is a value judgment. Because the multiplier lands on w_i it
+ *  reduces the event's effect on mean, sd, lcb and n_eff together — which is
+ *  the correct reading of thinner evidence, and why §7.6 needs no other
+ *  change to §7.3. */
+export declare function eventWeight(e: ScoredEvent, nowMs: number, halfLifeDays?: number): number;
+/**
+ * The prior of §7.3 and §7.5: the pair that takes the place of the two 1s in
+ * a and b. The uniform prior is { a0: 1, b0: 1 }. A portfolio prior may be
+ * stronger, but never by more than the equivalent of 10 effective events.
+ */
+export interface Prior {
+    a0: number;
+    b0: number;
+}
+export declare const UNIFORM_PRIOR: Prior;
+/** §7.5: a portfolio prior's weight, a0 + b0 − 2, MUST NOT exceed this. A formula constant. */
+export declare const MAX_PRIOR_WEIGHT = 10;
+/** Throws when a prior is not one §7.5 allows: both terms positive and finite, its weight from 0 to 10. */
+export declare function checkPrior(prior: Prior): void;
+/**
+ * A portfolio prior from the anchor's other agents RATED for the same
+ * capability (§7.5), as their mean quality spread over `weight` effective
+ * events: a0 = 1 + weight · m, b0 = 1 + weight · (1 − m). The uniform prior
+ * when there are none. The caller chooses which agents count; §7.5 says only
+ * the anchor's own members RATED for this capability may.
+ */
+export declare function portfolioPrior(ratedMeans: readonly number[], weight?: number): Prior;
+/**
+ * The Beta posterior summary of §7.3 over weighted values, with the prior of
+ * §7.5. n_eff counts direct evidence only: a + b less the two prior terms, so
+ * a portfolio prior moves the mean and the bound and never makes a capability
+ * RATED (§7.4).
+ */
+export declare function scoreWeighted(entries: ReadonlyArray<{
+    v: number;
+    w: number;
+    value_judgment?: boolean;
+}>, prior?: Prior): QualityScore;
+/** The Beta posterior summary of §7.3, exactly as published, over scored events, with an optional prior (§7.5). */
+export declare function scorePool(events: ScoredEvent[], nowMs: number, prior?: Prior): QualityScore;