attention-manifest-protocol 0.4.2 → 0.4.4

package/src/concept/concept.ts

@@ -1,75 +0,0 @@
-/**
- * AMP v0.1 — Concept: a compressed pattern that can occupy one attention slot.
- * Mirrors docs/schemas/concept.schema.json.
- */
-import type { Confidence, Id, Provenance, Ref, Timestamp } from "../types/common.ts";
-
-export type ConceptStatus = "proposed" | "active" | "deprecated" | "merged" | "split";
-
-export interface ConceptFeature {
-    feature: string;
-    weight?: Confidence;
-}
-
-export interface ConceptDimension {
-    name: string;
-    scale?: "nominal" | "ordinal" | "interval" | "ratio";
-}
-
-export type ConceptRelationType = "is-a" | "part-of" | "causes" | "enables" | "contrasts-with" | "derived-from" | "precedes";
-
-export interface ConceptRelation {
-    type: ConceptRelationType;
-    target: Ref;
-}
-
-export interface ConceptExample {
-    ref?: Ref;
-    description: string;
-    typicality?: Confidence;
-}
-
-/**
- * Operations are recorded, never applied in place.
- */
-export interface ConceptRevision {
-    op: "merge" | "split" | "refine" | "retire";
-    at: Timestamp;
-    from?: Ref[];
-    reason?: string;
-}
-
-export interface Concept {
-    amp: "0.1";
-    kind: "concept";
-    id: Id;
-    label: string;
-    definition: string;
-    /**
-     * Defining features (prototype-style, graded — not an OWL class expression).
-     */
-    intension: ConceptFeature[];
-    /**
-     * Conceptual-space dimensions, when the concept is geometric rather than featural.
-     */
-    dimensions?: ConceptDimension[];
-    /**
-     * Anti-vacuity: external theory this concept is answerable to.
-     */
-    theory_refs?: string[];
-    extension?: Ref[];
-    prototype?: string;
-    /**
-     * Grounding: at least one real instance. A concept with none is a label.
-     */
-    examples?: ConceptExample[];
-    counterexamples?: ConceptExample[];
-    relations?: ConceptRelation[];
-    grounded_in?: Ref[];
-    status: ConceptStatus;
-    confidence: Confidence;
-    provenance: Provenance;
-    version: number;
-    created: Timestamp;
-    revision?: ConceptRevision;
-}

package/src/concept/conceptBudget.ts

