attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/attention/resource.js

@@ -0,0 +1,148 @@
+export const DefaultAttentionPolicy = {
+    baseSlots: 4,
+    reserveRatio: 0.25,
+    safetyFloorRatio: 0.1,
+    maxForegroundUtil: 0.75,
+    minSliceSlots: 1,
+    restAfterCycles: 8,
+    vigilanceFloor: 0.25,
+    loadCeiling: 0.9,
+    recoveryDebtThreshold: 0.7,
+};
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+export const recoveryDebtOf = (state) => {
+    return clamp01(0.5 * (1 - state.vigilance) + 0.3 * state.load + 0.2 * state.pLapse);
+};
+export const shouldRest = (state, policy = DefaultAttentionPolicy) => {
+    return (state.cyclesSinceRest >= policy.restAfterCycles ||
+        state.vigilance <= policy.vigilanceFloor ||
+        state.load >= policy.loadCeiling ||
+        recoveryDebtOf(state) >= policy.recoveryDebtThreshold);
+};
+export const processAttention = (pid, state, policy = DefaultAttentionPolicy) => {
+    const effectiveSlots = Math.max(1, Math.floor(state.capacityEff));
+    const safetySlots = Math.min(effectiveSlots, Math.max(1, Math.floor(effectiveSlots * policy.safetyFloorRatio)));
+    const rawCap = Math.max(0, Math.floor(effectiveSlots * policy.maxForegroundUtil));
+    const foregroundCap = Math.max(0, Math.min(rawCap, effectiveSlots - safetySlots));
+    const reserveSlots = Math.max(safetySlots, effectiveSlots - foregroundCap);
+    return {
+        pid,
+        effectiveSlots,
+        foregroundCap,
+        reserveSlots,
+        safetySlots,
+        state,
+        recoveryDebt: recoveryDebtOf(state),
+        offline: shouldRest(state, policy),
+    };
+};
+const toAttention = (candidate, slots, foreground) => {
+    const attention = {
+        tid: candidate.tid,
+        pid: candidate.pid,
+        slots,
+        foreground,
+        priority: candidate.priority,
+        switchCost: Math.max(0, candidate.switchCost ?? 0),
+    };
+    if (candidate.role !== (void 0)) {
+        attention.role = candidate.role;
+    }
+    return attention;
+};
+/**
+ * Allocate one foreground task and, from the reserve, background tasks.
+ *
+ * Floors are intentionally asymmetric: safety is always reserved, every
+ * admitted task gets `minSlots`, but a deferred task gets no floor. Guaranteeing
+ * a floor to every candidate would make admission meaningless under pressure.
+ */
+export const planAttention = (process, candidates, policy = DefaultAttentionPolicy) => {
+    const deferred = [];
+    const background = [];
+    const sorted = [...candidates].sort((left, right) => right.priority - left.priority || left.tid - right.tid);
+    const foregroundCandidates = sorted.filter((candidate) => candidate.foreground !== false);
+    const backgroundCandidates = sorted.filter((candidate) => candidate.foreground === false);
+    if (process.offline) {
+        for (const candidate of foregroundCandidates) {
+            deferred.push({ tid: candidate.tid, reason: "offline" });
+        }
+        return {
+            process,
+            background,
+            deferred,
+            utilization: 0,
+            pressure: 1,
+            rest: true,
+        };
+    }
+    let foreground;
+    let remaining = process.foregroundCap;
+    for (let index = 0; index < foregroundCandidates.length; index += 1) {
+        const candidate = foregroundCandidates[index];
+        const minSlots = Math.max(1, candidate.minSlots ?? policy.minSliceSlots);
+        if (index === 0 && remaining >= minSlots) {
+            const slots = Math.min(remaining, Math.max(minSlots, Math.floor(candidate.preferredSlots)));
+            foreground = toAttention(candidate, slots, true);
+            remaining -= slots;
+        }
+        else {
+            deferred.push({ tid: candidate.tid, reason: index === 0 ? "budget" : "low-priority" });
+        }
+    }
+    let reserveRemaining = Math.max(0, process.effectiveSlots - process.safetySlots - (foreground?.slots ?? 0));
+    for (const candidate of backgroundCandidates) {
+        const minSlots = Math.max(1, candidate.minSlots ?? policy.minSliceSlots);
+        if (reserveRemaining < minSlots) {
+            deferred.push({ tid: candidate.tid, reason: "budget" });
+            continue;
+        }
+        const slots = Math.min(reserveRemaining, Math.max(minSlots, Math.floor(candidate.preferredSlots)));
+        background.push(toAttention(candidate, slots, false));
+        reserveRemaining -= slots;
+    }
+    const allocated = (foreground?.slots ?? 0) + background.reduce((sum, task) => sum + task.slots, 0);
+    const utilization = allocated / process.effectiveSlots;
+    const switchPressure = foreground === (void 0) ? 0 : Math.min(1, foreground.switchCost / Math.max(1, process.effectiveSlots));
+    const pressure = Math.min(1.5, deferred.length / Math.max(1, candidates.length) + switchPressure);
+    return {
+        process,
+        ...(foreground === (void 0) ? {} : { foreground }),
+        background,
+        deferred,
+        utilization,
+        pressure,
+        rest: false,
+    };
+};
+/**
+ * Rest restores vigilance, reduces load and clears the rest counter.
+ */
+export const applyRest = (state, cycles = 1) => {
+    const amount = Math.max(1, Math.floor(cycles));
+    const vigilance = clamp01(state.vigilance + 0.25 * amount);
+    const load = clamp01(state.load - 0.2 * amount);
+    return {
+        ...state,
+        vigilance,
+        load,
+        pLapse: clamp01(1 - vigilance),
+        cyclesSinceRest: 0,
+    };
+};
+/**
+ * Efficiency is useful outcomes per unit of attention, not raw utilization.
+ * Errors and rework are subtracted so a busy-but-wrong agent cannot win.
+ */
+export const qualityAdjustedThroughput = (stats) => {
+    const useful = Math.max(0, stats.successes - stats.errors - stats.rework);
+    return useful / Math.max(1, stats.attentionSlots);
+};
+export const attentionHealth = (plan) => {
+    return {
+        utilization: plan.utilization,
+        pressure: plan.pressure,
+        headroom: Math.max(0, 1 - plan.utilization),
+        rest: plan.rest,
+    };
+};

