attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/unordered.js

@@ -0,0 +1,341 @@
+/**
+ * Unordered hash set and map.
+ *
+ * Both containers are separate-chaining hash tables over a power-of-two bucket
+ * array, with a load factor of 0.75 and rehash-on-grow. The bucket index is
+ * taken from the low bits of a 64-bit hash from `./hash.ts`; collisions are
+ * walked as explicit chains and resolved with the equality strategy (never by
+ * hash equality alone). No insertion order is maintained: iteration order is
+ * unspecified bucket order and may change after a resize.
+ *
+ * Iteration is deliberately fail-fast: any structural mutation after an
+ * iterator is created (`add` of a new value, `set` of a new key, `delete`, or
+ * `clear`) makes the iterator throw on its next `next()` call, as does a
+ * rehash. Updating the value of an existing map key is not structural and does
+ * not invalidate iterators.
+ */
+import { HashMask, hashKey, sameKey } from "./hash.js";
+const InitialCapacity = 16;
+/**
+ * A clear, uniform error for the fail-fast iteration contract.
+ */
+const concurrentModification = (label) => {
+    return new Error(`${label}: collection was mutated during iteration`);
+};
+/**
+ * Shared power-of-two, separate-chaining table behind both public classes.
+ */
+class HashTable {
+    buckets = new Array(InitialCapacity).fill(null);
+    indexMask = BigInt(InitialCapacity - 1);
+    hashFn;
+    equalsFn;
+    label;
+    count = 0;
+    version = 0;
+    constructor(label, options) {
+        this.label = label;
+        this.hashFn = options?.hash ?? hashKey;
+        this.equalsFn = options?.equals ?? sameKey;
+    }
+    get size() {
+        return this.count;
+    }
+    hashOf(key) {
+        return this.hashFn(key) & HashMask;
+    }
+    /**
+     * Find a node, the node before it in its chain, and its bucket index.
+     */
+    find(key, hash) {
+        const index = Number(hash & this.indexMask);
+        let previous = null;
+        let node = this.buckets[index];
+        while (node !== null) {
+            if (this.equalsFn(key, node.key)) {
+                return { node, previous, index };
+            }
+            previous = node;
+            node = node.next;
+        }
+        return null;
+    }
+    has(key) {
+        return this.find(key, this.hashOf(key)) !== null;
+    }
+    get(key) {
+        const hit = this.find(key, this.hashOf(key));
+        return hit === null ? undefined : hit.node.value;
+    }
+    /**
+     * Add a key that must not exist yet; returns whether a node was created.
+     */
+    add(key, value) {
+        const hash = this.hashOf(key);
+        if (this.find(key, hash) !== null) {
+            return false;
+        }
+        this.insert(key, value, hash);
+        return true;
+    }
+    /**
+     * Insert or update; returns whether a node was created.
+     */
+    set(key, value) {
+        const hash = this.hashOf(key);
+        const hit = this.find(key, hash);
+        if (hit !== null) {
+            hit.node.value = value;
+            return false;
+        }
+        this.insert(key, value, hash);
+        return true;
+    }
+    insert(key, value, hash) {
+        if (this.count + 1 > (this.buckets.length * 3) / 4) {
+            this.grow();
+        }
+        const index = Number(hash & this.indexMask);
+        const node = { key, value, hash, next: this.buckets[index] };
+        this.buckets[index] = node;
+        this.count += 1;
+        this.version += 1;
+    }
+    /**
+     * Double the bucket array and relink every live node exactly once.
+     */
+    grow() {
+        const previousBuckets = this.buckets;
+        const nextBuckets = new Array(previousBuckets.length * 2).fill(null);
+        const nextMask = BigInt(nextBuckets.length - 1);
+        for (let headIndex = 0; headIndex < previousBuckets.length; headIndex += 1) {
+            let node = previousBuckets[headIndex];
+            while (node !== null) {
+                const next = node.next;
+                const index = Number(node.hash & nextMask);
+                node.next = nextBuckets[index];
+                nextBuckets[index] = node;
+                node = next;
+            }
+        }
+        this.buckets = nextBuckets;
+        this.indexMask = nextMask;
+    }
+    delete(key) {
+        const hit = this.find(key, this.hashOf(key));
+        if (hit === null) {
+            return false;
+        }
+        const { node, previous, index } = hit;
+        if (previous === null) {
+            this.buckets[index] = node.next;
+        }
+        else {
+            previous.next = node.next;
+        }
+        node.next = null;
+        this.count -= 1;
+        this.version += 1;
+        return true;
+    }
+    clear() {
+        if (this.count === 0) {
+            return;
+        }
+        this.buckets = new Array(InitialCapacity).fill(null);
+        this.indexMask = BigInt(InitialCapacity - 1);
+        this.count = 0;
+        this.version += 1;
+    }
+    /**
+     * Build a fail-fast iterator. The expected version is captured here, when
+     * the iterator is requested, not on the first `next()` call.
+     */
+    *iterate(expectedVersion, select) {
+        for (let index = 0; index < this.buckets.length; index += 1) {
+            let node = this.buckets[index];
+            while (node !== null) {
+                if (expectedVersion !== this.version) {
+                    throw concurrentModification(this.label);
+                }
+                const value = select(node);
+                yield value;
+                if (expectedVersion !== this.version) {
+                    throw concurrentModification(this.label);
+                }
+                node = node.next;
+            }
+        }
+    }
+    keys() {
+        return this.iterate(this.version, (node) => node.key);
+    }
+    values() {
+        return this.iterate(this.version, (node) => node.value);
+    }
+    entries() {
+        return this.iterate(this.version, (node) => [node.key, node.value]);
+    }
+    /**
+     * Entries for a set, where the stored value is irrelevant.
+     */
+    keyPairs() {
+        return this.iterate(this.version, (node) => [node.key, node.key]);
+    }
+}
+/**
+ * An unordered set backed by a separate-chaining hash table.
+ *
+ * Average O(1) membership, explicit collision chains, power-of-two buckets, a
+ * 0.75 load factor, and rehash-on-grow. Iteration order is unspecified (bucket
+ * order) and may change after a resize. The public API mirrors
+ * `OrderedSet`, including custom {@link KeyStrategy} support.
+ *
+ * Iteration is fail-fast: a structural mutation (`add` of a new value,
+ * `delete`, `clear`, or an internal rehash caused by growth) after an iterator
+ * is obtained makes that iterator throw on its next step. Mutating the set
+ * during `forEach` therefore also throws once the callback returns and the
+ * loop advances.
+ */
+export class UnorderedSet {
+    table;
+    constructor(values, options) {
+        this.table = new HashTable("UnorderedSet", options);
+        if (values === (void 0)) {
+            return;
+        }
+        const initialValues = [...values];
+        for (let valueIndex = 0; valueIndex < initialValues.length; valueIndex += 1) {
+            this.table.add(initialValues[valueIndex], undefined);
+        }
+    }
+    get size() {
+        return this.table.size;
+    }
+    clear() {
+        this.table.clear();
+    }
+    add(value) {
+        this.table.add(value, undefined);
+        return this;
+    }
+    has(value) {
+        return this.table.has(value);
+    }
+    delete(value) {
+        return this.table.delete(value);
+    }
+    /**
+     * Alias of {@link UnorderedSet.values}.
+     */
+    keys() {
+        return this.table.keys();
+    }
+    values() {
+        return this.table.keys();
+    }
+    entries() {
+        return this.table.keyPairs();
+    }
+    [Symbol.iterator]() {
+        return this.table.keys();
+    }
+    /**
+     * Call `callback` for each value; order is unspecified.
+     *
+     * The table generator is driven by hand so that the fail-fast version check
+     * keeps throwing between callback invocations, exactly as a `for…of` loop
+     * over `keys()` would.
+     *
+     * @param callback - Receives the value twice (matching the native `Set`
+     * shape) and the set itself.
+     * @param thisArg - Value used as `this` when invoking `callback`.
+     */
+    forEach(callback, thisArg) {
+        const iterator = this.table.keys();
+        let step = iterator.next();
+        while (!step.done) {
+            callback.call(thisArg, step.value, step.value, this);
+            step = iterator.next();
+        }
+    }
+}
+/**
+ * An unordered map backed by a separate-chaining hash table.
+ *
+ * Average O(1) lookup, explicit collision chains, power-of-two buckets, a 0.75
+ * load factor, and rehash-on-grow. Iteration order is unspecified (bucket
+ * order) and may change after a resize. The public API mirrors `OrderedMap`,
+ * including custom {@link KeyStrategy} support. Membership is determined by
+ * {@link UnorderedMap.has}, so `undefined` is a perfectly valid value.
+ *
+ * Iteration is fail-fast: a structural mutation (`set` of a new key, `delete`,
+ * `clear`, or an internal rehash caused by growth) after an iterator is
+ * obtained makes that iterator throw on its next step; updating an existing
+ * key's value is allowed. Mutating the key set during `forEach` also throws
+ * once the callback returns and the loop advances.
+ */
+export class UnorderedMap {
+    table;
+    constructor(entries, options) {
+        this.table = new HashTable("UnorderedMap", options);
+        if (entries === (void 0)) {
+            return;
+        }
+        const initialEntries = [...entries];
+        for (let entryIndex = 0; entryIndex < initialEntries.length; entryIndex += 1) {
+            const [key, value] = initialEntries[entryIndex];
+            this.table.set(key, value);
+        }
+    }
+    get size() {
+        return this.table.size;
+    }
+    clear() {
+        this.table.clear();
+    }
+    set(key, value) {
+        this.table.set(key, value);
+        return this;
+    }
+    get(key) {
+        return this.table.get(key);
+    }
+    has(key) {
+        return this.table.has(key);
+    }
+    delete(key) {
+        return this.table.delete(key);
+    }
+    keys() {
+        return this.table.keys();
+    }
+    values() {
+        return this.table.values();
+    }
+    entries() {
+        return this.table.entries();
+    }
+    [Symbol.iterator]() {
+        return this.table.entries();
+    }
+    /**
+     * Call `callback` for each entry; order is unspecified.
+     *
+     * The table generator is driven by hand so that the fail-fast version check
+     * keeps throwing between callback invocations, exactly as a `for…of` loop
+     * over `entries()` would.
+     *
+     * @param callback - Receives the value, the key, and the map itself.
+     * @param thisArg - Value used as `this` when invoking `callback`.
+     */
+    forEach(callback, thisArg) {
+        const iterator = this.table.entries();
+        let step = iterator.next();
+        while (!step.done) {
+            const [key, value] = step.value;
+            callback.call(thisArg, value, key, this);
+            step = iterator.next();
+        }
+    }
+}