@@ -1,346 +0,0 @@
-import { digestOf } from "../semantic/canonical.ts";
-import type { Concept, ConceptExample, ConceptRelation } from "./concept.ts";
-import type { ConceptBudget, ConceptCheckpoint, ConceptDrop, ConceptPrunePlan } from "./conceptBudgetTypes.ts";
-
-/**
- * Concept economy: bound one concept's content, and bound how many versions of
- * it are kept in storage.
- *
- * The rules answer one question: what may be removed without making the concept
- * worse at being a concept? Duplicated examples, duplicated relations, relation
- * targets that no longer resolve, and examples beyond the reading budget. Never
- * the definition, the intension, the counterexamples, or the last example that
- * keeps the concept grounded.
- */
-
-export const DefaultConceptBudget: ConceptBudget = {
-    amp: "0.1",
-    kind: "concept-budget",
-    maxExamples: 8,
-    minExamples: 1,
-    maxRelations: 12,
-    keepVersions: 1,
-};
-
-function normaliseText(text: string): string {
-    return text.trim().toLowerCase().replace(/\s+/g, " ");
-}
-
-function utf8Bytes(value: unknown): number {
-    return new TextEncoder().encode(JSON.stringify(value)).length;
-}
-
-function typicalityOf(example: ConceptExample): number {
-    return typeof(example.typicality) === "number" ? example.typicality : 0.5;
-}
-
-function clip(text: string, limit = 60): string {
-    const flat = text.trim().replace(/\s+/g, " ");
-    return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
-}
-
-export interface ConceptPruneOptions {
-    /**
-     * Resolvers for relation targets. Without one, dangling relations cannot be detected.
-     */
-    known?: (kind: string, id: string) => boolean;
-}
-
-export interface ConceptPruneResult {
-    concept: Concept;
-    plan: ConceptPrunePlan;
-}
-
-function resolveBudget(overrides: Partial<ConceptBudget>): ConceptBudget {
-    const budget: ConceptBudget = { ...DefaultConceptBudget, ...overrides, amp: "0.1", kind: "concept-budget" };
-    const minExamples = Math.max(0, Math.floor(budget.minExamples));
-    return {
-        ...budget,
-        minExamples,
-        maxExamples: Math.max(minExamples, Math.floor(budget.maxExamples)),
-        maxRelations: Math.max(0, Math.floor(budget.maxRelations)),
-        keepVersions: Math.max(1, Math.floor(budget.keepVersions)),
-    };
-}
-
-/**
- * A bounded view of one concept.
- *
- * Deterministic: the input is not mutated, and the same input yields the same
- * plan. `version` is carried over unchanged — a view is not a revision, and
- * bumping the version here would forge lineage.
- */
-export function pruneConcept(concept: Concept, overrides: Partial<ConceptBudget> = {}, options: ConceptPruneOptions = {}): ConceptPruneResult {
-    const budget = resolveBudget(overrides);
-    const dropped: ConceptDrop[] = [];
-    let reclaimed = 0;
-
-    const drop = (item: ConceptDrop, raw: unknown): void => {
-        dropped.push(item);
-        reclaimed += utf8Bytes(raw);
-    };
-
-    const view: Concept = { ...concept };
-
-    // Examples: collapse duplicates, then trim past the ceiling, never past the floor.
-    if (concept.examples) {
-        const unique = new Map<string, { example: ConceptExample; index: number }>();
-        concept.examples.forEach((example, index) => {
-            const key = normaliseText(example.description);
-            const existing = unique.get(key);
-            if (!existing) {
-                unique.set(key, { example, index });
-                return;
-            }
-            if (typicalityOf(example) > typicalityOf(existing.example)) {
-                // The newcomer is the better example of the pair; the earlier one goes.
-                drop(
-                    {
-                        slot: "example",
-                        index: existing.index,
-                        summary: clip(existing.example.description),
-                        reason: "duplicate",
-                        revisit_if: "if the kept example is removed as atypical",
-                    },
-                    existing.example,
-                );
-                unique.set(key, { example, index });
-                return;
-            }
-            drop(
-                {
-                    slot: "example",
-                    index,
-                    summary: clip(example.description),
-                    reason: "duplicate",
-                    revisit_if: "if this example is rewritten with a detail the kept one lacks",
-                },
-                example,
-            );
-        });
-
-        const kept = [...unique.values()].sort((a, b) => a.index - b.index);
-        if (kept.length > budget.maxExamples) {
-            const ranked = [...kept].sort((a, b) => typicalityOf(b.example) - typicalityOf(a.example) || a.index - b.index);
-            const keep = new Set(ranked.slice(0, budget.maxExamples).map((item) => item.index));
-            for (const item of ranked) {
-                if (keep.has(item.index)) {
-                    continue;
-                }
-                drop(
-                    {
-                        slot: "example",
-                        index: item.index,
-                        summary: clip(item.example.description),
-                        reason: "over-budget",
-                        revisit_if: "if the concept needs a broader extension again",
-                    },
-                    item.example,
-                );
-            }
-            view.examples = kept.filter((item) => keep.has(item.index)).map((item) => item.example);
-        } else {
-            view.examples = kept.map((item) => item.example);
-        }
-    }
-
-    // Counterexamples are the falsifiers; they are never trimmed (W-2).
-
-    // Relations: duplicate, dangling, then over budget.
-    if (concept.relations) {
-        const seen = new Set<string>();
-        const surviving: { relation: ConceptRelation; index: number }[] = [];
-        concept.relations.forEach((relation, index) => {
-            const key = `${relation.type}|${relation.target.kind}|${relation.target.id}`;
-            if (seen.has(key)) {
-                drop(
-                    {
-                        slot: "relation",
-                        index,
-                        summary: `${relation.type} → ${relation.target.kind}:${relation.target.id}`,
-                        reason: "duplicate",
-                        revisit_if: "if the duplicate gains a distinct provenance or weight",
-                    },
-                    relation,
-                );
-                return;
-            }
-            seen.add(key);
-            if (options.known && options.known(relation.target.kind, relation.target.id) === false) {
-                drop(
-                    {
-                        slot: "relation",
-                        index,
-                        summary: `${relation.type} → ${relation.target.kind}:${relation.target.id}`,
-                        reason: "dangling",
-                        revisit_if: `if ${relation.target.kind}:${relation.target.id} is imported again`,
-                    },
-                    relation,
-                );
-                return;
-            }
-            surviving.push({ relation, index });
-        });
-
-        const keep = surviving.slice(0, budget.maxRelations);
-        for (const item of surviving.slice(budget.maxRelations)) {
-            drop(
-                {
-                    slot: "relation",
-                    index: item.index,
-                    summary: `${item.relation.type} → ${item.relation.target.kind}:${item.relation.target.id}`,
-                    reason: "over-budget",
-                    revisit_if: "if the relation becomes load-bearing for a query",
-                },
-                item.relation,
-            );
-        }
-        view.relations = keep.map((item) => item.relation);
-    }
-
-    // Extension: exact duplicates only. Membership refs may be external, so no dangling check.
-    if (concept.extension) {
-        const seen = new Set<string>();
-        const kept = concept.extension.filter((ref, index) => {
-            const key = `${ref.kind}:${ref.id}`;
-            if (!seen.has(key)) {
-                seen.add(key);
-                return true;
-            }
-            drop({ slot: "extension", index, summary: key, reason: "duplicate", revisit_if: "if the duplicate comes from a different source" }, ref);
-            return false;
-        });
-        view.extension = kept;
-    }
-
-    return {
-        concept: view,
-        plan: {
-            amp: "0.1",
-            kind: "concept-prune-plan",
-            concept: concept.id,
-            version: concept.version,
-            dropped,
-            reclaimedBytes: reclaimed,
-            budget,
-        },
-    };
-}
-
-export class ConceptCompactionRefused extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = "ConceptCompactionRefused";
-    }
-}
-
-export interface ConceptHistoryCompaction {
-    checkpoint: ConceptCheckpoint;
-    head: Concept;
-    removed: Concept[];
-}
-
-/**
- * Replace every version except the retained tail with a checkpoint.
- *
- * Refuses on a gap in the version sequence: a checkpoint over a broken lineage
- * would assert that nothing is missing while being unable to prove it.
- */
-export function compactConceptHistory(versions: Concept[], options: { keepVersions?: number; now?: string } = {}): ConceptHistoryCompaction {
-    if (versions.length === 0) {
-        throw new ConceptCompactionRefused("no versions to compact");
-    }
-
-    const ordered = [...versions].sort((a, b) => a.version - b.version);
-    const id = ordered[0].id;
-    for (const version of ordered) {
-        if (version.id !== id) {
-            throw new ConceptCompactionRefused(`versions belong to different concepts: ${id} and ${version.id}`);
-        }
-    }
-    for (let index = 1; index < ordered.length; index++) {
-        if (ordered[index].version !== ordered[index - 1].version + 1) {
-            throw new ConceptCompactionRefused(`lineage is broken between version ${ordered[index - 1].version} and ${ordered[index].version}`);
-        }
-    }
-
-    const keepVersions = Math.max(1, Math.floor(options.keepVersions ?? 1));
-    const cut = ordered.length - keepVersions;
-    if (cut <= 0) {
-        throw new ConceptCompactionRefused("nothing to compact: every version is inside the retention window");
-    }
-
-    const removed = ordered.slice(0, cut);
-    const head = ordered[ordered.length - 1];
-    const last = removed[removed.length - 1];
-
-    return {
-        checkpoint: {
-            amp: "0.1",
-            kind: "concept-checkpoint",
-            id: `cp.concept.${id}.${last.version}`,
-            concept: id,
-            from: removed[0].version,
-            to: last.version,
-            count: removed.length,
-            tip: digestOf(last),
-            root: digestOf(removed),
-            created: options.now ?? new Date().toISOString(),
-            budget: { keepVersions },
-        },
-        head,
-        removed,
-    };
-}
-
-/**
- * Check a concept checkpoint against the versions it claims to cover.
- */
-export function verifyConceptCheckpoint(checkpoint: ConceptCheckpoint, removed: Concept[], head?: Concept): { ok: boolean; reasons: string[] } {
-    const reasons: string[] = [];
-
-    if (digestOf(removed) !== checkpoint.root) {
-        reasons.push("checkpoint root does not cover the removed versions");
-    }
-    if (removed.length !== checkpoint.count) {
-        reasons.push(`checkpoint count ${checkpoint.count} does not match ${removed.length} removed versions`);
-    }
-
-    for (let index = 1; index < removed.length; index++) {
-        if (removed[index].version !== removed[index - 1].version + 1) {
-            reasons.push(`removed versions are not contiguous at ${removed[index - 1].version} → ${removed[index].version}`);
-        }
-    }
-
-    const first = removed[0];
-    const last = removed[removed.length - 1];
-    if (!first || !last) {
-        reasons.push("no versions were removed");
-    } else {
-        if (first.version !== checkpoint.from) {
-            reasons.push(`checkpoint starts at ${checkpoint.from} but the first removed version is ${first.version}`);
-        }
-        if (last.version !== checkpoint.to) {
-            reasons.push(`checkpoint ends at ${checkpoint.to} but the last removed version is ${last.version}`);
-        }
-        if (digestOf(last) !== checkpoint.tip) {
-            reasons.push("checkpoint tip does not match the last removed version");
-        }
-        for (const version of removed) {
-            if (version.id !== checkpoint.concept) {
-                reasons.push(`removed version ${version.version} belongs to ${version.id}`);
-            }
-        }
-    }
-
-    if (head) {
-        if (head.id !== checkpoint.concept) {
-            reasons.push(`head belongs to ${head.id}, not ${checkpoint.concept}`);
-        }
-        if (head.version !== checkpoint.to + 1) {
-            reasons.push(`head version ${head.version} does not continue from ${checkpoint.to}`);
-        }
-    }
-
-    return { ok: reasons.length === 0, reasons };
-}

