attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/window/window.js

@@ -0,0 +1,194 @@
+import { WindowError } from "../error/windowError.js";
+import { LRUUnorderedMap } from "../structure/lru.js";
+import { UnorderedMap } from "../structure/unordered.js";
+import { pageIdFor, pageKey } from "./page.js";
+export class ContextWindow {
+    capacityTokens;
+    maxPages;
+    resident;
+    table;
+    now;
+    objects;
+    used = 0;
+    hits = 0;
+    faults = 0;
+    evictions = 0;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.capacityTokens) || options.capacityTokens <= 0) {
+            throw new RangeError("capacityTokens must be a positive safe integer");
+        }
+        this.capacityTokens = options.capacityTokens;
+        this.maxPages = options.maxPages ?? 128;
+        this.resident = new LRUUnorderedMap(this.maxPages);
+        this.table = new UnorderedMap();
+        this.now = options.now ?? (() => Date.now());
+        if (options.objects !== (void 0)) {
+            this.objects = options.objects;
+        }
+    }
+    has(kind, id) {
+        return this.table.has(pageKey(kind, id));
+    }
+    /**
+     * Load a page into the resident set, evicting unpinned pages if needed.
+     */
+    fault(kind, id, tokens, content) {
+        if (!Number.isSafeInteger(tokens) || tokens <= 0) {
+            throw new RangeError("tokens must be a positive safe integer");
+        }
+        const key = pageKey(kind, id);
+        const existingId = this.table.get(key);
+        if (existingId !== (void 0)) {
+            const existing = this.resident.get(existingId);
+            if (existing !== (void 0)) {
+                this.hits += 1;
+                return existing;
+            }
+            this.table.delete(key);
+        }
+        if (tokens > this.capacityTokens) {
+            throw new WindowError("window_full", [`${key} needs ${tokens} tokens, window holds ${this.capacityTokens}`]);
+        }
+        this.evictUntil(tokens);
+        const page = {
+            id: pageIdFor(kind, id),
+            objectKind: kind,
+            objectId: id,
+            tokens,
+            pinned: 0,
+            lastUsed: this.now(),
+        };
+        const loaded = content ?? this.load(kind, id);
+        if (loaded !== (void 0)) {
+            page.content = loaded;
+        }
+        this.resident.set(page.id, page);
+        this.table.set(key, page.id);
+        this.used += tokens;
+        this.faults += 1;
+        return page;
+    }
+    /**
+     * Pin a page so eviction cannot remove it; returns the new pin count.
+     */
+    pin(kind, id) {
+        const page = this.pageOf(kind, id);
+        if (page === (void 0)) {
+            throw new WindowError("unknown_page", [pageKey(kind, id)]);
+        }
+        page.pinned += 1;
+        return page.pinned;
+    }
+    unpin(kind, id) {
+        const page = this.pageOf(kind, id);
+        if (page === (void 0)) {
+            throw new WindowError("unknown_page", [pageKey(kind, id)]);
+        }
+        page.pinned = Math.max(0, page.pinned - 1);
+        return page.pinned;
+    }
+    /**
+     * Remove a page regardless of pin count (explicit release, not eviction).
+     */
+    release(kind, id) {
+        const key = pageKey(kind, id);
+        const pageId = this.table.get(key);
+        if (pageId === (void 0)) {
+            return false;
+        }
+        const page = this.resident.get(pageId);
+        if (page !== (void 0)) {
+            this.used -= page.tokens;
+        }
+        this.resident.delete(pageId);
+        this.table.delete(key);
+        return true;
+    }
+    pageOf(kind, id) {
+        const pageId = this.table.get(pageKey(kind, id));
+        return pageId === (void 0) ? undefined : this.resident.get(pageId);
+    }
+    entries() {
+        return [...this.resident.values()];
+    }
+    snapshot() {
+        return this.entries().map((page) => ({
+            pageId: page.id,
+            objectKind: page.objectKind,
+            objectId: page.objectId,
+            tokens: page.tokens,
+            pinned: page.pinned > 0,
+            lastUsed: page.lastUsed,
+        }));
+    }
+    restore(pages) {
+        this.resident.clear();
+        this.table.clear();
+        this.used = 0;
+        for (const page of pages) {
+            const restored = {
+                id: page.pageId,
+                objectKind: page.objectKind,
+                objectId: page.objectId,
+                tokens: page.tokens,
+                pinned: page.pinned ? 1 : 0,
+                lastUsed: page.lastUsed,
+            };
+            this.resident.set(restored.id, restored);
+            this.table.set(pageKey(page.objectKind, page.objectId), restored.id);
+            this.used += restored.tokens;
+        }
+    }
+    get usedTokens() {
+        return this.used;
+    }
+    stats() {
+        return {
+            hits: this.hits,
+            faults: this.faults,
+            evictions: this.evictions,
+            usedTokens: this.used,
+            capacityTokens: this.capacityTokens,
+            pages: this.resident.size,
+        };
+    }
+    evictUntil(incoming) {
+        while (this.used + incoming > this.capacityTokens || this.resident.size >= this.maxPages) {
+            const victim = this.leastRecentUnpinned();
+            if (victim === (void 0)) {
+                throw new WindowError("window_full", [`no unpinned page can make room for ${incoming} tokens`]);
+            }
+            this.used -= victim.tokens;
+            this.resident.delete(victim.id);
+            this.table.delete(pageKey(victim.objectKind, victim.objectId));
+            this.evictions += 1;
+        }
+    }
+    leastRecentUnpinned() {
+        let victim;
+        for (const page of this.resident.values()) {
+            if (page.pinned > 0) {
+                continue;
+            }
+            if (victim === (void 0) || page.lastUsed < victim.lastUsed) {
+                victim = page;
+            }
+        }
+        return victim;
+    }
+    load(kind, id) {
+        if (this.objects === (void 0)) {
+            return undefined;
+        }
+        const row = this.objects.find(kind, id);
+        if (row === (void 0)) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(row.body);
+        }
+        catch {
+            return row.body;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attention-manifest-protocol",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "description": "A metacognitive protocol for agent attention and warrant: signed manifests, attention frames with explicit exclusions, receipts, T0-T4 evidence tiers, MCP execution, federation, persistence, agent governance (manifests, credentials, budgets, workflows) and multi-agent delegation.",
   "keywords": [
@@ -17,13 +17,34 @@
   "license": "Apache-2.0",
   "author": "Eloy Kim",
   "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./schemas/*": "./docs/schemas/*",
+    "./*.js": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    },
+    "./*": {
+      "types": "./lib/*/index.d.ts",
+      "default": "./lib/*/index.js"
+    }
+  },
   "engines": {
     "node": ">=24"
   },
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
+    "build:lib": "tsc -p tsconfig.build.json && node tools/rewrite-declaration-extensions.ts",
+    "prebuild:lib": "node -e \"require('node:fs').rmSync('lib', { recursive: true, force: true })\"",
     "preview": "vite preview",
