attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/error/authzError.js

@@ -0,0 +1,11 @@
+/**
+ * Authorization errors: a denied capability, or a grant that would amplify
+ * rights or lifetime. They share the `AmpError` shape so the kernel can turn
+ * any of them into a blocked receipt.
+ */
+import { AmpError } from "./ampError.js";
+export class AuthzError extends AmpError {
+    constructor(code, problems) {
+        super("AuthzError", code, problems);
+    }
+}

package/lib/error/boundaryRejection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Boundary rejections: the only error a constructor in `src/boundary` may throw.
+ *
+ * The point of the boundary is that an invalid object is never returned. A
+ * constructor therefore fails as a whole, carrying every problem it found, so
+ * a caller can log one machine-readable reason and one audit receipt instead of
+ * a partially valid object that a later checker may or may not notice.
+ */
+import { AmpError } from "./ampError.js";
+/**
+ * Stable machine-readable reasons; callers may switch on these.
+ */
+export type BoundaryCode = "invalid_frame" | "invalid_tool_args" | "unresolvable_ref" | "duplicate_ref" | "invalid_id";
+export declare class BoundaryRejection extends AmpError<BoundaryCode> {
+    constructor(code: BoundaryCode, problems: readonly string[]);
+}

package/lib/error/boundaryRejection.js

@@ -0,0 +1,14 @@
+/**
+ * Boundary rejections: the only error a constructor in `src/boundary` may throw.
+ *
+ * The point of the boundary is that an invalid object is never returned. A
+ * constructor therefore fails as a whole, carrying every problem it found, so
+ * a caller can log one machine-readable reason and one audit receipt instead of
+ * a partially valid object that a later checker may or may not notice.
+ */
+import { AmpError } from "./ampError.js";
+export class BoundaryRejection extends AmpError {
+    constructor(code, problems) {
+        super("BoundaryRejection", code, problems);
+    }
+}

package/lib/error/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./agentError.js";
+export * from "./ampError.js";
+export * from "./authzError.js";
+export * from "./boundaryRejection.js";
+export * from "./kernelError.js";
+export * from "./mailboxError.js";
+export * from "./windowError.js";

package/lib/error/index.js

@@ -0,0 +1,7 @@
+export * from "./agentError.js";
+export * from "./ampError.js";
+export * from "./authzError.js";
+export * from "./boundaryRejection.js";
+export * from "./kernelError.js";
+export * from "./mailboxError.js";
+export * from "./windowError.js";

package/lib/error/kernelError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Kernel errors: illegal process/thread transitions and exhausted resources.
+ *
+ * They share the `AmpError` shape (`code` + every problem found) so a caller can
+ * turn any of them into a blocked receipt without special-casing.
+ */
+import { AmpError } from "./ampError.js";
+export type KernelCode = "invalid_process" | "invalid_thread" | "invalid_transition" | "unknown_process" | "unknown_thread" | "budget_exceeded" | "missing_receipt" | "agent_busy" | "claim_failed" | "lease_lost" | "unknown_object" | "duplicate_task";
+export declare class KernelError extends AmpError<KernelCode> {
+    constructor(code: KernelCode, problems: readonly string[]);
+}

package/lib/error/kernelError.js

@@ -0,0 +1,12 @@
+/**
+ * Kernel errors: illegal process/thread transitions and exhausted resources.
+ *
+ * They share the `AmpError` shape (`code` + every problem found) so a caller can
+ * turn any of them into a blocked receipt without special-casing.
+ */
+import { AmpError } from "./ampError.js";
+export class KernelError extends AmpError {
+    constructor(code, problems) {
+        super("KernelError", code, problems);
+    }
+}

package/lib/error/mailboxError.d.ts

@@ -0,0 +1,5 @@
+import { AmpError } from "./ampError.js";
+export type MailboxCode = "mailbox_full" | "unknown_message" | "unknown_recipient";
+export declare class MailboxError extends AmpError<MailboxCode> {
+    constructor(code: MailboxCode, problems: readonly string[]);
+}

package/lib/error/mailboxError.js