package/src/concept/conceptBudgetTypes.ts

@@ -1,79 +0,0 @@
-/**
- * AMP v0.1 — concept economy.
- *
- * A concept is the unit that occupies an attention slot, so its size is paid on
- * every turn that uses it. Left alone, a concept accretes: examples pile up,
- * relations duplicate, old versions accumulate in the ledger. This layer bounds
- * both, without letting either the definition or the falsifiers be trimmed away.
- *
- * Two operations, deliberately separate:
- *
- * - **pruneConcept** returns a bounded *view* of one concept. Storage is
- *   untouched and `version` does not move: a view is not a revision.
- * - **compactConceptHistory** replaces every version except the head with a
- *   checkpoint that commits to their digest, so lineage stays provable.
- */
-import type { Digest, Id, Timestamp } from "../types/common.ts";
-
-export interface ConceptBudget {
-    amp: "0.1";
-    kind: "concept-budget";
-    /**
-     * Hard ceiling on examples in a view.
-     */
-    maxExamples: number;
-    /**
-     * Floor that keeps a concept grounded: zero examples would make it a label.
-     */
-    minExamples: number;
-    maxRelations: number;
-    /**
-     * Versions kept in storage besides the head. 1 means head only.
-     */
-    keepVersions: number;
-}
-
-export type ConceptDropReason = "duplicate" | "over-budget" | "dangling";
-
-export interface ConceptDrop {
-    slot: "example" | "relation" | "extension";
-    index: number;
-    /**
-     * Human-readable identification of what left the view.
-     */
-    summary: string;
-    reason: ConceptDropReason;
-    revisit_if: string;
-}
-
-export interface ConceptPrunePlan {
-    amp: "0.1";
-    kind: "concept-prune-plan";
-    concept: Id;
-    version: number;
-    dropped: ConceptDrop[];
-    reclaimedBytes: number;
-    budget: ConceptBudget;
-}
-
-export interface ConceptCheckpoint {
-    amp: "0.1";
-    kind: "concept-checkpoint";
-    id: Id;
-    concept: Id;
-    from: number;
-    to: number;
-    count: number;
-    /**
-     * Digest of the last removed version, so a holder can spot a swap.
-     */
-    tip: Digest;
-    /**
-     * Digest over the removed versions, in version order.
-     */
-    root: Digest;
-    created: Timestamp;
-    budget: {
-        keepVersions: number;
-    };
-}