+    "prepublishOnly": "npm run build:lib",
     "verify": "node tools/validate.ts && node tools/conformance.ts && node tools/runtime-check.ts && node tools/exec-check.ts && node tools/policy-check.ts && node tools/checkpoint-check.ts && node tools/envelope-check.ts && node tools/keys-check.ts && node tools/pin-check.ts && node tools/guard-check.ts && node tools/interrupts-check.ts && node tools/conformance-runtime.ts && node tools/linear-structure-check.ts && node tools/tree-structure-check.ts && node tools/segment-ast-check.ts && node tools/structure-compare-check.ts && node tools/filter-check.ts && node tools/lru-check.ts && node tools/priority-check.ts && node tools/boundary-check.ts && node tools/concurrency-check.ts && node tools/authz-check.ts && node tools/platform-check.ts && node tools/evidence-revalidation-check.ts && node tools/ipc-check.ts && node tools/registry-check.ts && node tools/agent-check.ts && node tools/agent-store-check.ts && node tools/attention-resource-check.ts && node tools/scenario-check.ts && node tools/interaction-check.ts && node tools/bayes-check.ts && node tools/calibration-check.ts && node tools/calibration-registry-check.ts && node tools/reliability-check.ts && node tools/scoped-priors-check.ts && node tools/scoped-priors-pooling.ts && node tools/calibration-sim.ts && node tools/agreement-check.ts && node tools/label-audit.ts && node tools/annotation-status.ts && node tools/annotation-server-check.ts && node tools/calibrate-imported.ts && node tools/labels-workflow-check.ts && node tools/behavior-tuning-check.ts && node tools/diagnosis-check.ts && node tools/context-ast-check.ts && node tools/context-index-check.ts && node tools/context-storage-check.ts && node tools/context-graph-check.ts && node tools/context-projection-check.ts && node tools/context-lifecycle-check.ts && node tools/context-scope-check.ts && node tools/workspace-context-check.ts && node tools/workspace-agent-check.ts && node tools/document-context-check.ts && node tools/tex-context-check.ts && node tools/diagnosis-router-check.ts && node tools/cognitive-runtime-check.ts && node tools/deepseek-llm-check.ts && node tools/kernel-async-check.ts && node tools/kernel-runtime-check.ts && node tools/approval-access-check.ts && node tools/mcp-executor-check.ts && node tools/outbox-check.ts && node tools/session-store-check.ts && node tools/turn-store-check.ts && node tools/runtime-eval.ts && node tools/telemetry-check.ts && node tools/eval-replay.ts && node tools/eval-recorded-replay.ts && node tools/eval-summary.ts && node tools/arch-check.ts && node tools/inquiry-check.ts && node tools/sign-check.ts && node tools/social-check.ts && node tools/federation-check.ts && node tools/persistence-check.ts && node tools/team-check.ts && node tools/merge-check.ts && node tools/authority-check.ts && node tools/board-check.ts && node tools/unified-check.ts && node tools/compaction-check.ts && node tools/concept-check.ts && node tools/share-check.ts && node tools/metrics-check.ts && node tools/session-check.ts && node tools/wire-check.ts && node tools/channel-check.ts && node tools/http-channel-check.ts && node tools/retry-check.ts && node tools/a2a-check.ts && node tools/agent-card-check.ts && node tools/a2a-flow-check.ts && node tools/card-sign-check.ts && node tools/card-trust-check.ts && node tools/bundle-trust-check.ts && node tools/trust-flow-check.ts && node tools/scenario-incident.ts && node tools/cognition-check.ts && node tools/governance-check.ts && node tools/governed-task-check.ts && node tools/cooperation-check.ts && node tools/audit-check.ts && node tools/signing-check.ts && node tools/tool-gate-check.ts && node tools/cooperation-http-check.ts && node tools/governance-store-check.ts && node node_modules/typescript/bin/tsc --noEmit && node node_modules/typescript/bin/tsc -p tsconfig.tools.json",
     "typecheck": "tsc --noEmit",
     "typecheck:tools": "tsc -p tsconfig.tools.json",