package/lib/attention/social.d.ts

@@ -0,0 +1,74 @@
+import type { Id, Timestamp } from "../types/common.js";
+import type { AttentionRequest, InterruptClass } from "./socialTypes.js";
+export type Decision = "grant" | "defer" | "deny";
+export interface AttentionPolicy {
+    /**
+     * Grants allowed per class per rolling hour. Safety is never blocked by this.
+     */
+    budgets: Record<InterruptClass, number>;
+    quietHours?: {
+        start: number;
+        end: number;
+    };
+    cooldownMinutes?: number;
+    /**
+     * Curiosity must clear this expected value to be granted at all.
+     */
+    curiosityFloor?: number;
+}
+export declare const DefaultPolicy: AttentionPolicy;
+export interface AttentionDecision {
+    request: Id;
+    decision: Decision;
+    reason: string;
+    at: Timestamp;
+    class: InterruptClass;
+    debtAdded: boolean;
+}
+export interface DebtEntry {
+    request: Id;
+    class: InterruptClass;
+    openedAt: Timestamp;
+    weight: number;
+    resolvedAt?: Timestamp;
+}
+type BrokerOptions = {
+    now: () => Timestamp;
+    policy?: Partial<AttentionPolicy>;
+};
+/**
+ * Attention broker (Profile `Social`).
+ *
+ * The human's attention is a budgeted resource, not a callable function.
+ * Safety bypasses the budget; everything else queues, cools down, or is denied.
+ */
+export declare class AttentionBroker {
+    private readonly policy;
+    private readonly now;
+    private readonly requests;
+    private readonly decisions;
+    private readonly grants;
+    private readonly lastTouch;
+    private readonly debt;
+    constructor(options: BrokerOptions);
+    submit(request: AttentionRequest): AttentionDecision;
+    private decide;
+    private defer;
+    private grantedThisHour;
+    private recordGrant;
+    /**
+     * Resolve a deferred request: it is answered, expired, or withdrawn.
+     */
+    resolve(requestId: Id, outcome?: "answered" | "expired" | "withdrawn"): void;
+    /**
+     * Age-weighted debt: minutes open × urgency. Higher means more owed.
+     */
+    debtScore(at?: Timestamp): number;
+    openDebt(): DebtEntry[];
+    /**
+     * How many requests were granted (feeds the unified ledger snapshot).
+     */
+    grantedCount(): number;
+    decisionOf(requestId: Id): AttentionDecision | undefined;
+}
+export {};