package/src/concept/index.ts

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

package/src/concurrency/idempotency.ts

@@ -1,41 +0,0 @@
-/**
- * Idempotency for external effects.
- *
- * A message send or a tool call carries a key; the first successful attempt
- * stores its result, and a retry after a crash returns that result instead of
- * performing the effect twice. The unique primary key is the arbiter, so two
- * workers racing on the same key cannot both execute.
- */
-import type { DatabaseSync } from "node:sqlite";
-
-export interface OnceResult<T> {
-    value: T;
-    replayed: boolean;
-}
-
-type IdempotencyRow = {
-    result: string;
-};
-
-type Once = <T>(db: DatabaseSync, key: string, at: string, fn: () => T) => OnceResult<T>;
-
-export const once: Once = <T>(db: DatabaseSync, key: string, at: string, fn: () => T): OnceResult<T> => {
-    const existing: IdempotencyRow | undefined = db.prepare("SELECT result FROM idempotency WHERE key = ?").get(key) as IdempotencyRow | undefined;
-    if (existing !== (void 0)) {
-        return { value: JSON.parse(existing.result) as T, replayed: true };
-    }
-    const value: T = fn();
-    try {
-        db.prepare("INSERT INTO idempotency (key, result, created_at) VALUES (?, ?, ?)").run(key, JSON.stringify(value), at);
-        return { value, replayed: false };
-    } catch {
-        /**
-         * Another worker won the insert between our SELECT and INSERT.
-         */
-        const row: IdempotencyRow | undefined = db.prepare("SELECT result FROM idempotency WHERE key = ?").get(key) as IdempotencyRow | undefined;
-        if (row === (void 0)) {
-            throw new Error(`idempotency key ${key} was not stored`);
-        }
-        return { value: JSON.parse(row.result) as T, replayed: true };
-    }
-};