package/src/authz/index.ts

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

package/src/concept/index.ts

@@ -0,0 +1,3 @@
+export * from "./concept.ts";
+export * from "./conceptBudget.ts";
+export * from "./conceptBudgetTypes.ts";

package/src/concurrency/index.ts

@@ -0,0 +1,5 @@
+export * from "./idempotency.ts";
+export * from "./mutex.ts";
+export * from "./namedLocks.ts";
+export * from "./retry.ts";
+export * from "./worker.ts";

package/src/cooperation/index.ts

@@ -0,0 +1,6 @@
+export * from "./board.ts";
+export * from "./collaboration.ts";
+export * from "./merge.ts";
+export * from "./metrics.ts";
+export * from "./session.ts";
+export * from "./unified.ts";

package/src/delegate/index.ts

@@ -0,0 +1,2 @@
+export * from "./team.ts";
+export * from "./teamTypes.ts";

package/src/error/index.ts

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

package/src/evaluation/index.ts

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

package/src/execution/index.ts

@@ -0,0 +1,3 @@
+export * from "./exec.ts";
+export * from "./handles.ts";
+export * from "./pin.ts";

package/src/frame/index.ts

@@ -0,0 +1 @@
+export * from "./frame.ts";

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Root entry: the documented protocol surfaces. Other modules are available as
+ * subpaths, for example `attention-manifest-protocol/governance`.
+ */
+export * from "./attention/index.ts";
+export * from "./context/index.ts";
+export * from "./frame/index.ts";
+export * from "./ledger/index.ts";
+export * from "./manifest/index.ts";
+export * from "./receipt/index.ts";
+export * from "./warrant/index.ts";