@@ -0,0 +1,6 @@
+import { AmpError } from "./ampError.js";
+export class MailboxError extends AmpError {
+    constructor(code, problems) {
+        super("MailboxError", code, problems);
+    }
+}

package/lib/error/windowError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Window errors: the context window cannot hold a page even after eviction.
+ */
+import { AmpError } from "./ampError.js";
+export type WindowCode = "window_full" | "unknown_page";
+export declare class WindowError extends AmpError<WindowCode> {
+    constructor(code: WindowCode, problems: readonly string[]);
+}

package/lib/error/windowError.js

@@ -0,0 +1,9 @@
+/**
+ * Window errors: the context window cannot hold a page even after eviction.
+ */
+import { AmpError } from "./ampError.js";
+export class WindowError extends AmpError {
+    constructor(code, problems) {
+        super("WindowError", code, problems);
+    }
+}

package/lib/evaluation/agreement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Inter-annotator agreement metrics. These are for labeled evaluation, not for
+ * model confidence; keep them separate from ECE/Brier.
+ */
+/**
+ * Two label sequences over the same items.
+ */
+type LabelList = readonly string[];
+/**
+ * A pairwise agreement statistic over two label sequences.
+ */
+type AgreementFn = (left: LabelList, right: LabelList) => number;
+export declare const agreementRate: AgreementFn;
+/**
+ * Cohen's kappa for two raters over the same categorical labels.
+ */
+export declare const cohenKappa: AgreementFn;
+/**
+ * Fleiss' kappa for n items x m raters.
+ */
+export declare const fleissKappa: (matrix: readonly LabelList[]) => number;
+export {};

package/lib/evaluation/agreement.js

@@ -0,0 +1,82 @@
+/**
+ * Inter-annotator agreement metrics. These are for labeled evaluation, not for
+ * model confidence; keep them separate from ECE/Brier.
+ */
+export const agreementRate = (left, right) => {
+    if (left.length !== right.length) {
+        throw new Error("label arrays must have equal length");
+    }
+    if (left.length === 0) {
+        return 1;
+    }
+    let matches = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] === right[index]) {
+            matches += 1;
+        }
+    }
+    return matches / left.length;
+};
+/**
+ * Cohen's kappa for two raters over the same categorical labels.
+ */
+export const cohenKappa = (left, right) => {
+    if (left.length !== right.length) {
+        throw new Error("label arrays must have equal length");
+    }
+    if (left.length === 0) {
+        return 1;
+    }
+    const observed = agreementRate(left, right);
+    const categories = [...new Set([...left, ...right])];
+    let expected = 0;
+    for (let categoryIndex = 0; categoryIndex < categories.length; categoryIndex += 1) {
+        const category = categories[categoryIndex];
+        const leftRate = left.filter((label) => label === category).length / left.length;
+        const rightRate = right.filter((label) => label === category).length / right.length;
+        expected += leftRate * rightRate;
+    }
+    if (expected === 1) {
+        return observed === 1 ? 1 : 0;
+    }
+    return (observed - expected) / (1 - expected);
+};
+/**
+ * Fleiss' kappa for n items x m raters.
+ */
+export const fleissKappa = (matrix) => {
+    if (matrix.length === 0) {
+        return 1;
+    }
+    const raters = matrix[0].length;
+    if (raters === 0 || matrix.some((row) => row.length !== raters)) {
+        throw new Error("ragged rating matrix");
+    }
+    const categories = [...new Set(matrix.flat())];
+    const total = matrix.length * raters;
+    const counts = new Map();
+    for (let rowIndex = 0; rowIndex < matrix.length; rowIndex += 1) {
+        const row = matrix[rowIndex];
+        for (let labelIndex = 0; labelIndex < row.length; labelIndex += 1) {
+            const label = row[labelIndex];
+            counts.set(label, (counts.get(label) ?? 0) + 1);
+        }
+    }
+    const observed = matrix.reduce((sum, row) => {
+        let agreements = 0;
+        for (let categoryIndex = 0; categoryIndex < categories.length; categoryIndex += 1) {
+            const category = categories[categoryIndex];
+            const count = row.filter((label) => label === category).length;
+            agreements += count * (count - 1);
+        }
+        return sum + agreements / (raters * (raters - 1));
+    }, 0) / matrix.length;
+    const expected = categories.reduce((sum, category) => {
+        const rate = (counts.get(category) ?? 0) / total;
+        return sum + rate * rate;
+    }, 0);
+    if (expected === 1) {
+        return observed === 1 ? 1 : 0;
+    }
+    return (observed - expected) / (1 - expected);
+};