package/src/concurrency/index.ts

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

package/src/concurrency/mutex.ts

@@ -1,26 +0,0 @@
-/**
- * An async mutex for in-process critical sections.
- *
- * The kernel's own writes are synchronous and serialized by SQLite, so this is
- * for handlers that interleave at `await` points: a tool call, an LLM request,
- * a file write. It is not a cross-worker lock — for that, use the database
- * lease (`claimThread` + fencing token), because a promise cannot be shared
- * between `worker_threads`.
- */
-export class Mutex {
-    private tail: Promise<void> = Promise.resolve();
-
-    async run<T>(fn: () => Promise<T> | T): Promise<T> {
-        const previous: Promise<void> = this.tail;
-        let release: () => void = () => {};
-        this.tail = new Promise<void>((resolve) => {
-            release = resolve;
-        });
-        await previous;
-        try {
-            return await fn();
-        } finally {
-            release();
-        }
-    }
-}

package/src/concurrency/namedLocks.ts

@@ -1,35 +0,0 @@
-/**
- * Named mutexes for one worker.
- *
- * A single process may need to serialize access to a resource (a file, a
- * browser tab, an MCP session) without blocking unrelated work. The registry
- * keeps one {@link Mutex} per name; `UnorderedMap` is enough because names are
- * opaque and the lock itself carries no ordering.
- *
- * This is intra-worker only. Cross-worker exclusion is the database lease
- * (`claimThread`), not a promise.
- */
-import { UnorderedMap } from "../structure/unordered.ts";
-import { Mutex } from "./mutex.ts";
-
-export class NamedLocks {
-    private readonly locks: UnorderedMap<string, Mutex> = new UnorderedMap<string, Mutex>();
-
-    forName(name: string): Mutex {
-        const existing: Mutex | undefined = this.locks.get(name);
-        if (existing !== (void 0)) {
-            return existing;
-        }
-        const mutex: Mutex = new Mutex();
-        this.locks.set(name, mutex);
-        return mutex;
-    }
-
-    run<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
-        return this.forName(name).run(fn);
-    }
-
-    get size(): number {
-        return this.locks.size;
-    }
-}

package/src/concurrency/retry.ts

@@ -1,50 +0,0 @@
-/**
- * Retry helpers for the two kinds of contention a kernel sees.
- *
- * - SQLite write contention between `worker_threads`: `SQLITE_BUSY`. The
- *   connection sets `busy_timeout`, and async callers can additionally back off
- *   with {@link withBusyRetry}.
- * - Application-level contention: a lease or a row version that moved. Callers
- *   should re-read and decide, not retry blindly.
- */
-
-export interface RetryOptions {
-    attempts?: number;
-    baseMs?: number;
-    maxMs?: number;
-    sleep?: (ms: number) => Promise<void>;
-    isRetryable?: (error: unknown) => boolean;
-}
-
-export const isBusyError: (error: unknown) => boolean = (error: unknown): boolean => {
-    const message: string = error instanceof Error ? error.message : `${error}`;
-    return message.includes("database is locked") || message.includes("SQLITE_BUSY");
-};
-
-const defaultSleep: (ms: number) => Promise<void> = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-type BusyRetry = <T>(fn: () => Promise<T> | T, options?: RetryOptions) => Promise<T>;
-
-/**
- * Retry an async operation with exponential backoff while it is busy.
- */
-export const withBusyRetry: BusyRetry = async <T>(fn: () => Promise<T> | T, options: RetryOptions = {}): Promise<T> => {
-    const attempts: number = options.attempts ?? 5;
-    const baseMs: number = options.baseMs ?? 25;
-    const maxMs: number = options.maxMs ?? 1000;
-    const sleep: (ms: number) => Promise<void> = options.sleep ?? defaultSleep;
-    const retryable: (error: unknown) => boolean = options.isRetryable ?? isBusyError;
-    let lastError: unknown;
-    for (let attempt: number = 0; attempt < attempts; attempt += 1) {
-        try {
-            return await fn();
-        } catch (error) {
-            lastError = error;
-            if (!retryable(error) || attempt === attempts - 1) {
-                throw error;
-            }
-            await sleep(Math.min(maxMs, baseMs * 2 ** attempt));
-        }
-    }
-    throw lastError;
-};