package/lib/attention/social.js

@@ -0,0 +1,153 @@
+export const DefaultPolicy = {
+    budgets: { safety: 1, commitment: 3, opportunity: 2, curiosity: 1 },
+    quietHours: { start: 22, end: 7 },
+    cooldownMinutes: 10,
+    curiosityFloor: 0.7,
+};
+/**
+ * Attention broker (Profile `Social`).
+ *
+ * The human's attention is a budgeted resource, not a callable function.
+ * Safety bypasses the budget; everything else queues, cools down, or is denied.
+ */
+export class AttentionBroker {
+    policy;
+    now;
+    requests = new Map();
+    decisions = new Map();
+    grants = new Map();
+    lastTouch = new Map();
+    debt = [];
+    constructor(options) {
+        this.now = options.now;
+        this.policy = {
+            ...DefaultPolicy,
+            ...options.policy,
+            budgets: { ...DefaultPolicy.budgets, ...(options.policy?.budgets ?? {}) },
+        };
+    }
+    submit(request) {
+        if (!request.why_now || !request.if_ignored) {
+            throw new Error("an attention request needs why_now and if_ignored");
+        }
+        if (this.requests.has(request.id)) {
+            throw new Error(`duplicate request: ${request.id}`);
+        }
+        this.requests.set(request.id, request);
+        const at = this.now();
+        const kind = request.class;
+        const decision = this.decide(request, at, kind);
+        this.decisions.set(request.id, decision);
+        if (decision.decision === "grant") {
+            this.recordGrant(kind, at);
+            this.lastTouch.set(request.target.id, Date.parse(at));
+        }
+        if (decision.decision !== "grant") {
+            this.lastTouch.set(request.id, Date.parse(at));
+        }
+        if (decision.debtAdded) {
+            this.debt.push({ request: request.id, class: kind, openedAt: at, weight: request.urgency });
+        }
+        return decision;
+    }
+    decide(request, at, kind) {
+        const immediate = {
+            request: request.id,
+            decision: "grant",
+            reason: "safety_bypass",
+            at,
+            class: kind,
+            debtAdded: false,
+        };
+        if (kind === "safety") {
+            return immediate;
+        }
+        const hour = new Date(at).getUTCHours();
+        const quiet = this.policy.quietHours;
+        const inQuietHours = quiet
+            ? quiet.start <= quiet.end
+                ? hour >= quiet.start && hour < quiet.end
+                : hour >= quiet.start || hour < quiet.end
+            : false;
+        if (inQuietHours) {
+            return this.defer(request, at, kind, "quiet_hours");
+        }
+        const cooldown = this.policy.cooldownMinutes ?? 0;
+        const touched = this.lastTouch.get(request.target.id);
+        if (touched !== (void 0) && cooldown > 0) {
+            const elapsed = (Date.parse(at) - touched) / 60_000;
+            if (elapsed < cooldown) {
+                return this.defer(request, at, kind, "cooldown");
+            }
+        }
+        if (kind === "curiosity" && (request.expected_value ?? 0) < (this.policy.curiosityFloor ?? 0)) {
+            return { request: request.id, decision: "deny", reason: "curiosity_below_floor", at, class: kind, debtAdded: false };
+        }
+        if (this.grantedThisHour(kind, at) >= this.policy.budgets[kind]) {
+            return request.fallback === "queue"
+                ? this.defer(request, at, kind, "budget_exhausted")
+                : { request: request.id, decision: "deny", reason: "budget_exhausted", at, class: kind, debtAdded: false };
+        }
+        return { request: request.id, decision: "grant", reason: "within_budget", at, class: kind, debtAdded: false };
+    }
+    defer(request, at, kind, reason) {
+        if (request.fallback === "drop") {
+            return { request: request.id, decision: "deny", reason: `${reason}:fallback_drop`, at, class: kind, debtAdded: false };
+        }
+        this.lastTouch.set(request.target.id, Date.parse(at));
+        return { request: request.id, decision: "defer", reason, at, class: kind, debtAdded: true };
+    }
+    grantedThisHour(kind, at) {
+        const now = Date.parse(at);
+        const window = (this.grants.get(kind) ?? []).filter((stamp) => now - Date.parse(stamp) < 3_600_000);
+        this.grants.set(kind, window);
+        return window.length;
+    }
+    recordGrant(kind, at) {
+        const list = this.grants.get(kind) ?? [];
+        list.push(at);
+        this.grants.set(kind, list);
+        this.lastTouch.set(kind, Date.parse(at));
+    }
+    /**
+     * Resolve a deferred request: it is answered, expired, or withdrawn.
+     */
+    resolve(requestId, outcome = "answered") {
+        const entry = this.debt.find((item) => item.request === requestId && !item.resolvedAt);
+        if (!entry) {
+            throw new Error(`no open debt for ${requestId}`);
+        }
+        entry.resolvedAt = this.now();
+        void outcome;
+    }
+    /**
+     * Age-weighted debt: minutes open × urgency. Higher means more owed.
+     */
+    debtScore(at = this.now()) {
+        const now = Date.parse(at);
+        return Math.round(this.debt.reduce((sum, entry) => {
+            const end = entry.resolvedAt ? Date.parse(entry.resolvedAt) : now;
+            return sum + Math.max(0, (end - Date.parse(entry.openedAt)) / 60_000) * entry.weight;
+        }, 0));
+    }
+    openDebt() {
+        return this.debt.filter((entry) => !entry.resolvedAt);
+    }
+    /**
+     * How many requests were granted (feeds the unified ledger snapshot).
+     */
+    grantedCount() {
+        let count = 0;
+        const decisions = [...this.decisions.values()];
+        for (let index = 0; index < decisions.length; index += 1) {
+            const decision = decisions[index];
+            if (decision.decision === "grant") {
+                count += 1;
+            }
+        }
+        return count;
+    }
+    decisionOf(requestId) {
+        return this.decisions.get(requestId);
+    }
+}

