attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/authz/authz.js

@@ -0,0 +1,176 @@
+import { AuthzError } from "../error/authzError.js";
+import { putObject } from "../database/store/database.js";
+const AllActions = ["read", "write", "append", "grant", "revoke", "spawn", "kill", "send", "receive", "fork", "join"];
+const toCapability = (row) => {
+    const subject = { kind: row.subject_kind, id: row.subject_id };
+    if (row.subject_pid !== null) {
+        subject.pid = row.subject_pid;
+    }
+    const resource = { kind: row.resource_kind, id: row.resource_id };
+    if (row.owner_pid !== null) {
+        resource.ownerPid = row.owner_pid;
+    }
+    const capability = {
+        hid: row.hid,
+        id: row.id,
+        subject,
+        resource,
+        rights: JSON.parse(row.rights),
+        scope: row.scope,
+        createdAt: row.created_at,
+    };
+    if (row.parent_hid !== null) {
+        capability.parentHid = row.parent_hid;
+    }
+    if (row.expires_at !== null) {
+        capability.expiresAt = row.expires_at;
+    }
+    if (row.revoked_at !== null) {
+        capability.revokedAt = row.revoked_at;
+    }
+    if (row.granted_by !== null) {
+        capability.grantedBy = row.granted_by;
+    }
+    return capability;
+};
+const live = (row, at) => row.revoked_at === null && (row.expires_at === null || row.expires_at > at);
+const rowsFor = (db, subject, resource, at) => {
+    const subjects = [subject];
+    // A thread also acts with the capabilities of its process (fds are shared).
+    if (subject.kind === "thread" && subject.pid !== (void 0)) {
+        subjects.push({ kind: "process", id: `p.${subject.pid}`, pid: subject.pid });
+    }
+    const rows = [];
+    for (const candidate of subjects) {
+        const found = db
+            .prepare(`SELECT * FROM handles
+                 WHERE subject_kind = ? AND subject_id = ?
+                   AND resource_kind = ? AND resource_id = ?
+                 ORDER BY hid ASC`)
+            .all(candidate.kind, candidate.id, resource.kind, resource.id);
+        rows.push(...found.filter((row) => live(row, at)));
+    }
+    if (subject.kind === "thread" && subject.pid !== (void 0)) {
+        const inherited = db
+            .prepare(`SELECT * FROM handles
+                 WHERE subject_kind = 'process' AND subject_pid = ?
+                   AND resource_kind = ? AND resource_id = ?
+                 ORDER BY hid ASC`)
+            .all(subject.pid, resource.kind, resource.id);
+        rows.push(...inherited.filter((row) => live(row, at)));
+    }
+    return rows;
+};
+const isOwner = (subject, resource) => resource.ownerPid !== (void 0) && subject.pid === resource.ownerPid;
+/**
+ * Rights the subject actually holds on the resource, including ownership.
+ */
+export const effectiveRights = (db, subject, resource, at) => {
+    if (subject.kind === "host" || isOwner(subject, resource)) {
+        return [...AllActions];
+    }
+    const rights = new Set();
+    for (const row of rowsFor(db, subject, resource, at)) {
+        for (const right of JSON.parse(row.rights)) {
+            rights.add(right);
+        }
+    }
+    return [...rights];
+};
+export const can = (db, subject, action, resource, at) => {
+    return effectiveRights(db, subject, resource, at).includes(action);
+};
+/**
+ * Throws unless the subject holds `action` on `resource`.
+ */
+export const requirePermission = (db, subject, action, resource, at) => {
+    if (can(db, subject, action, resource, at)) {
+        return;
+    }
+    throw new AuthzError("permission_denied", [`${subject.kind}:${subject.id} may not ${action} ${resource.kind}:${resource.id}`]);
+};
+export const listCapabilities = (db, subject) => {
+    const rows = db
+        .prepare("SELECT * FROM handles WHERE subject_kind = ? AND subject_id = ? ORDER BY hid ASC")
+        .all(subject.kind, subject.id);
+    return rows.map(toCapability);
+};
+/**
+ * Grant a subset of the grantor's rights to another subject.
+ *
+ * Amplification is rejected in both dimensions the model cares about: no new
+ * right may appear, and the new expiry may not outlive the grantor's own.
+ */
+export const grant = (db, input, at) => {
+    if (input.rights.length === 0) {
+        throw new AuthzError("invalid_grant", ["rights must not be empty"]);
+    }
+    if (input.grantee.kind === "host") {
+        throw new AuthzError("invalid_grant", ["cannot grant to host"]);
+    }
+    requirePermission(db, input.grantor, "grant", input.resource, at);
+    const available = effectiveRights(db, input.grantor, input.resource, at);
+    const amplified = input.rights.filter((right) => !available.includes(right));
+    if (amplified.length > 0) {
+        throw new AuthzError("rights_amplification", [`grantor does not hold ${amplified.join(", ")}`]);
+    }
+    const source = rowsFor(db, input.grantor, input.resource, at).find((row) => JSON.parse(row.rights).includes("grant"));
+    const sourceExpiry = source?.expires_at ?? undefined;
+    if (sourceExpiry !== (void 0) && (input.expiresAt === (void 0) || input.expiresAt > sourceExpiry)) {
+        throw new AuthzError("expiry_amplification", [`grant expires after the grantor's capability (${sourceExpiry})`]);
+    }
+    const count = db.prepare("SELECT COUNT(*) AS n FROM handles").get();
+    const hid = count.n + 1;
+    const id = `h.${hid}`;
+    const scope = input.scope ?? (input.grantee.kind === "thread" ? "thread" : "process");
+    const result = db
+        .prepare(`INSERT INTO handles
+             (id, subject_kind, subject_id, subject_pid, resource_kind, resource_id, owner_pid, rights, scope, parent_hid, expires_at, granted_by, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, input.grantee.kind, input.grantee.id, input.grantee.pid ?? null, input.resource.kind, input.resource.id, input.resource.ownerPid ?? null, JSON.stringify(input.rights), scope, source?.hid ?? null, input.expiresAt ?? null, input.grantor.id, at);
+    const row = db.prepare("SELECT * FROM handles WHERE hid = ?").get(Number(result.lastInsertRowid));
+    putObject(db, "event", `ev.authz.grant.${row.hid}`, {
+        amp: "0.1",
+        kind: "event",
+        id: `ev.authz.grant.${row.hid}`,
+        at,
+        actor: { kind: input.grantor.kind === "host" ? "self" : "agent", id: input.grantor.id },
+        type: "authz.granted",
+        payload: { capability: id, grantee: input.grantee.id, resource: input.resource, rights: input.rights },
+    }, at);
+    return toCapability(row);
+};
+/**
+ * Revoke a capability and every grant derived from it.
+ */
+export const revoke = (db, subject, hid, at) => {
+    const row = db.prepare("SELECT * FROM handles WHERE hid = ?").get(hid);
+    if (row === (void 0)) {
+        throw new AuthzError("unknown_capability", [`hid ${hid}`]);
+    }
+    const capability = toCapability(row);
+    requirePermission(db, subject, "revoke", capability.resource, at);
+    const result = db
+        .prepare(`WITH RECURSIVE tree(hid) AS (
+               SELECT ?
+               UNION ALL
+               SELECT h.hid FROM handles h JOIN tree t ON h.parent_hid = t.hid
+             )
+             UPDATE handles SET revoked_at = ?
+             WHERE hid IN (SELECT hid FROM tree) AND revoked_at IS NULL`)
+        .run(hid, at);
+    const count = Number(result.changes);
+    if (count === 0) {
+        return 0;
+    }
+    putObject(db, "event", `ev.authz.revoke.${hid}.${count}`, {
+        amp: "0.1",
+        kind: "event",
+        id: `ev.authz.revoke.${hid}.${count}`,
+        at,
+        actor: { kind: "self", id: subject.id },
+        type: "authz.revoked",
+        payload: { capability: hid, revoked: count },
+    }, at);
+    return count;
+};

package/lib/authz/index.d.ts

@@ -0,0 +1 @@
+export * from "./authz.js";

package/lib/authz/index.js

@@ -0,0 +1 @@
+export * from "./authz.js";

package/lib/bayes/calibration.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Post-hoc calibration utilities.
+ *
+ * The model's posterior is not trusted as-is; we measure ECE/Brier and fit a
+ * monotone isotonic map only for evaluation. Cross-validation is mandatory on
+ * small samples so the "improvement" is not just in-sample overfit.
+ */
+export interface CalibrationPoint {
+    predicted: number;
+    actual: boolean;
+}
+export interface IsotonicModel {
+    /**
+     * Upper predicted bound of each block.
+     */
+    thresholds: number[];
+    /**
+     * Observed frequency of each block.
+     */
+    values: number[];
+}
+/**
+ * Calibration statistics for one set of predictions.
+ */
+type CalibrationReport = {
+    ece: number;
+    brier: number;
+    rawEce: number;
+    rawBrier: number;
+};
+/**
+ * Expected calibration error over optionally binned predictions.
+ */
+type EceScore = (points: readonly CalibrationPoint[], bins?: number) => number;
+/**
+ * Fit an isotonic map to the given points.
+ */
+type FitIsotonic = (points: readonly CalibrationPoint[]) => IsotonicModel;
+/**
+ * Fit a temperature scalar to the given points.
+ */
+type FitTemperature = (points: readonly CalibrationPoint[], grid?: readonly number[]) => TemperatureModel;
+/**
+ * Apply a temperature scalar to one prediction.
+ */
+type ApplyTemperature = (model: TemperatureModel, predicted: number) => number;
+/**
+ * Cross-validated calibration report.
+ */
+type CrossValidate = (points: readonly CalibrationPoint[], folds?: number) => CalibrationReport;
+export declare const brier: (points: readonly CalibrationPoint[]) => number;
+export declare const ece: EceScore;
+/**
+ * Pool-adjacent-violators isotonic regression.
+ */
+export declare const fitIsotonic: FitIsotonic;
+export declare const applyIsotonic: (model: IsotonicModel, predicted: number) => number;
+export interface TemperatureModel {
+    temperature: number;
+}
+/**
+ * Grid-fit temperature by NLL; T<1 sharpens, T>1 softens.
+ */
+export declare const fitTemperature: FitTemperature;
+export declare const applyTemperature: ApplyTemperature;
+export declare const crossValidateCalibration: CrossValidate;
+export {};

package/lib/bayes/calibration.js

@@ -0,0 +1,114 @@
+const DefaultGrid = [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 2.5, 3, 4, 5];
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+export const brier = (points) => {
+    if (points.length === 0) {
+        return 0;
+    }
+    return points.reduce((sum, point) => sum + (point.predicted - (point.actual ? 1 : 0)) ** 2, 0) / points.length;
+};
+export const ece = (points, bins = 10) => {
+    if (points.length === 0) {
+        return 0;
+    }
+    const buckets = Array.from({ length: bins }, () => ({ n: 0, confidence: 0, accuracy: 0 }));
+    for (let i = 0; i < points.length; i += 1) {
+        const point = points[i];
+        const index = Math.min(bins - 1, Math.max(0, Math.floor(clamp01(point.predicted) * bins)));
+        buckets[index].n += 1;
+        buckets[index].confidence += point.predicted;
+        buckets[index].accuracy += point.actual ? 1 : 0;
+    }
+    return buckets.reduce((sum, bucket) => {
+        if (bucket.n === 0) {
+            return sum;
+        }
+        return sum + (bucket.n / points.length) * Math.abs(bucket.accuracy / bucket.n - bucket.confidence / bucket.n);
+    }, 0);
+};
+/**
+ * Pool-adjacent-violators isotonic regression.
+ */
+export const fitIsotonic = (points) => {
+    const sorted = [...points].sort((left, right) => left.predicted - right.predicted);
+    const blocks = [];
+    for (let i = 0; i < sorted.length; i += 1) {
+        const point = sorted[i];
+        blocks.push({ sum: point.actual ? 1 : 0, n: 1, max: point.predicted });
+        while (blocks.length >= 2) {
+            const current = blocks[blocks.length - 1];
+            const previous = blocks[blocks.length - 2];
+            if (previous.sum / previous.n <= current.sum / current.n) {
+                break;
+            }
+            blocks.splice(blocks.length - 2, 2, {
+                sum: previous.sum + current.sum,
+                n: previous.n + current.n,
+                max: current.max,
+            });
+        }
+    }
+    return {
+        thresholds: blocks.map((block) => block.max),
+        values: blocks.map((block) => block.sum / block.n),
+    };
+};
+export const applyIsotonic = (model, predicted) => {
+    if (model.thresholds.length === 0) {
+        return clamp01(predicted);
+    }
+    const index = model.thresholds.findIndex((threshold) => predicted <= threshold);
+    return model.values[index === -1 ? model.values.length - 1 : index];
+};
+const logit = (value) => {
+    const bounded = Math.max(1e-6, Math.min(1 - 1e-6, value));
+    return Math.log(bounded / (1 - bounded));
+};
+const sigmoid = (value) => 1 / (1 + Math.exp(-value));
+/**
+ * Grid-fit temperature by NLL; T<1 sharpens, T>1 softens.
+ */
+export const fitTemperature = (points, grid = DefaultGrid) => {
+    if (points.length === 0) {
+        return { temperature: 1 };
+    }
+    let best = 1;
+    let bestLoss = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < grid.length; i += 1) {
+        const temperature = grid[i];
+        const loss = points.reduce((sum, point) => {
+            const calibrated = sigmoid(logit(point.predicted) / temperature);
+            const target = point.actual ? 1 : 0;
+            return sum - (target * Math.log(Math.max(1e-9, calibrated)) + (1 - target) * Math.log(Math.max(1e-9, 1 - calibrated)));
+        }, 0);
+        if (loss < bestLoss) {
+            bestLoss = loss;
+            best = temperature;
+        }
+    }
+    return { temperature: best };
+};
+export const applyTemperature = (model, predicted) => sigmoid(logit(predicted) / model.temperature);
+export const crossValidateCalibration = (points, folds = 5) => {
+    if (points.length === 0) {
+        return { ece: 0, brier: 0, rawEce: 0, rawBrier: 0 };
+    }
+    const predictions = [];
+    for (let fold = 0; fold < folds; fold += 1) {
+        const train = points.filter((_point, index) => index % folds !== fold);
+        const test = points.filter((_point, index) => index % folds === fold);
+        if (train.length === 0 || test.length === 0) {
+            continue;
+        }
+        const model = fitIsotonic(train);
+        for (let i = 0; i < test.length; i += 1) {
+            const point = test[i];
+            predictions.push({ predicted: applyIsotonic(model, point.predicted), actual: point.actual });
+        }
+    }
+    return {
+        ece: ece(predictions),
+        brier: brier(predictions),
+        rawEce: ece(points),
+        rawBrier: brier(points),
+    };
+};

package/lib/bayes/calibrationRegistry.d.ts

@@ -0,0 +1,39 @@
+import type { CalibrationPoint } from "./calibration.js";
+import type { CalibrationMethod, CalibrationSelection } from "./calibrationSelection.js";
+export interface CalibrationModel {
+    scope: string;
+    method: CalibrationMethod;
+    samples: number;
+    rawEce: number;
+    cvEce: number;
+    thresholds: number[];
+    values: number[];
+    temperature?: number;
+    ciLower: number;
+    ciUpper: number;
+    activatedAt: string;
+}
+export interface RegisterOptions {
+    minSamples?: number;
+    minImprovement?: number;
+    folds?: number;
+    /**
+     * Require the bootstrap 95% upper bound to be below zero.
+     */
+    requireCi?: boolean;
+    bootstrapSamples?: number;
+    seed?: number;
+    at?: string;
+}
+export interface RegisterResult {
+    status: "raw" | "activated";
+    selection: CalibrationSelection;
+    model?: CalibrationModel;
+}
+export declare class CalibrationRegistry {
+    private readonly models;
+    register(scope: string, points: readonly CalibrationPoint[], options?: RegisterOptions): RegisterResult;
+    calibrate(scope: string, predicted: number): number;
+    model(scope: string): CalibrationModel | undefined;
+    scopes(): string[];
+}

package/lib/bayes/calibrationRegistry.js

@@ -0,0 +1,61 @@
+/**
+ * Calibration registry.
+ *
+ * A fitted map is activated only when there are enough points AND its
+ * cross-validated ECE beats raw by `minImprovement`. Otherwise the scope stays
+ * raw. This prevents the "isotonic made it worse" failure from shipping.
+ */
+import { applyIsotonic, applyTemperature, fitIsotonic, fitTemperature } from "./calibration.js";
+import { selectCalibration, bootstrapEceDelta } from "./calibrationSelection.js";
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+export class CalibrationRegistry {
+    models = new Map();
+    register(scope, points, options = {}) {
+        const minSamples = options.minSamples ?? 30;
+        const minImprovement = options.minImprovement ?? 0.01;
+        const selection = selectCalibration(points, options.folds ?? 5);
+        const candidate = points.length >= minSamples && selection.method !== "raw" && selection.rawEce - selection.ece >= minImprovement;
+        const ci = candidate
+            ? bootstrapEceDelta(points, selection.method, options.folds ?? 5, options.bootstrapSamples ?? 500, options.seed ?? 42)
+            : { mean: 0, lower: 0, upper: 0 };
+        const improves = candidate && (options.requireCi === false || ci.upper < 0);
+        if (!improves) {
+            this.models.delete(scope);
+            return { status: "raw", selection };
+        }
+        const model = fitIsotonic(points);
+        const temperature = fitTemperature(points);
+        const record = {
+            scope,
+            method: selection.method,
+            samples: points.length,
+            rawEce: selection.rawEce,
+            cvEce: selection.ece,
+            thresholds: model.thresholds,
+            values: model.values,
+            ...(selection.method === "temperature" ? { temperature: temperature.temperature } : {}),
+            ciLower: ci.lower,
+            ciUpper: ci.upper,
+            activatedAt: options.at ?? new Date().toISOString(),
+        };
+        this.models.set(scope, record);
+        return { status: "activated", selection, model: record };
+    }
+    calibrate(scope, predicted) {
+        const model = this.models.get(scope);
+        if (model === (void 0)) {
+            return clamp01(predicted);
+        }
+        if (model.method === "temperature") {
+            return applyTemperature({ temperature: model.temperature ?? 1 }, predicted);
+        }
+        const calibrated = applyIsotonic({ thresholds: model.thresholds, values: model.values }, predicted);
+        return model.method === "isotonic" ? calibrated : 0.5 * calibrated + 0.5 * clamp01(predicted);
+    }
+    model(scope) {
+        return this.models.get(scope);
+    }
+    scopes() {
+        return [...this.models.keys()];
+    }
+}

package/lib/bayes/calibrationSelection.d.ts

@@ -0,0 +1,40 @@
+import type { CalibrationPoint } from "./calibration.js";
+export type CalibrationMethod = "raw" | "isotonic" | "shrunk" | "temperature";
+export interface CalibrationSelection {
+    method: CalibrationMethod;
+    ece: number;
+    brier: number;
+    rawEce: number;
+    rawBrier: number;
+}
+export interface CvPrediction {
+    predicted: number;
+    actual: boolean;
+}
+/**
+ * Emits one out-of-fold prediction per calibration point.
+ */
+type CrossValidatedPredictor = (points: readonly CalibrationPoint[], method: CalibrationMethod, folds: number) => CvPrediction[];
+export declare const crossValidatedPredictions: CrossValidatedPredictor;
+/**
+ * Percentile interval for the paired ECE delta.
+ */
+type BootstrapInterval = {
+    mean: number;
+    lower: number;
+    upper: number;
+};
+/**
+ * Bootstrap signature for the ECE delta estimate.
+ */
+type BootstrapDelta = (points: readonly CalibrationPoint[], method: CalibrationMethod, folds?: number, samples?: number, seed?: number) => BootstrapInterval;
+/**
+ * Paired bootstrap of ECE(calibrated) - ECE(raw); negative means improvement.
+ */
+export declare const bootstrapEceDelta: BootstrapDelta;
+/**
+ * Picks the calibration method with the lowest cross-validated ECE.
+ */
+type CalibrationSelector = (points: readonly CalibrationPoint[], folds?: number) => CalibrationSelection;
+export declare const selectCalibration: CalibrationSelector;
+export {};

package/lib/bayes/calibrationSelection.js

@@ -0,0 +1,89 @@
+/**
+ * Calibration model selection. Fits raw / isotonic / shrunk isotonic /
+ * temperature on each cross-validation fold and picks the lowest ECE; ties
+ * prefer raw.
+ */
+import { applyIsotonic, applyTemperature, brier, ece, fitIsotonic, fitTemperature } from "./calibration.js";
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+const predict = (method, isotonic, temperature, value) => {
+    if (method === "raw") {
+        return clamp01(value);
+    }
+    if (method === "temperature") {
+        return applyTemperature(temperature, value);
+    }
+    const calibrated = applyIsotonic(isotonic, value);
+    return method === "isotonic" ? calibrated : 0.5 * calibrated + 0.5 * value;
+};
+export const crossValidatedPredictions = (points, method, folds) => {
+    const predictions = [];
+    for (let fold = 0; fold < folds; fold += 1) {
+        const train = points.filter((_, index) => index % folds !== fold);
+        const test = points.filter((_, index) => index % folds === fold);
+        if (train.length === 0 || test.length === 0) {
+            continue;
+        }
+        const isotonic = fitIsotonic(train);
+        const temperature = fitTemperature(train);
+        for (let index = 0; index < test.length; index += 1) {
+            const point = test[index];
+            predictions.push({ predicted: predict(method, isotonic, temperature, point.predicted), actual: point.actual });
+        }
+    }
+    return predictions;
+};
+const crossValidate = (points, method, folds) => {
+    const predictions = crossValidatedPredictions(points, method, folds);
+    return { ece: ece(predictions), brier: brier(predictions) };
+};
+const mulberry32 = (seed) => {
+    let state = seed >>> 0;
+    return () => {
+        state += 0x6d2b79f5;
+        let value = Math.imul(state ^ (state >>> 15), 1 | state);
+        value ^= value + Math.imul(value ^ (value >>> 7), 61 | value);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    };
+};
+/**
+ * Paired bootstrap of ECE(calibrated) - ECE(raw); negative means improvement.
+ */
+export const bootstrapEceDelta = (points, method, folds = 5, samples = 500, seed = 42) => {
+    const raw = crossValidatedPredictions(points, "raw", folds);
+    const calibrated = crossValidatedPredictions(points, method, folds);
+    if (raw.length === 0 || raw.length !== calibrated.length) {
+        return { mean: 0, lower: 0, upper: 0 };
+    }
+    const random = mulberry32(seed);
+    const deltas = [];
+    for (let sample = 0; sample < samples; sample += 1) {
+        const left = [];
+        const right = [];
+        for (let index = 0; index < raw.length; index += 1) {
+            const pick = Math.floor(random() * raw.length);
+            left.push(raw[pick]);
+            right.push(calibrated[pick]);
+        }
+        deltas.push(ece(right) - ece(left));
+    }
+    deltas.sort((a, b) => a - b);
+    const mean = deltas.reduce((sum, value) => sum + value, 0) / deltas.length;
+    return {
+        mean,
+        lower: deltas[Math.floor(deltas.length * 0.025)] ?? mean,
+        upper: deltas[Math.floor(deltas.length * 0.975)] ?? mean,
+    };
+};
+export const selectCalibration = (points, folds = 5) => {
+    const rawEce = ece(points);
+    const rawBrier = brier(points);
+    const candidates = [{ method: "raw", ece: rawEce, brier: rawBrier, rawEce, rawBrier }];
+    const methods = ["isotonic", "shrunk", "temperature"];
+    for (let index = 0; index < methods.length; index += 1) {
+        const method = methods[index];
+        const score = crossValidate(points, method, folds);
+        candidates.push({ method, ece: score.ece, brier: score.brier, rawEce, rawBrier });
+    }
+    candidates.sort((left, right) => left.ece - right.ece || (left.method === "raw" ? -1 : 1));
+    return candidates[0];
+};