package/src/ledger/index.ts

@@ -0,0 +1,4 @@
+export * from "./checkpoint.ts";
+export * from "./ledger.ts";
+export * from "./persistence.ts";
+export * from "./share.ts";

package/src/manifest/index.ts

@@ -0,0 +1,8 @@
+export * from "./agentCard.ts";
+export * from "./cardSign.ts";
+export * from "./federation.ts";
+export * from "./federationTypes.ts";
+export * from "./keys.ts";
+export * from "./manifest.ts";
+export * from "./sign.ts";
+export * from "./trust.ts";

package/src/policy/index.ts

@@ -0,0 +1,2 @@
+export * from "./guard.ts";
+export * from "./policy.ts";

package/src/protocol/index.ts

@@ -0,0 +1,6 @@
+export * from "./a2a.ts";
+export * from "./channel.ts";
+export * from "./envelope.ts";
+export * from "./httpChannel.ts";
+export * from "./protocol.ts";
+export * from "./wire.ts";

package/src/receipt/index.ts

@@ -0,0 +1 @@
+export * from "./receipt.ts";

package/src/semantic/index.ts

@@ -0,0 +1,2 @@
+export * from "./canonical.ts";
+export * from "./sha256.ts";

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export * from "./appendLog.ts";
+export * from "./fileAppendSink.ts";

package/src/structure/index.ts

@@ -0,0 +1,20 @@
+export * from "./abstractSyntaxTree.ts";
+export * from "./avlTree.ts";
+export * from "./binarySearchTree.ts";
+export * from "./binaryTree.ts";
+export * from "./bloomFilter.ts";
+export * from "./compare.ts";
+export * from "./cuckooFilter.ts";
+export * from "./deque.ts";
+export * from "./filterKey.ts";
+export * from "./hash.ts";
+export * from "./heap.ts";
+export * from "./iterator.ts";
+export * from "./lru.ts";
+export * from "./ordered.ts";
+export * from "./priority.ts";
+export * from "./queue.ts";
+export * from "./redBlackTree.ts";
+export * from "./segmentTree.ts";
+export * from "./stack.ts";
+export * from "./unordered.ts";

package/src/thread/index.ts

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

package/src/warrant/index.ts

@@ -0,0 +1,3 @@
+export * from "./epistemic.ts";
+export * from "./inquiry.ts";
+export * from "./warrant.ts";

package/src/window/index.ts

@@ -1,4 +1,7 @@
-export { ContextWindow } from "./window.ts";
-export type { ContextWindowOptions, WindowStats } from "./window.ts";
-export type { Page } from "./page.ts";
-export { pageIdFor, pageKey } from "./page.ts";
+export { ContextWindow } from "./window.ts";
+export type { ContextWindowOptions, WindowStats } from "./window.ts";
+export type { Page } from "./page.ts";
+export { pageIdFor, pageKey } from "./page.ts";
+export { CompactionRefused, compactLedger, planPrune, verifyCompaction } from "./compaction.ts";
+export type { Compaction, CompactionOptions, PruneResult } from "./compaction.ts";
+export type { Checkpoint, LedgerKind, PruneDecision, PrunePlan, PrunePolicy, PruneReason } from "./compactionTypes.ts";