package/lib/attention/socialTypes.d.ts

@@ -0,0 +1,102 @@
+/**
+ * AMP v0.1 — social objects (Profile `Social`): other-model | common-ground | attention-request.
+ * Mirrors docs/schemas/social.schema.json.
+ *
+ * Everything about another mind is a hypothesis carrying confidence, not a fact (W-1, INV-11).
+ */
+import type { Confidence, Id, Ref, Timestamp } from "../types/common.js";
+export interface OtherSubject {
+    kind: "human" | "agent";
+    id: Id;
+    label?: string;
+}
+export interface BeliefAscription {
+    slot: Id;
+    /**
+     * 1 = "A believes P" · 2 = "A believes B believes P". Depth above 2 is computed from records, not elicited.
+     */
+    order: 1 | 2 | 3;
+    proposition: string;
+    confidence: Confidence;
+    source: string;
+    volatility: "low" | "medium" | "high";
+    ttl: number;
+}
+export interface GoalAscription {
+    goal: string;
+    priority: number;
+    confidence: Confidence;
+}
+export interface KnowledgeState {
+    known?: Ref[];
+    unknown?: Ref[];
+    uncertain?: Ref[];
+}
+export interface Preference {
+    key: string;
+    value: string;
+    confidence: Confidence;
+    source?: string;
+}
+export interface AttentionState {
+    state: "idle" | "busy" | "interruptible";
+    load?: Confidence;
+    last_interaction?: Timestamp;
+}
+export interface TrustAssessment {
+    domain?: string;
+    level: Confidence;
+    basis?: string;
+}
+export interface Privacy {
+    scope: "turn" | "session" | "task" | "persistent";
+    retention_days?: number;
+    redact?: string[];
+}
+export interface OtherModel {
+    amp: "0.1";
+    kind: "other-model";
+    id: Id;
+    subject: OtherSubject;
+    beliefs: BeliefAscription[];
+    goals?: GoalAscription[];
+    knowledge?: KnowledgeState;
+    preferences?: Preference[];
+    attention?: AttentionState;
+    trust?: TrustAssessment;
+    common_ground?: Ref[];
+    privacy: Privacy;
+    confidence: Confidence;
+    updated: Timestamp;
+}
+export interface CommonGround {
+    amp: "0.1";
+    kind: "common-ground";
+    id: Id;
+    proposition: string;
+    /**
+     * Only the first four actually establish common ground.
+     */
+    established_by: "assertion" | "confirmation" | "repair" | "shared_observation" | "assumption";
+    participants: Ref[];
+    confidence: Confidence;
+    established_at: Timestamp;
+}
+export type InterruptClass = "safety" | "commitment" | "opportunity" | "curiosity";
+export interface AttentionRequest {
+    amp: "0.1";
+    kind: "attention-request";
+    id: Id;
+    from: Ref;
+    to: Ref;
+    target: Ref;
+    class: InterruptClass;
+    urgency: 1 | 2 | 3 | 4 | 5;
+    why_now: string;
+    if_ignored: string;
+    cost: import("../types/common.js").Budget;
+    expected_value?: Confidence;
+    expires?: Timestamp;
+    fallback: "queue" | "drop" | "escalate";
+}
+export type SocialObject = OtherModel | CommonGround | AttentionRequest;