package/lib/evaluation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./agreement.js";
+export * from "./labels.js";

package/lib/evaluation/index.js

@@ -0,0 +1,2 @@
+export * from "./agreement.js";
+export * from "./labels.js";

package/lib/evaluation/labels.d.ts

@@ -0,0 +1,56 @@
+export interface Annotation {
+    caseId: string;
+    annotator: string;
+    label: string;
+    note?: string;
+}
+export interface LabelCandidate {
+    caseId: string;
+    predicted: number;
+    uncertainty?: number;
+}
+/**
+ * CSV header: caseId,annotator,label[,note]. Handles quoted newlines.
+ */
+export declare const importAnnotationsCsv: (text: string) => Annotation[];
+/**
+ * Active learning: prefer predicted probability near 0.5 and high uncertainty.
+ */
+export declare const selectLabelCandidates: (candidates: readonly LabelCandidate[], budget: number) => LabelCandidate[];
+/**
+ * Fill only unresolved ties; resolved cases keep their majority label.
+ */
+export declare const resolveUnresolved: (audit: LabelAudit, resolutions: Record<string, string>) => Record<string, string | null>;
+/**
+ * Reject an annotation batch before it is used for calibration.
+ */
+export declare const requireLabelCoverage: (audit: LabelAudit, options?: {
+    minCoverage?: number;
+    maxDuplicates?: number;
+}) => void;
+export interface LabelAudit {
+    cases: number;
+    annotations: number;
+    covered: number;
+    coverage: number;
+    missing: string[];
+    duplicates: Array<{
+        caseId: string;
+        annotator: string;
+        count: number;
+    }>;
+    disagreements: Array<{
+        caseId: string;
+        labels: Record<string, number>;
+    }>;
+    annotators: string[];
+    pairwiseKappa: Array<{
+        left: string;
+        right: string;
+        kappa: number;
+        common: number;
+    }>;
+    adjudicated: Record<string, string | null>;
+}
+export declare const importAnnotations: (input: unknown) => Annotation[];
+export declare const auditLabels: (caseIds: readonly string[], annotations: readonly Annotation[]) => LabelAudit;

package/lib/evaluation/labels.js