package/tools/rewrite-declaration-extensions.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Rewrite TypeScript extensions in emitted declarations to JavaScript ones.
+ *
+ * `tsc` rewrites relative `.ts` specifiers when it emits `.js`, but leaves them
+ * untouched in `.d.ts`. A published declaration importing `./frame.ts` would
+ * therefore point at a file that only exists as `./frame.js`, so consumers
+ * would fail to resolve the types.
+ */
+import { existsSync } from "node:fs";
+import type { Dirent } from "node:fs";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Declaration root produced by `tsconfig.build.json`.
+ */
+const Root: string = path.resolve(import.meta.dirname, "..", "lib");
+
+/**
+ * Relative specifier ending in a TypeScript extension, quoted either way.
+ */
+const Specifier: RegExp = /(["'])(\.{1,2}\/[^"']*?)\.(ts|tsx|mts|cts)\1/g;
+
+/**
+ * Emitted JavaScript extension for each TypeScript extension.
+ */
+const Emitted: Record<string, string> = { ts: ".js", tsx: ".jsx", mts: ".mjs", cts: ".cjs" };
+
+/**
+ * Declaration files discovered under {@link Root}.
+ */
+const Declarations: string[] = [];
+
+/**
+ * Collect `.d.ts` files under one directory tree.
+ *
+ * @param directory Absolute directory to walk.
+ */
+const collect: (directory: string) => Promise<void> = async (directory: string): Promise<void> => {
+    const entries: Dirent[] = await readdir(directory, { withFileTypes: true });
+    for (let index: number = 0; index < entries.length; index += 1) {
+        const entry: Dirent = entries[index];
+        const full: string = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            await collect(full);
+        } else if (entry.name.endsWith(".d.ts")) {
+            Declarations.push(full);
+        }
+    }
+};
+
+/**
+ * Replace TypeScript specifier extensions inside one declaration file.
+ *
+ * @param file Absolute path to a declaration file.
+ * @returns Whether the file changed.
+ */
+const rewrite: (file: string) => Promise<boolean> = async (file: string): Promise<boolean> => {
+    const before: string = await readFile(file, "utf8");
+    const after: string = before.replace(
+        Specifier,
+        (match: string, quote: string, base: string, extension: string): string => `${quote}${base}${Emitted[extension]}${quote}`,
+    );
+    if (after === before) {
+        return false;
+    }
+    await writeFile(file, after, "utf8");
+    return true;
+};
+
+if (!existsSync(Root)) {
+    throw new Error(`missing declaration output: ${Root} (run tsc -p tsconfig.build.json first)`);
+}
+
+await collect(Root);
+
+let Rewrites: number = 0;
+for (let index: number = 0; index < Declarations.length; index += 1) {
+    if (await rewrite(Declarations[index])) {
+        Rewrites += 1;
+    }
+}
+
+const Leftovers: string[] = [];
+for (let index: number = 0; index < Declarations.length; index += 1) {
+    const file: string = Declarations[index];
+    if (Specifier.test(await readFile(file, "utf8"))) {
+        Leftovers.push(file);
+    }
+    Specifier.lastIndex = 0;
+}
+
+if (Leftovers.length > 0) {
+    throw new Error(`declarations still reference TypeScript extensions: ${Leftovers.join(", ")}`);
+}
+
+console.log(`rewrote ${Rewrites} of ${Declarations.length} declaration files under ${path.relative(process.cwd(), Root)}`);

package/tsconfig.build.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "outDir": "lib",
+    "rootDir": "src",
+    "rewriteRelativeImportExtensions": true
+  },
+  "include": ["src"],
+  "exclude": ["src/main.ts", "src/counter.ts", "src/style.css"]
+}