package/lib/attention/socialTypes.js

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

package/lib/authz/authz.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Capability-based authorization.
+ *
+ * A logical process has no MMU, so isolation is a policy decision: by default a
+ * subject may touch only its own resources, and any cross-subject access needs a
+ * live capability row. Capabilities are attenuating (rights and expiry can only
+ * shrink), recursive (revoking a parent revokes its grants) and auditable (every
+ * grant/revoke appends an event to the object chain).
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Id } from "../types/common.js";
+export type SubjectKind = "host" | "process" | "thread";
+export interface Subject {
+    kind: SubjectKind;
+    id: Id;
+    pid?: number;
+    tid?: number;
+}
+export type PermissionAction = "read" | "write" | "append" | "grant" | "revoke" | "spawn" | "kill" | "send" | "receive" | "fork" | "join";
+/**
+ * @deprecated Use `PermissionAction`; `Action` is reserved for the runtime's
+ * goal-directed intent (see `src/runtime/action.ts`).
+ */
+export type Action = PermissionAction;
+export type ResourceKind = "object" | "process" | "thread" | "mailbox" | "budget";
+export interface Resource {
+    kind: ResourceKind;
+    id: Id;
+    /**
+     * The process that owns the resource; omitted for kernel/global objects.
+     */
+    ownerPid?: number;
+}
+export interface CapabilityRecord {
+    hid: number;
+    id: Id;
+    subject: Subject;
+    resource: Resource;
+    rights: Action[];
+    scope: "process" | "thread" | "shared";
+    parentHid?: number;
+    expiresAt?: string;
+    revokedAt?: string;
+    grantedBy?: Id;
+    createdAt: string;
+}
+export interface GrantInput {
+    grantor: Subject;
+    grantee: Subject;
+    resource: Resource;
+    rights: Action[];
+    scope?: "process" | "thread" | "shared";
+    expiresAt?: string;
+}
+/**
+ * Rights the subject actually holds on the resource, including ownership.
+ */
+export declare const effectiveRights: (db: DatabaseSync, subject: Subject, resource: Resource, at: string) => Action[];
+export declare const can: (db: DatabaseSync, subject: Subject, action: Action, resource: Resource, at: string) => boolean;
+/**
+ * Throws unless the subject holds `action` on `resource`.
+ */
+export declare const requirePermission: (db: DatabaseSync, subject: Subject, action: Action, resource: Resource, at: string) => void;
+export declare const listCapabilities: (db: DatabaseSync, subject: Subject) => CapabilityRecord[];
+/**
+ * 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 declare const grant: (db: DatabaseSync, input: GrantInput, at: string) => CapabilityRecord;
+/**
+ * Revoke a capability and every grant derived from it.
+ */
+export declare const revoke: (db: DatabaseSync, subject: Subject, hid: number, at: string) => number;