@@ -0,0 +1,206 @@
+/**
+ * Annotation import and adjudication.
+ *
+ * This is deliberately file-oriented: human labels may come from a spreadsheet,
+ * a CSV export or a small JSONL file. The audit reports coverage, duplicates,
+ * disagreements and pairwise Cohen's kappa before any label is trusted.
+ */
+import { cohenKappa } from "./agreement.js";
+const splitCsvRecords = (text) => {
+    const records = [];
+    let record = [];
+    let cell = "";
+    let quoted = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"') {
+            if (quoted && text[index + 1] === '"') {
+                cell += '"';
+                index += 1;
+            }
+            else {
+                quoted = !quoted;
+            }
+        }
+        else if (char === "," && !quoted) {
+            record.push(cell);
+            cell = "";
+        }
+        else if ((char === "\n" || char === "\r") && !quoted) {
+            if (char === "\r" && text[index + 1] === "\n") {
+                index += 1;
+            }
+            record.push(cell);
+            if (record.some((entry) => entry.trim().length > 0)) {
+                records.push(record);
+            }
+            record = [];
+            cell = "";
+        }
+        else {
+            cell += char;
+        }
+    }
+    if (cell.length > 0 || record.length > 0) {
+        record.push(cell);
+        if (record.some((entry) => entry.trim().length > 0)) {
+            records.push(record);
+        }
+    }
+    return records;
+};
+/**
+ * CSV header: caseId,annotator,label[,note]. Handles quoted newlines.
+ */
+export const importAnnotationsCsv = (text) => {
+    const records = splitCsvRecords(text.replace(/^\uFEFF/, ""));
+    if (records.length === 0) {
+        return [];
+    }
+    const header = records[0].map((cell) => cell.trim());
+    const indexOf = (name) => header.indexOf(name);
+    if (indexOf("caseId") < 0 || indexOf("annotator") < 0 || indexOf("label") < 0) {
+        throw new Error("CSV header requires caseId, annotator, label");
+    }
+    return records.slice(1).map((cells, row) => {
+        const caseId = cells[indexOf("caseId")]?.trim();
+        const annotator = cells[indexOf("annotator")]?.trim();
+        const label = cells[indexOf("label")]?.trim();
+        if (caseId === (void 0) || annotator === (void 0) || label === (void 0)) {
+            throw new Error(`CSV row ${row + 2} is incomplete`);
+        }
+        const note = indexOf("note") >= 0 ? cells[indexOf("note")]?.trim() : undefined;
+        return { caseId, annotator, label, ...(note === (void 0) || note.length === 0 ? {} : { note }) };
+    });
+};
+/**
+ * Active learning: prefer predicted probability near 0.5 and high uncertainty.
+ */
+export const selectLabelCandidates = (candidates, budget) => {
+    return [...candidates]
+        .sort((left, right) => {
+        const leftScore = (1 - Math.abs(left.predicted - 0.5) * 2) * 0.6 + (left.uncertainty ?? 0) * 0.4;
+        const rightScore = (1 - Math.abs(right.predicted - 0.5) * 2) * 0.6 + (right.uncertainty ?? 0) * 0.4;
+        return rightScore - leftScore;
+    })
+        .slice(0, Math.max(0, budget));
+};
+/**
+ * Fill only unresolved ties; resolved cases keep their majority label.
+ */
+export const resolveUnresolved = (audit, resolutions) => {
+    const result = { ...audit.adjudicated };
+    for (const [caseId, label] of Object.entries(resolutions)) {
+        if (result[caseId] !== null) {
+            continue;
+        }
+        result[caseId] = label;
+    }
+    return result;
+};
+/**
+ * Reject an annotation batch before it is used for calibration.
+ */
+export const requireLabelCoverage = (audit, options = {}) => {
+    const minCoverage = options.minCoverage ?? 0.9;
+    const maxDuplicates = options.maxDuplicates ?? 0;
+    if (audit.coverage < minCoverage) {
+        throw new Error(`label coverage ${audit.coverage.toFixed(3)} < ${minCoverage}`);
+    }
+    if (audit.duplicates.length > maxDuplicates) {
+        throw new Error(`duplicate annotations: ${audit.duplicates.length}`);
+    }
+};
+export const importAnnotations = (input) => {
+    const rows = Array.isArray(input)
+        ? input
+        : `${input}`
+            .split(/\r?\n/)
+            .filter((line) => line.trim().length > 0)
+            .map((line) => JSON.parse(line));
+    return rows.map((row, index) => {
+        const value = row;
+        if (typeof (value.caseId) !== "string" || typeof (value.annotator) !== "string" || typeof (value.label) !== "string") {
+            throw new Error(`annotation ${index} requires caseId, annotator and label`);
+        }
+        return { caseId: value.caseId, annotator: value.annotator, label: value.label, ...(typeof (value.note) === "string" ? { note: value.note } : {}) };
+    });
+};
+const pairKappa = (caseIds, annotations, left, right) => {
+    const common = [];
+    for (const caseId of caseIds) {
+        const leftLabel = annotations.find((annotation) => annotation.caseId === caseId && annotation.annotator === left)?.label;
+        const rightLabel = annotations.find((annotation) => annotation.caseId === caseId && annotation.annotator === right)?.label;
+        if (leftLabel !== (void 0) && rightLabel !== (void 0)) {
+            common.push({ caseId, left: leftLabel, right: rightLabel });
+        }
+    }
+    if (common.length === 0) {
+        return { kappa: 1, common: 0 };
+    }
+    return {
+        kappa: cohenKappa(common.map((entry) => entry.left), common.map((entry) => entry.right)),
+        common: common.length,
+    };
+};
+export const auditLabels = (caseIds, annotations) => {
+    const ids = new Set(caseIds);
+    const annotators = [...new Set(annotations.map((annotation) => annotation.annotator))].sort();
+    const counts = new Map();
+    for (const annotation of annotations) {
+        counts.set(`${annotation.caseId}\u0000${annotation.annotator}`, (counts.get(`${annotation.caseId}\u0000${annotation.annotator}`) ?? 0) + 1);
+    }
+    const duplicates = [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([key, count]) => {
+        const [caseId, annotator] = key.split("\u0000");
+        return { caseId, annotator, count };
+    });
+    const missing = caseIds.filter((caseId) => !annotations.some((annotation) => annotation.caseId === caseId));
+    const disagreements = caseIds
+        .map((caseId) => {
+        const labels = {};
+        for (const annotation of annotations.filter((entry) => entry.caseId === caseId)) {
+            labels[annotation.label] = (labels[annotation.label] ?? 0) + 1;
+        }
+        return { caseId, labels };
+    })
+        .filter((entry) => Object.keys(entry.labels).length > 1);
+    const adjudicated = {};
+    for (const caseId of caseIds) {
+        const countsForCase = {};
+        for (const annotation of annotations.filter((entry) => entry.caseId === caseId)) {
+            countsForCase[annotation.label] = (countsForCase[annotation.label] ?? 0) + 1;
+        }
+        const ranked = Object.entries(countsForCase).sort((left, right) => right[1] - left[1]);
+        if (ranked.length === 0) {
+            adjudicated[caseId] = null;
+        }
+        else if (ranked.length > 1 && ranked[0][1] === ranked[1][1]) {
+            adjudicated[caseId] = null;
+        }
+        else {
+            adjudicated[caseId] = ranked[0][0];
+        }
+    }
+    const pairwiseKappa = [];
+    for (let left = 0; left < annotators.length; left += 1) {
+        for (let right = left + 1; right < annotators.length; right += 1) {
+            const result = pairKappa(caseIds, annotations, annotators[left], annotators[right]);
+            pairwiseKappa.push({ left: annotators[left], right: annotators[right], ...result });
+        }
+    }
+    const covered = caseIds.filter((caseId) => annotations.some((annotation) => annotation.caseId === caseId)).length;
+    return {
+        cases: caseIds.length,
+        annotations: annotations.filter((annotation) => ids.has(annotation.caseId)).length,
+        covered,
+        coverage: caseIds.length === 0 ? 1 : covered / caseIds.length,
+        missing,
+        duplicates,
+        disagreements,
+        annotators,
+        pairwiseKappa,
+        adjudicated,
+    };
+};