package/lib/thread/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./thread.js";
+export * from "./transitions.js";

package/lib/thread/index.js

@@ -0,0 +1,2 @@
+export * from "./thread.js";
+export * from "./transitions.js";

package/lib/thread/thread.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Thread: one task (or goal) that an agent is executing.
+ *
+ * The agent is the process; a thread is the unit of work the CPU-like scheduler
+ * runs. Multiple tasks may be ready for the same agent, but at most one may be
+ * `running` at a time (a partial unique index enforces it): an agent does one
+ * thing at a time, and switches by scheduling another thread.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Budget, Criterion, Id, Usage } from "../types/common.js";
+export { canThreadTransition } from "./transitions.js";
+export type ThreadState = "ready" | "running" | "blocked" | "done" | "failed" | "abandoned";
+export interface ThreadSpec {
+    /**
+     * Defaults to `t.<pid>.<n>`; must satisfy the AMP id grammar.
+     */
+    id?: Id;
+    pid: number;
+    /**
+     * Goal this task serves.
+     */
+    goal: Id;
+    statement: string;
+    /**
+     * At least one observable completion criterion.
+     */
+    success: Criterion[];
+    priority?: number;
+    budget?: Budget;
+    quantumMs?: number;
+}
+export interface ThreadRecord {
+    tid: number;
+    id: Id;
+    pid: number;
+    goal: Id;
+    statement: string;
+    success: Criterion[];
+    state: ThreadState;
+    priority: number;
+    quantumMs: number;
+    sliceUsedMs: number;
+    budget: Budget;
+    used: Usage;
+    blockedOn?: string;
+    wakeAt?: string;
+    createdAt: string;
+    finishedAt?: string;
+    exitNote?: string;
+    ownerWorker?: string;
+    lease: number;
+    version: number;
+}
+export interface ThreadPatch {
+    blockedOn?: string | null;
+    wakeAt?: string | null;
+    sliceUsedMs?: number;
+    finishedAt?: string;
+    exitNote?: string;
+}
+/**
+ * Task lifecycle. `done`, `failed` and `abandoned` are terminal.
+ */
+export declare const getThread: (db: DatabaseSync, tid: number) => ThreadRecord;
+export declare const findThread: (db: DatabaseSync, id: Id) => ThreadRecord | undefined;
+export declare const listThreads: (db: DatabaseSync, pid?: number) => ThreadRecord[];
+export declare const spawnThread: (db: DatabaseSync, spec: ThreadSpec, at: string) => ThreadRecord;
+/**
+ * Oldest highest-priority task whose agent may run it.
+ */
+export declare const nextReadyThread: (db: DatabaseSync) => ThreadRecord | undefined;
+export declare const transitionThread: (db: DatabaseSync, tid: number, from: ThreadState | ThreadState[], to: ThreadState, patch?: ThreadPatch, lease?: number) => ThreadRecord;
+export interface ThreadClaim {
+    tid: number;
+    lease: number;
+    workerId: string;
+}
+/**
+ * Atomically move a ready task to running; the lease is the fencing token.
+ */
+export declare const claimThread: (db: DatabaseSync, tid: number, workerId: string) => ThreadClaim;
+export declare const releaseThread: (db: DatabaseSync, tid: number, workerId: string, lease: number) => boolean;
+/**
+ * Charge the task's own slice. Exhaustion fails the task, not the agent.
+ */
+export declare const chargeThread: (db: DatabaseSync, tid: number, usage: Budget, at: string) => {
+    ok: boolean;
+    exceeded: string[];
+};
+/**
+ * Wake every thread blocked on one condition (mailbox, object, handle).
+ */
+export declare const notifyCondition: (db: DatabaseSync, condition: string) => number;
+/**
+ * Promote sleeping tasks whose `wake_at` has passed.
+ */
+export declare const wakeSleeping: (db: DatabaseSync, at: string) => number;
+/**
+ * Crash recovery: requeue running tasks owned by a dead worker; agents go idle.
+ */
+export declare const recoverThreads: (db: DatabaseSync, workerId?: string) => {
+    threads: number;
+    processes: number;
+};
+export declare const liveThreadCount: (db: DatabaseSync, pid: number) => number;
+export declare const readyThreadCount: (db: DatabaseSync, pid: number) => number;
+export declare const runningThreadCount: (db: DatabaseSync, pid: number) => number;

