attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/protocol/protocol.d.ts

@@ -0,0 +1,120 @@
+/**
+ * AMP v0.1 — protocol surfaces: message envelope (A-surface) and model verbs (M-surface).
+ * Mirrors docs/schemas/message.schema.json and docs/schemas/verb.schema.json.
+ */
+import type { Budget, Id, Ref, Signature, Tier, Timestamp } from "../types/common.js";
+import type { InterruptClass } from "../attention/socialTypes.js";
+export type Performative = "inform" | "request" | "propose" | "commit" | "decline" | "cancel" | "release";
+/**
+ * Closed error enum. `retryable` is a property of the code, not of the message.
+ */
+export type ErrorCode = "denied" | "unavailable" | "invalid" | "expired" | "conflict" | "budget_exceeded" | "unsupported" | "internal";
+export interface MessagePayload {
+    claim?: Ref;
+    warrant?: Ref;
+    target?: Ref;
+    class?: InterruptClass;
+    why_now?: string;
+    if_ignored?: string;
+    cost?: Budget;
+    proposal?: string;
+    ref?: Ref;
+    request?: Id;
+    reason?: string;
+    code?: ErrorCode;
+    note?: string;
+}
+/**
+ * One envelope, seven performatives. Every field is observable; nothing encodes sincerity.
+ */
+export interface Message {
+    amp: "0.1";
+    kind: "message";
+    id: Id;
+    type: Performative;
+    from: Ref;
+    to: Ref;
+    thread: Id;
+    reply_to?: Id;
+    sent: Timestamp;
+    ttl?: number;
+    payload: MessagePayload;
+    signature?: Signature;
+}
+export type VerbName = "attend" | "plan" | "act" | "ask" | "note" | "reflect" | "read";
+export interface ExpectationCall {
+    observation: string;
+    check: string;
+}
+export interface AttendCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "attend";
+    id?: Id;
+    target: Ref;
+    why: string;
+    budget?: Budget;
+}
+export interface PlanCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "plan";
+    id?: Id;
+    goal: Ref;
+    process?: Ref;
+    mode?: "draft" | "commit";
+}
+export interface ActCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "act";
+    id?: Id;
+    action: string;
+    ref?: Ref;
+    args?: Record<string, unknown>;
+    expect?: ExpectationCall;
+    budget?: Budget;
+}
+export interface AskCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "ask";
+    id?: Id;
+    question: string;
+    to?: Ref;
+    class?: InterruptClass;
+    urgency?: 1 | 2 | 3 | 4 | 5;
+    expires?: Timestamp;
+}
+export interface NoteCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "note";
+    id?: Id;
+    assertion: string;
+    as: "claim" | "hypothesis" | "unknown" | "concept";
+    /**
+     * May be proposed; the Warrant Engine may reject or lower it (W-5).
+     */
+    tier?: Tier;
+    evidence?: Ref[];
+    refutes_if?: string;
+    label?: string;
+}
+export interface ReflectCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "reflect";
+    id?: Id;
+    scope?: "turn" | "task" | "session";
+}
+export interface ReadCall {
+    amp: "0.1";
+    kind: "call";
+    verb: "read";
+    id?: Id;
+    handle: string;
+    cursor: number;
+    limit?: number;
+}
+export type VerbCall = AttendCall | PlanCall | ActCall | AskCall | NoteCall | ReflectCall | ReadCall;

package/lib/protocol/protocol.js

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

package/lib/protocol/wire.d.ts

@@ -0,0 +1,12 @@
+import type { Delegation, Lease } from "../delegate/team.js";
+import type { DelegationDoc, LeaseDoc } from "../cooperation/collaboration.js";
+/**
+ * Wire mapping for collaboration objects.
+ *
+ * The runtime uses camelCase; the wire uses snake_case and stable names because
+ * a delegation crosses domains and must not depend on an implementation's
+ * internal naming. Round-tripping is tested, not assumed.
+ */
+export declare const toDelegationDoc: (delegation: Delegation) => DelegationDoc;
+export declare const fromDelegationDoc: (doc: DelegationDoc) => Delegation;
+export declare const toLeaseDoc: (lease: Lease) => LeaseDoc;

package/lib/protocol/wire.js