package/lib/evidence/evidenceGraph.d.ts

@@ -0,0 +1,37 @@
+export type EvidenceKind = "claim" | "evidence";
+export interface EvidenceNode {
+    readonly id: string;
+    readonly kind: EvidenceKind;
+    statement: string;
+    trust?: "self" | "verified" | "trusted" | "asserted" | "inferred" | "external";
+}
+export interface EvidenceImpact {
+    id: string;
+    /**
+     * One shortest dependency witness; null denotes an explicitly changed root.
+     */
+    via: string | null;
+}
+export declare class EvidenceGraph {
+    private readonly nodes;
+    private readonly forward;
+    private readonly reverse;
+    addClaim(id: string, statement: string): EvidenceNode;
+    addEvidence(id: string, statement: string, forClaim: string, trust?: EvidenceNode["trust"]): EvidenceNode;
+    addSource(id: string, statement: string, trust?: EvidenceNode["trust"]): EvidenceNode;
+    link(from: string, to: string): void;
+    /**
+     * Multi-source breadth-first impact closure, including the changed roots.
+     * Visits only reachable adjacency, once per node, in container iteration order.
+     * This is a review set, not a verdict that dependent claims are false.
+     */
+    impact(changedIds: readonly string[]): EvidenceImpact[];
+    get(id: string): EvidenceNode | undefined;
+    evidenceFor(claimId: string): string[];
+    claimsFor(evidenceId: string): string[];
+    hasCycle(): boolean;
+    get size(): number;
+    private addNode;
+    private reaches;
+    private edge;
+}