package/lib/thread/thread.js

@@ -0,0 +1,81 @@
+import { isId } from "../boundary/ids.js";
+import { KernelError } from "../error/kernelError.js";
+import { getProcess } from "../process/process.js";
+import { ExecutionRepository } from "../database/repository/executionRepository.js";
+export { canThreadTransition } from "./transitions.js";
+/**
+ * Task lifecycle. `done`, `failed` and `abandoned` are terminal.
+ */
+export const getThread = (db, tid) => new ExecutionRepository(db).getTask(tid);
+export const findThread = (db, id) => new ExecutionRepository(db).findTaskByExternalId(id);
+export const listThreads = (db, pid) => new ExecutionRepository(db).listTasks(pid);
+export const spawnThread = (db, spec, at) => {
+    const agent = getProcess(db, spec.pid);
+    if (!["created", "idle", "running"].includes(agent.state)) {
+        throw new KernelError("invalid_transition", [`agent ${agent.id} is ${agent.state}`]);
+    }
+    if (!isId(spec.goal)) {
+        throw new KernelError("invalid_thread", [`goal ${spec.goal} is not a valid AMP id`]);
+    }
+    if (spec.statement.trim().length === 0) {
+        throw new KernelError("invalid_thread", ["statement is empty"]);
+    }
+    if (!Array.isArray(spec.success) || spec.success.length === 0) {
+        throw new KernelError("invalid_thread", ["success must contain at least one criterion"]);
+    }
+    for (const criterion of spec.success) {
+        if (!isId(criterion.id) || criterion.statement.trim().length === 0 || criterion.check.trim().length === 0) {
+            throw new KernelError("invalid_thread", [`criterion ${criterion.id} is incomplete`]);
+        }
+    }
+    const repository = new ExecutionRepository(db);
+    const duplicate = repository.findActiveTaskByGoal(spec.pid, spec.goal);
+    if (duplicate !== (void 0)) {
+        throw new KernelError("duplicate_task", [`goal ${spec.goal} already has active task ${duplicate.tid}`]);
+    }
+    const count = repository.countTasks(spec.pid);
+    const id = spec.id ?? `t.${spec.pid}.${count + 1}`;
+    if (!isId(id)) {
+        throw new KernelError("invalid_thread", [`id ${id} is not a valid AMP id`]);
+    }
+    return repository.createTask({
+        id,
+        pid: spec.pid,
+        goal: spec.goal,
+        statement: spec.statement,
+        success: spec.success,
+        priority: spec.priority,
+        quantumMs: spec.quantumMs,
+        budget: spec.budget,
+        at,
+    });
+};
+/**
+ * Oldest highest-priority task whose agent may run it.
+ */
+export const nextReadyThread = (db) => new ExecutionRepository(db).nextReadyTask();
+export const transitionThread = (db, tid, from, to, patch = {}, lease) => new ExecutionRepository(db).transitionTask(tid, from, to, patch, lease);
+/**
+ * Atomically move a ready task to running; the lease is the fencing token.
+ */
+export const claimThread = (db, tid, workerId) => new ExecutionRepository(db).claimTask(tid, workerId);
+export const releaseThread = (db, tid, workerId, lease) => new ExecutionRepository(db).releaseTask(tid, workerId, lease);
+/**
+ * Charge the task's own slice. Exhaustion fails the task, not the agent.
+ */
+export const chargeThread = (db, tid, usage, at) => new ExecutionRepository(db).chargeTask(tid, usage, at);
+/**
+ * Wake every thread blocked on one condition (mailbox, object, handle).
+ */
+export const notifyCondition = (db, condition) => new ExecutionRepository(db).notify(condition);
+/**
+ * Promote sleeping tasks whose `wake_at` has passed.
+ */
+export const wakeSleeping = (db, at) => new ExecutionRepository(db).wake(at);
+/**
+ * Crash recovery: requeue running tasks owned by a dead worker; agents go idle.
+ */
+export const recoverThreads = (db, workerId) => new ExecutionRepository(db).recover(workerId);
+export const liveThreadCount = (db, pid) => new ExecutionRepository(db).liveTaskCount(pid);
+export const readyThreadCount = (db, pid) => new ExecutionRepository(db).readyTaskCount(pid);
+export const runningThreadCount = (db, pid) => new ExecutionRepository(db).runningTaskCount(pid);