@@ -0,0 +1,55 @@
+/**
+ * Wire mapping for collaboration objects.
+ *
+ * The runtime uses camelCase; the wire uses snake_case and stable names because
+ * a delegation crosses domains and must not depend on an implementation's
+ * internal naming. Round-tripping is tested, not assumed.
+ */
+export const toDelegationDoc = (delegation) => {
+    return {
+        amp: "0.1",
+        kind: "delegation",
+        id: delegation.id,
+        parent: delegation.parent,
+        granter: delegation.granter,
+        delegatee: delegation.delegatee,
+        goal_digest: delegation.goalDigest,
+        scope: delegation.scope,
+        budget: delegation.budget,
+        deadline: delegation.deadline,
+        may_redelegate: delegation.mayRedelegate,
+        depth: delegation.depth,
+    };
+};
+export const fromDelegationDoc = (doc) => {
+    const delegation = {
+        id: doc.id,
+        granter: doc.granter,
+        delegatee: doc.delegatee,
+        goalDigest: doc.goal_digest,
+        scope: doc.scope,
+        budget: doc.budget,
+        deadline: doc.deadline,
+        mayRedelegate: doc.may_redelegate,
+        depth: doc.depth,
+    };
+    if (doc.parent !== (void 0)) {
+        delegation.parent = doc.parent;
+    }
+    return delegation;
+};
+export const toLeaseDoc = (lease) => {
+    return {
+        amp: "0.1",
+        kind: "lease",
+        id: lease.id,
+        delegation: lease.delegation,
+        task_id: lease.taskId,
+        holder: lease.holder,
+        fence: lease.fence,
+        goal_digest: lease.goalDigest,
+        budget: lease.budget,
+        deadline: lease.deadline,
+        status: lease.status,
+    };
+};

package/lib/receipt/index.d.ts

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

package/lib/receipt/index.js

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

package/lib/receipt/receipt.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AMP v0.1 — settlement objects: receipt | event.
+ * Mirrors docs/schemas/receipt.schema.json.
+ *
+ * Receipts are the only ground truth for calibration; events are the append-only log.
+ */
+import type { Confidence, Digest, Handle, Id, Ref, Timestamp, Usage } from "../types/common.js";
+export type ReceiptOp = "attend" | "act" | "ask" | "note" | "plan" | "reflect" | "read";
+export type Outcome = "success" | "partial" | "failure" | "blocked";
+export interface Receipt {
+    amp: "0.1";
+    kind: "receipt";
+    id: Id;
+    op: ReceiptOp;
+    target?: Ref;
+    at: Timestamp;
+    ms?: number;
+    usage: Usage;
+    outcome: Outcome;
+    /**
+     * Recorded before the action; compared with realized_voi to calibrate the controller.
+     */
+    predicted_voi?: Confidence;
+    realized_voi?: Confidence;
+    handle?: Handle;
+    note?: string;
+}
+/**
+ * Named AmpEvent to avoid shadowing the DOM `Event`.
+ */
+export interface AmpEvent {
+    amp: "0.1";
+    kind: "event";
+    id: Id;
+    at: Timestamp;
+    actor: Ref;
+    type: string;
+    caused_by?: Id;
+    refs?: Ref[];
+    digest: Digest;
+    payload?: Record<string, unknown>;
+}
+export type SettlementObject = Receipt | AmpEvent;

package/lib/receipt/receipt.js

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

package/lib/registry/content.d.ts

@@ -0,0 +1,10 @@
+export interface ContentEntry {
+    path: string;
+    digest: string;
+}
+export declare const collectDirectory: (root: string) => Promise<ContentEntry[]>;
+/**
+ * Deterministic digest of a directory's current content.
+ */
+export declare const digestDirectory: (root: string) => Promise<string>;
+export declare const diffDirectory: (root: string, expected: readonly ContentEntry[]) => Promise<ContentEntry[]>;

package/lib/registry/content.js

@@ -0,0 +1,58 @@
+/**
+ * Content digest for a module directory.
+ *
+ * A declaration that only records a path proves almost nothing. This module
+ * hashes every file under the directory into a sorted manifest, then hashes the
+ * manifest, so a declaration can bind the actual code. `verifyModuleContent`
+ * recomputes it and reports drift.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { digestOf } from "../semantic/canonical.js";
+import { sha256Hex } from "../semantic/sha256.js";
+const Skip = new Set(["node_modules", ".git", ".tscheck", "dist"]);
+const walk = async (root, current, out) => {
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        if (Skip.has(entry.name)) {
+            continue;
+        }
+        const full = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+            await walk(root, full, out);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const text = await readFile(full, "utf8");
+        out.push({ path: path.relative(root, full).split(path.sep).join("/"), digest: sha256Hex(text) });
+    }
+};
+export const collectDirectory = async (root) => {
+    const entries = [];
+    await walk(root, root, entries);
+    return entries;
+};
+/**
+ * Deterministic digest of a directory's current content.
+ */
+export const digestDirectory = async (root) => {
+    return digestOf(await collectDirectory(root));
+};
+export const diffDirectory = async (root, expected) => {
+    const actual = await collectDirectory(root);
+    const expectedMap = new Map(expected.map((entry) => [entry.path, entry.digest]));
+    const changed = [];
+    for (const entry of actual) {
+        if (expectedMap.get(entry.path) !== entry.digest) {
+            changed.push(entry);
+        }
+        expectedMap.delete(entry.path);
+    }
+    for (const [missingPath, digest] of expectedMap) {
+        changed.push({ path: missingPath, digest });
+    }
+    return changed;
+};