package/lib/thread/transitions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure thread lifecycle predicate; no DB or domain implementation imports.
+ */
+import type { ThreadState } from "./thread.js";
+type ThreadTransition = (from: ThreadState, to: ThreadState) => boolean;
+export declare const ThreadEdges: Record<ThreadState, readonly ThreadState[]>;
+export declare const canThreadTransition: ThreadTransition;
+export {};

package/lib/thread/transitions.js

@@ -0,0 +1,9 @@
+export const ThreadEdges = {
+    ready: ["running", "failed", "abandoned"],
+    running: ["ready", "blocked", "done", "failed", "abandoned"],
+    blocked: ["ready", "done", "failed", "abandoned"],
+    done: [],
+    failed: [],
+    abandoned: [],
+};
+export const canThreadTransition = (from, to) => ThreadEdges[from].includes(to);

package/lib/types/common.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AMP v0.1 — common primitives.
+ * Mirrors docs/schemas/common.schema.json.
+ */
+export type Id = string;
+export type Digest = string;
+export type Timestamp = string;
+/**
+ * Process id: in AMP a process is an agent, i.e. a person.
+ */
+export type Pid = number;
+/**
+ * Credence in [0, 1]. For claims this is DERIVED from tier + evidence, never authored.
+ */
+export type Confidence = number;
+/**
+ * Where evidence came from, which caps how far it can promote a claim.
+ */
+export type Trust = "self" | "verified" | "trusted" | "asserted" | "inferred" | "external";
+/**
+ * Epistemic investment tier.
+ * T0 assumed · T1 sourced (entailment) · T2 observed · T3 tested · T4 replicated
+ */
+export type Tier = "T0" | "T1" | "T2" | "T3" | "T4";
+export type RefKind = "entity" | "concept" | "process" | "thread" | "question" | "hypothesis" | "claim" | "evidence" | "goal" | "plan" | "task" | "tool" | "memory" | "other" | "human" | "agent" | "event" | "handle" | "frame" | "self" | "unknown" | "common-ground" | "capability" | "receipt" | "org";
+/**
+ * A pointer, not a copy. The ledger stores ids; content lives wherever it lives.
+ */
+export interface Ref {
+    kind: RefKind;
+    id: Id;
+    label?: string;
+}
+export type ProvenanceKind = "observation" | "testimony" | "inference" | "tool" | "memory" | "document" | "simulation";
+export interface Provenance {
+    source: string;
+    kind?: ProvenanceKind;
+    trust?: Trust;
+    at?: Timestamp;
+    digest?: Digest;
+    note?: string;
+}
+/**
+ * Five-dimension attention budget. Dimensions do not convert into each other.
+ */
+export interface Budget {
+    tokens?: number;
+    ms?: number;
+    calls?: number;
+    interrupts?: number;
+    money?: number;
+}
+export type Usage = Budget;
+export interface Signature {
+    role: "self" | "host" | "registry" | "org" | "tenant";
+    alg: "ed25519";
+    kid: string;
+    sig: string;
+}
+/**
+ * An observable success / abandonment condition. `check` must be executable.
+ */
+export interface Criterion {
+    id: Id;
+    statement: string;
+    check: string;
+    kind?: "observe" | "query" | "assert";
+}
+/**
+ * Opaque reference to an oversized result. Never a capability token.
+ */
+export interface Handle {
+    id: string;
+    kind: "table" | "text" | "tree" | "blob" | "graph";
+    tokens?: number;
+    bytes?: number;
+    preview?: string;
+    scope: "turn" | "session" | "task";
+    ttl_ms?: number;
+}

package/lib/types/common.js

@@ -0,0 +1,5 @@
+/**
+ * AMP v0.1 — common primitives.
+ * Mirrors docs/schemas/common.schema.json.
+ */
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AMP v0.1 — public type surface.
+ *
+ * The shared primitives stay in this directory. Every domain owns its own
+ * schema-mirroring types next to the code that enforces them; this barrel
+ * re-exports the whole surface for hosts and tools that want one import.
+ *
+ * These types mirror docs/schemas/*.schema.json one-to-one.
+ */
+export type * from "./common.js";
+export type * from "../concept/concept.js";
+export type * from "../attention/socialTypes.js";
+export type * from "../cooperation/collaboration.js";
+export type * from "../delegate/teamTypes.js";
+export type * from "../goal/plan.js";
+export type * from "../frame/frame.js";
+export type * from "../window/compactionTypes.js";
+export type * from "../concept/conceptBudgetTypes.js";
+export type * from "../manifest/federationTypes.js";
+export type * from "../manifest/manifest.js";
+export type * from "../protocol/protocol.js";
+export type * from "../receipt/receipt.js";
+export type * from "../warrant/epistemic.js";

package/lib/types/index.js

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