package/lib/registry/index.d.ts

@@ -0,0 +1,4 @@
+export { attest, declareConcept, declareModule, dependencies, hasDependencyCycle, linkConcept, linkDependency, verifyModuleContent, verifyRegistry, } from "./registry.js";
+export type { AttestationResult, ConceptInput, ConceptLinkRole, DeclarationResult, DependencyRow, ModuleInput, ModuleKind, RegistryStatus, } from "./registry.js";
+export { collectDirectory, diffDirectory, digestDirectory } from "./content.js";
+export type { ContentEntry } from "./content.js";

package/lib/registry/index.js

@@ -0,0 +1,2 @@
+export { attest, declareConcept, declareModule, dependencies, hasDependencyCycle, linkConcept, linkDependency, verifyModuleContent, verifyRegistry, } from "./registry.js";
+export { collectDirectory, diffDirectory, digestDirectory } from "./content.js";

package/lib/registry/registry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Registry: concepts and modules as first-class rows.
+ *
+ * A directory existing on disk is not evidence that a module is part of the
+ * architecture. Declaring it writes an immutable `module.<id>.v<n>` object into
+ * the hash chain and updates the current row; the row points at that object, so
+ * "this module exists, at version n, with this description" is checkable.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { ConceptEntity, ModuleEntity } from "../database/entity/registry.js";
+export type RegistryStatus = "proposed" | "active" | "deprecated";
+export type ModuleKind = "kernel" | "database" | "domain" | "protocol" | "module" | "structure" | "tool" | "boundary";
+export type ConceptLinkRole = "owns" | "uses" | "constrains" | "implements";
+export interface ConceptInput {
+    id: string;
+    label: string;
+    definition: string;
+    status?: RegistryStatus;
+}
+export interface ModuleInput {
+    id: string;
+    kind: ModuleKind;
+    entry: string;
+    description: string;
+    status?: RegistryStatus;
+    /**
+     * Digest of the directory content at declaration time; enables drift checks.
+     */
+    contentDigest?: string;
+}
+export interface DeclarationResult<T> {
+    row: T;
+    objectId: string;
+    hash: string;
+}
+/**
+ * Verification outcome shared by the registry checks.
+ */
+type VerifyReport = {
+    ok: boolean;
+    reasons: string[];
+};
+/**
+ * Signature of the concept declarer.
+ */
+type ConceptDeclarer = (db: DatabaseSync, input: ConceptInput, at: string) => DeclarationResult<ConceptEntity>;
+export declare const declareConcept: ConceptDeclarer;
+/**
+ * Signature of the module declarer.
+ */
+type ModuleDeclarer = (db: DatabaseSync, input: ModuleInput, at: string) => DeclarationResult<ModuleEntity>;
+export declare const declareModule: ModuleDeclarer;
+/**
+ * Signature of the concept-to-module linker.
+ */
+type ConceptLinker = (db: DatabaseSync, moduleId: string, conceptId: string, role: ConceptLinkRole) => boolean;
+export declare const linkConcept: ConceptLinker;
+export interface AttestationResult {
+    aid: number;
+    objectId: string;
+    hash: string;
+}
+export interface DependencyRow {
+    moduleId: string;
+    dependsOn: string;
+    reason?: string;
+}
+/**
+ * Signature of the module dependency reader.
+ */
+type DependencyReader = (db: DatabaseSync, moduleId: string) => DependencyRow[];
+export declare const dependencies: DependencyReader;
+/**
+ * Signature of the module dependency linker.
+ */
+type DependencyLinker = (db: DatabaseSync, moduleId: string, dependencyId: string, reason?: string) => boolean;
+export declare const linkDependency: DependencyLinker;
+/**
+ * Signature of the dependency cycle detector.
+ */
+type CycleDetector = (db: DatabaseSync) => boolean;
+/**
+ * DFS over the dependency graph; uses the structure library's Stack/Set.
+ */
+export declare const hasDependencyCycle: CycleDetector;
+/**
+ * Signature of the module content verifier.
+ */
+type ModuleContentVerifier = (db: DatabaseSync, compute: (entry: string) => Promise<string>) => Promise<VerifyReport>;
+/**
+ * Recompute each module directory's digest and compare it with the declaration.
+ */
+export declare const verifyModuleContent: ModuleContentVerifier;
+/**
+ * Signature of the registry attester.
+ */
+type Attester = (db: DatabaseSync, subjectKind: "concept" | "module", subjectId: string, claimId: string, at: string) => AttestationResult;
+/**
+ * Attest a registry row with a claim. The attestation is an `evidence` object
+ * in the chain plus a row that points at it, so a module can be justified by
+ * something stronger than "the directory exists".
+ */
+export declare const attest: Attester;
+/**
+ * Signature of the registry verifier.
+ */
+type RegistryVerifier = (db: DatabaseSync) => VerifyReport;
+export declare const verifyRegistry: RegistryVerifier;
+export {};