attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/diagnosis/checklist.js

@@ -0,0 +1,61 @@
+/**
+ * USE-style checklist. Utilization, saturation and errors are asked per layer;
+ * latency is decomposed because "slow" is not a layer.
+ */
+export const LayerChecks = {
+    thread_pool: {
+        layer: "thread_pool",
+        question: "Are worker threads exhausted, blocked, or idle?",
+        signals: ["utilization", "saturation", "errors"],
+        probe: "active/max threads, run queue, reject count; one thread dump with top blocking frames",
+    },
+    connection_pool: {
+        layer: "connection_pool",
+        question: "Is the pool exhausted, leaking, or waiting on slow work?",
+        signals: ["utilization", "saturation", "latency"],
+        probe: "active/idle/pending, checkout wait P99, timeout count, held-time distribution",
+    },
+    connect: {
+        layer: "connect",
+        question: "Is a new connection slow to establish?",
+        signals: ["latency", "errors"],
+        probe: "TCP RTT, TLS handshake, auth, DNS, connect P99, new-connection/churn rate",
+    },
+    database: {
+        layer: "database",
+        question: "Is the database slow, locked, or out of connections?",
+        signals: ["utilization", "saturation", "latency", "errors"],
+        probe: "pg_stat_statements top SQL, EXPLAIN ANALYZE, pg_locks blocking chain, wait events, sessions/max_connections",
+    },
+    queue: {
+        layer: "queue",
+        question: "Is work arriving faster than it is consumed?",
+        signals: ["saturation", "latency", "errors"],
+        probe: "consumer lag, consume rate, retry/DLQ, partition skew, active consumers",
+    },
+    application: {
+        layer: "application",
+        question: "Is application code or GC burning CPU / holding locks?",
+        signals: ["utilization", "saturation", "errors"],
+        probe: "CPU, GC pauses, thread dump, lock contention, dependency spans",
+    },
+    release: {
+        layer: "release",
+        question: "Is the failure correlated with a specific version?",
+        signals: ["errors", "latency"],
+        probe: "per-version error/latency split, diff, canary cohort, deploy timeline",
+    },
+};
+export const stepFor = (layer) => {
+    const check = LayerChecks[layer];
+    return {
+        id: `probe.${layer}`,
+        layer,
+        intent: `inspect ${layer}`,
+        probe: check.probe,
+        readOnly: true,
+        successCriteria: [`${layer} utilization/saturation/error signals are known`, "the next hypothesis is discriminated or explicitly left open"],
+        stopIf: "a higher layer fully explains the symptoms and the lower layer is healthy",
+    };
+};
+export const stepsFor = (layers) => layers.map((layer) => stepFor(layer));

package/lib/diagnosis/context.d.ts

@@ -0,0 +1,19 @@
+import { ContextAst, MemoryDetailStore } from "../context/ast.js";
+import type { ContextAstNode } from "../context/ast.js";
+import type { DiagnosticFrame } from "./types.js";
+import { selectHypothesis } from "./frame.js";
+export interface DiagnosisContext {
+    ast: ContextAst;
+    details: MemoryDetailStore;
+    view: ReturnType<ContextAst["view"]>;
+    top?: ReturnType<typeof selectHypothesis>;
+}
+type ContextProjector = (frame: DiagnosticFrame, budgetTokens?: number) => DiagnosisContext;
+/**
+ * Project a DiagnosticFrame into the context AST:
+ * incident -> layer steps -> signals/hypotheses. Summaries stay in the view;
+ * raw signal/probe payloads live behind local refs.
+ */
+export declare const toContextAst: ContextProjector;
+export declare const diagnosisNode: (id: string) => ContextAstNode["kind"];
+export {};

package/lib/diagnosis/context.js

@@ -0,0 +1,79 @@
+import { ContextAst, MemoryDetailStore } from "../context/ast.js";
+import { assessHypotheses, selectHypothesis } from "./frame.js";
+/**
+ * Project a DiagnosticFrame into the context AST:
+ * incident -> layer steps -> signals/hypotheses. Summaries stay in the view;
+ * raw signal/probe payloads live behind local refs.
+ */
+export const toContextAst = (frame, budgetTokens = 1200) => {
+    const ast = new ContextAst();
+    const details = new MemoryDetailStore();
+    let order = 0;
+    ast.add({
+        id: "diagnosis",
+        kind: "goal",
+        summary: `${frame.incident.summary} | phase=${frame.phase} | layers=${frame.layers.join(",")}`,
+        order: order++,
+        salience: 1,
+    });
+    for (let stepIndex = 0; stepIndex < frame.steps.length; stepIndex += 1) {
+        const step = frame.steps[stepIndex];
+        const layerId = `step.${step.layer}`;
+        ast.add({
+            id: layerId,
+            parentId: "diagnosis",
+            kind: "frame",
+            summary: `inspect ${step.layer}: ${step.probe}`,
+            order: order++,
+            salience: 0.8,
+        });
+        const signals = (frame.incident.signals ?? []).filter((signal) => signal.layer === step.layer);
+        for (let signalIndex = 0; signalIndex < signals.length; signalIndex += 1) {
+            const signal = signals[signalIndex];
+            const id = `signal.${step.layer}.${signal.name}`;
+            const raw = JSON.stringify(signal);
+            const ref = details.put(id, raw);
+            ast.add({
+                id,
+                parentId: layerId,
+                kind: "observation",
+                summary: `${signal.layer}/${signal.kind}/${signal.name}: ${signal.state}`,
+                detailRef: ref,
+                detailTokens: Math.ceil(raw.length / 4),
+                order: order++,
+                salience: signal.state === "critical" ? 0.95 : 0.6,
+            });
+        }
+    }
+    const ranked = assessHypotheses(frame);
+    for (let index = 0; index < ranked.length; index += 1) {
+        const assessment = ranked[index];
+        const id = `hyp.${assessment.hypothesis.id}`;
+        const raw = JSON.stringify({
+            cause: assessment.hypothesis.cause,
+            matched: assessment.matched,
+            missing: assessment.missing,
+            contradicted: assessment.contradicted,
+        });
+        const ref = details.put(id, raw);
+        ast.add({
+            id,
+            parentId: "diagnosis",
+            kind: "hypothesis",
+            summary: `${assessment.hypothesis.layer}: ${assessment.hypothesis.cause} (confidence=${assessment.confidence.toFixed(2)})`,
+            detailRef: ref,
+            detailTokens: Math.ceil(raw.length / 4),
+            order: order++,
+            salience: assessment.confidence,
+        });
+    }
+    for (let index = 0; index < frame.steps.length - 1; index += 1) {
+        ast.link({ from: `step.${frame.steps[index].layer}`, to: `step.${frame.steps[index + 1].layer}`, kind: "before" });
+    }
+    const firstStep = frame.steps[0];
+    if (firstStep !== (void 0)) {
+        ast.link({ from: "diagnosis", to: `step.${firstStep.layer}`, kind: "before" });
+    }
+    return { ast, details, view: ast.view(budgetTokens), top: selectHypothesis(frame) };
+};
+export const diagnosisNode = (id) => id.startsWith("hyp.") ? "hypothesis" : id.startsWith("signal.") ? "observation" : "frame";

package/lib/diagnosis/frame.d.ts

@@ -0,0 +1,34 @@
+import type { DiagnosticFrame, DiagnosticLayer, DiagnosticSignal, DiagnosticStep, Hypothesis, HypothesisAssessment, IncidentInput } from "./types.js";
+import type { PlanTask } from "../goal/plan.js";
+import type { ActionPlan } from "../runtime/action.js";
+export declare const DefaultHypotheses: readonly Hypothesis[];
+export declare const assessHypotheses: (frame: DiagnosticFrame) => HypothesisAssessment[];
+export declare const selectHypothesis: (frame: DiagnosticFrame) => HypothesisAssessment | undefined;
+export declare const buildDiagnosisFrame: (incident: IncidentInput) => DiagnosticFrame;
+/**
+ * Add an observation without mutating the original frame.
+ */
+export declare const observe: (frame: DiagnosticFrame, signal: DiagnosticSignal) => DiagnosticFrame;
+export declare const nextStep: (frame: DiagnosticFrame) => DiagnosticStep | undefined;
+/**
+ * Route to the step that best matches the current evidence. The static layer
+ * order is only a fallback: a strong DB hypothesis must not be routed to
+ * `thread_pool` just because it is first in the checklist.
+ */
+export declare const routeStep: (frame: DiagnosticFrame, minConfidence?: number) => DiagnosticStep | undefined;
+export declare const validateDiagnosisFrame: (frame: DiagnosticFrame) => string[];
+/**
+ * Render the next diagnostic step as a bounded, read-only ActionPlan.
+ */
+export declare const toActionPlan: (frame: DiagnosticFrame) => ActionPlan | undefined;
+/**
+ * Render diagnostic steps as existing PlanTasks (all irreversibility 0).
+ */
+export declare const toPlanTasks: (frame: DiagnosticFrame) => PlanTask[];
+/**
+ * Select the layer that best explains the current evidence, with an explicit reason.
+ */
+export declare const selectLayer: (frame: DiagnosticFrame) => {
+    layer: DiagnosticLayer | null;
+    reason: string;
+};

package/lib/diagnosis/frame.js

@@ -0,0 +1,230 @@
+import { LayerOrder, clamp01 } from "./types.js";
+import { stepsFor } from "./checklist.js";
+export const DefaultHypotheses = [
+    {
+        id: "thread_pool_exhaustion",
+        cause: "worker threads are exhausted or blocked",
+        layer: "thread_pool",
+        supports: [
+            { layer: "thread_pool", kind: "saturation", name: "thread.queue" },
+            { layer: "thread_pool", kind: "utilization", name: "thread.active_max" },
+            { layer: "thread_pool", kind: "errors", name: "thread.reject" },
+        ],
+        contradicts: [{ layer: "thread_pool", kind: "utilization", name: "thread.idle" }],
+        discriminatingTest: "thread dump: are active threads blocked on a pool, a lock, or CPU?",
+        baseConfidence: 0.25,
+        rootWeight: 0,
+    },
+    {
+        id: "connection_pool_exhaustion",
+        cause: "connection pool is exhausted or leaking",
+        layer: "connection_pool",
+        supports: [
+            { layer: "connection_pool", kind: "saturation", name: "pool.pending" },
+            { layer: "connection_pool", kind: "utilization", name: "pool.active_max" },
+            { layer: "connection_pool", kind: "latency", name: "pool.checkout_wait" },
+        ],
+        contradicts: [{ layer: "connection_pool", kind: "utilization", name: "pool.idle" }],
+        discriminatingTest: "checkout wait vs active vs held-time: pool exhaustion, leak, or slow owner?",
+        baseConfidence: 0.25,
+        rootWeight: 0,
+    },
+    {
+        id: "connect_latency",
+        cause: "new connections are slow to establish",
+        layer: "connect",
+        supports: [
+            { layer: "connect", kind: "latency", name: "connect.p99" },
+            { layer: "connect", kind: "errors", name: "connect.error" },
+            { layer: "connect", kind: "latency", name: "tls.handshake" },
+        ],
+        contradicts: [{ layer: "connect", kind: "latency", name: "connect.ok" }],
+        discriminatingTest: "split connect into TCP RTT, TLS, auth, DNS; is pool wait high while active is low?",
+        baseConfidence: 0.25,
+        rootWeight: 0.1,
+    },
+    {
+        id: "db_slow_query",
+        cause: "database queries are slow",
+        layer: "database",
+        supports: [
+            { layer: "database", kind: "latency", name: "db.query_p99" },
+            { layer: "database", kind: "utilization", name: "db.cpu" },
+            { layer: "database", kind: "saturation", name: "db.temp_spill" },
+        ],
+        contradicts: [{ layer: "database", kind: "latency", name: "db.query_ok" }],
+        discriminatingTest: "EXPLAIN ANALYZE: seq scan, temp spill, bad row estimate, or missing index?",
+        baseConfidence: 0.25,
+        rootWeight: 0.15,
+    },
+    {
+        id: "db_lock",
+        cause: "database locks are blocking progress",
+        layer: "database",
+        supports: [
+            { layer: "database", kind: "saturation", name: "db.lock_wait" },
+            { layer: "database", kind: "saturation", name: "db.blocking_chain" },
+        ],
+        contradicts: [{ layer: "database", kind: "saturation", name: "db.no_lock_wait" }],
+        discriminatingTest: "pg_locks + pg_blocking_pids: who blocks whom, and for how long?",
+        baseConfidence: 0.25,
+        rootWeight: 0.15,
+    },
+    {
+        id: "queue_backlog",
+        cause: "consumers cannot keep up with the queue",
+        layer: "queue",
+        supports: [
+            { layer: "queue", kind: "saturation", name: "queue.lag" },
+            { layer: "queue", kind: "latency", name: "queue.consume_rate" },
+            { layer: "queue", kind: "errors", name: "queue.retry" },
+        ],
+        contradicts: [{ layer: "queue", kind: "saturation", name: "queue.drained" }],
+        discriminatingTest: "lag with idle consumers (blocked) vs busy consumers (capacity)?",
+        baseConfidence: 0.2,
+        rootWeight: 0.1,
+    },
+    {
+        id: "code_regression",
+        cause: "application code or GC is the bottleneck",
+        layer: "application",
+        supports: [
+            { layer: "application", kind: "utilization", name: "app.cpu" },
+            { layer: "application", kind: "saturation", name: "app.gc_pause" },
+            { layer: "release", kind: "errors", name: "release.only_new_version" },
+        ],
+        contradicts: [{ layer: "database", kind: "latency", name: "db.query_p99" }],
+        discriminatingTest: "DB fast + app CPU/GC high + blocked stack in app code?",
+        baseConfidence: 0.2,
+        rootWeight: 0.1,
+    },
+];
+const patternMatches = (pattern, signal) => {
+    if (pattern.layer !== signal.layer) {
+        return false;
+    }
+    if (pattern.kind !== (void 0) && pattern.kind !== signal.kind) {
+        return false;
+    }
+    if (pattern.name !== (void 0) && signal.name !== pattern.name && !signal.name.startsWith(`${pattern.name}.`)) {
+        return false;
+    }
+    return true;
+};
+const label = (pattern) => [pattern.layer, pattern.kind, pattern.name].filter((part) => part !== (void 0)).join(".");
+export const assessHypotheses = (frame) => {
+    return frame.hypotheses
+        .map((hypothesis) => {
+        const matched = hypothesis.supports.filter((pattern) => frame.incident.signals?.some((signal) => patternMatches(pattern, signal))).map(label);
+        const contradicted = (hypothesis.contradicts ?? [])
+            .filter((pattern) => frame.incident.signals?.some((signal) => patternMatches(pattern, signal)))
+            .map(label);
+        const missing = hypothesis.supports.filter((pattern) => !matched.includes(label(pattern))).map(label);
+        const score = matched.length - contradicted.length * 2;
+        return {
+            hypothesis,
+            score,
+            confidence: clamp01(hypothesis.baseConfidence + matched.length * 0.12 + (hypothesis.rootWeight ?? 0) - contradicted.length * 0.2),
+            matched,
+            missing,
+            contradicted,
+        };
+    })
+        .sort((left, right) => right.confidence - left.confidence || right.score - left.score);
+};
+export const selectHypothesis = (frame) => assessHypotheses(frame)[0];
+export const buildDiagnosisFrame = (incident) => {
+    const layers = incident.layers ?? LayerOrder;
+    return {
+        id: `diag.${incident.id}`,
+        incident,
+        layers: [...layers],
+        hypotheses: DefaultHypotheses.map((hypothesis) => ({ ...hypothesis })),
+        steps: stepsFor(layers),
+        phase: (incident.signals?.length ?? 0) > 0 ? "observing" : "framing",
+    };
+};
+/**
+ * Add an observation without mutating the original frame.
+ */
+export const observe = (frame, signal) => ({
+    ...frame,
+    incident: { ...frame.incident, signals: [...(frame.incident.signals ?? []), signal] },
+    phase: frame.phase === "framing" ? "observing" : frame.phase,
+});
+export const nextStep = (frame) => frame.steps[0];
+/**
+ * Route to the step that best matches the current evidence. The static layer
+ * order is only a fallback: a strong DB hypothesis must not be routed to
+ * `thread_pool` just because it is first in the checklist.
+ */
+export const routeStep = (frame, minConfidence = 0.5) => {
+    const top = selectHypothesis(frame);
+    if (top !== (void 0) && top.confidence >= minConfidence) {
+        const matched = frame.steps.find((step) => step.layer === top.hypothesis.layer);
+        if (matched !== (void 0)) {
+            return matched;
+        }
+    }
+    return nextStep(frame);
+};
+export const validateDiagnosisFrame = (frame) => {
+    const problems = [];
+    if (frame.layers.length === 0) {
+        problems.push("diagnosis requires at least one layer");
+    }
+    if (frame.hypotheses.length === 0) {
+        problems.push("diagnosis requires at least one hypothesis");
+    }
+    for (const hypothesis of frame.hypotheses) {
+        if (hypothesis.discriminatingTest.trim().length === 0) {
+            problems.push(`hypothesis ${hypothesis.id} lacks a discriminating test`);
+        }
+    }
+    if (frame.steps.some((step) => step.readOnly !== true)) {
+        problems.push("diagnostic steps must be read-only");
+    }
+    if (new Set(frame.steps.map((step) => step.id)).size !== frame.steps.length) {
+        problems.push("duplicate diagnostic step ids");
+    }
+    return problems;
+};
+/**
+ * Render the next diagnostic step as a bounded, read-only ActionPlan.
+ */
+export const toActionPlan = (frame) => {
+    const step = routeStep(frame);
+    if (step === (void 0)) {
+        return undefined;
+    }
+    return {
+        goal: `discriminate the incident cause at ${step.layer}`,
+        intent: `diagnose:${step.layer}`,
+        expectedEffect: `evidence for or against ${step.layer} hypotheses`,
+        preconditions: ["diagnostic step is read-only", "no production mutation before discrimination"],
+        successCriteria: step.successCriteria,
+        risk: "read",
+    };
+};
+/**
+ * Render diagnostic steps as existing PlanTasks (all irreversibility 0).
+ */
+export const toPlanTasks = (frame) => frame.steps.map((step, index) => ({
+    id: step.id,
+    intent: step.intent,
+    actor: "tool",
+    pre: index === 0 ? [] : [frame.steps[index - 1].id],
+    expect: { observation: step.probe, check: step.successCriteria.join("; ") },
+    irreversibility: 0,
+    status: "pending",
+}));
+/**
+ * Select the layer that best explains the current evidence, with an explicit reason.
+ */
+export const selectLayer = (frame) => {
+    const top = selectHypothesis(frame);
+    if (top === (void 0)) {
+        return { layer: null, reason: "no hypotheses" };
+    }
+    return { layer: top.hypothesis.layer, reason: `${top.hypothesis.id} confidence=${top.confidence.toFixed(2)} matched=${top.matched.join(",") || "none"}` };
+};

package/lib/diagnosis/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./checklist.js";
+export * from "./frame.js";
+export * from "./context.js";
+export * from "./router.js";

package/lib/diagnosis/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./checklist.js";
+export * from "./frame.js";
+export * from "./context.js";
+export * from "./router.js";

package/lib/diagnosis/router.d.ts

@@ -0,0 +1,22 @@
+import type { DiagnosticFrame, DiagnosticLayer } from "./types.js";
+export type ToolIntent = "inspect" | "discriminate" | "confirm" | "refute";
+export interface ToolBinding {
+    layer: DiagnosticLayer;
+    hypothesisId?: string;
+    tool: string;
+    intent: ToolIntent;
+    readOnly: true;
+    produces: "metric" | "trace" | "log" | "lock" | "profile";
+}
+export interface ToolRoute {
+    tool: string;
+    layer: DiagnosticLayer;
+    hypothesisId?: string;
+    intent: ToolIntent;
+    readOnly: true;
+    reason: string;
+}
+export declare const DefaultToolBindings: readonly ToolBinding[];
+type ToolRouter = (frame: DiagnosticFrame, bindings?: readonly ToolBinding[], minConfidence?: number) => ToolRoute | undefined;
+export declare const routeTool: ToolRouter;
+export {};

package/lib/diagnosis/router.js

@@ -0,0 +1,47 @@
+/**
+ * Tool routing: AST/diagnosis candidates -> read-only probe.
+ *
+ * This is deliberately not an executor. It selects a tool and explains why; the
+ * runtime still wraps it in an Action/Operation and approval policy.
+ */
+import { selectHypothesis } from "./frame.js";
+export const DefaultToolBindings = [
+    { layer: "thread_pool", tool: "thread_dump", intent: "inspect", readOnly: true, produces: "profile" },
+    { layer: "connection_pool", tool: "pool_stats", intent: "inspect", readOnly: true, produces: "metric" },
+    { layer: "connect", tool: "connect_stats", intent: "inspect", readOnly: true, produces: "metric" },
+    { layer: "database", hypothesisId: "db_lock", tool: "pg_locks", intent: "discriminate", readOnly: true, produces: "lock" },
+    { layer: "database", hypothesisId: "db_slow_query", tool: "pg_stat_statements", intent: "discriminate", readOnly: true, produces: "trace" },
+    { layer: "database", tool: "pg_stat_statements", intent: "inspect", readOnly: true, produces: "trace" },
+    { layer: "queue", tool: "queue_lag", intent: "inspect", readOnly: true, produces: "metric" },
+    { layer: "application", tool: "app_profile", intent: "inspect", readOnly: true, produces: "profile" },
+    { layer: "release", tool: "version_diff", intent: "inspect", readOnly: true, produces: "log" },
+];
+export const routeTool = (frame, bindings = DefaultToolBindings, minConfidence = 0.5) => {
+    const top = selectHypothesis(frame);
+    if (top !== (void 0) && top.confidence >= minConfidence) {
+        const exact = bindings.filter((binding) => binding.layer === top.hypothesis.layer && binding.hypothesisId === top.hypothesis.id);
+        const layer = bindings.filter((binding) => binding.layer === top.hypothesis.layer && binding.hypothesisId === (void 0));
+        const selected = exact[0] ?? layer[0];
+        if (selected !== (void 0)) {
+            return {
+                tool: selected.tool,
+                layer: selected.layer,
+                hypothesisId: top.hypothesis.id,
+                intent: selected.intent,
+                readOnly: true,
+                reason: `${top.hypothesis.id} confidence=${top.confidence.toFixed(2)}; matched=${top.matched.join(",") || "none"}`,
+            };
+        }
+    }
+    const fallback = bindings.find((binding) => binding.layer === "thread_pool") ?? bindings[0];
+    if (fallback === (void 0)) {
+        return undefined;
+    }
+    return {
+        tool: fallback.tool,
+        layer: fallback.layer,
+        intent: fallback.intent,
+        readOnly: true,
+        reason: top === (void 0) ? "no hypothesis; start with thread dump" : `weak hypothesis confidence=${top.confidence.toFixed(2)}; start with thread dump`,
+    };
+};

package/lib/diagnosis/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Diagnostic frame: a bounded, read-only investigation of a failing system.
+ *
+ * This is deliberately independent of the runtime. It can be rendered into a
+ * Plan, an Action, or a prompt; it does not execute anything.
+ */
+export type DiagnosticLayer = "thread_pool" | "connection_pool" | "connect" | "database" | "queue" | "application" | "release";
+export type SignalKind = "utilization" | "saturation" | "errors" | "latency";
+export type ObservationState = "ok" | "warn" | "critical";
+export interface DiagnosticSignal {
+    layer: DiagnosticLayer;
+    kind: SignalKind;
+    name: string;
+    state: ObservationState;
+    value?: number;
+    note?: string;
+}
+export interface SignalPattern {
+    layer: DiagnosticLayer;
+    kind?: SignalKind;
+    name?: string;
+}
+export interface Hypothesis {
+    id: string;
+    cause: string;
+    layer: DiagnosticLayer;
+    supports: SignalPattern[];
+    contradicts?: SignalPattern[];
+    /**
+     * A check that separates this cause from its neighbors.
+     */
+    discriminatingTest: string;
+    baseConfidence: number;
+    /**
+     * Root-cause evidence weighs more than a downstream saturation symptom.
+     */
+    rootWeight?: number;
+}
+export interface HypothesisAssessment {
+    hypothesis: Hypothesis;
+    score: number;
+    confidence: number;
+    matched: string[];
+    missing: string[];
+    contradicted: string[];
+}
+export interface DiagnosticStep {
+    id: string;
+    layer: DiagnosticLayer;
+    intent: string;
+    probe: string;
+    readOnly: true;
+    successCriteria: string[];
+    stopIf?: string;
+}
+export interface IncidentInput {
+    id: string;
+    summary: string;
+    symptoms: string[];
+    signals?: DiagnosticSignal[];
+    recentChanges?: string[];
+    constraints?: string[];
+    /**
+     * Optional narrowing; defaults to all layers.
+     */
+    layers?: DiagnosticLayer[];
+}
+export interface DiagnosticFrame {
+    id: string;
+    incident: IncidentInput;
+    layers: DiagnosticLayer[];
+    hypotheses: Hypothesis[];
+    steps: DiagnosticStep[];
+    phase: "framing" | "observing" | "discriminating" | "deciding" | "verifying";
+    selected?: string;
+}
+export declare const LayerOrder: readonly DiagnosticLayer[];
+export declare const clamp01: (value: number) => number;

package/lib/diagnosis/types.js

@@ -0,0 +1,2 @@
+export const LayerOrder = ["thread_pool", "connection_pool", "connect", "database", "queue", "application", "release"];
+export const clamp01 = (value) => Math.max(0, Math.min(1, value));

package/lib/error/agentError.d.ts

@@ -0,0 +1,9 @@
+import type { AgentErrorCode } from "../process/agent.js";
+/**
+ * Domain error for the agent facets; never a database error.
+ */
+export declare class AgentError extends Error {
+    readonly code: AgentErrorCode;
+    readonly details: readonly string[];
+    constructor(code: AgentErrorCode, details?: readonly string[]);
+}

package/lib/error/agentError.js

@@ -0,0 +1,13 @@
+/**
+ * Domain error for the agent facets; never a database error.
+ */
+export class AgentError extends Error {
+    code;
+    details;
+    constructor(code, details = []) {
+        super(details.length === 0 ? code : `${code}: ${details.join("; ")}`);
+        this.name = "AgentError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/lib/error/ampError.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared base for AMP errors that carry a machine-readable code and every
+ * problem found in one attempt.
+ *
+ * Boundary rejections are the first user; other fail-closed paths can extend
+ * this without changing their own extra fields. The `code` stays narrow through
+ * the generic parameter, so `catch (error) { if (error instanceof BoundaryRejection) ... }`
+ * still sees a literal union.
+ */
+export declare class AmpError<Code extends string = string> extends Error {
+    readonly code: Code;
+    readonly problems: readonly string[];
+    constructor(name: string, code: Code, problems: readonly string[]);
+}

package/lib/error/ampError.js

@@ -0,0 +1,19 @@
+/**
+ * Shared base for AMP errors that carry a machine-readable code and every
+ * problem found in one attempt.
+ *
+ * Boundary rejections are the first user; other fail-closed paths can extend
+ * this without changing their own extra fields. The `code` stays narrow through
+ * the generic parameter, so `catch (error) { if (error instanceof BoundaryRejection) ... }`
+ * still sees a literal union.
+ */
+export class AmpError extends Error {
+    code;
+    problems;
+    constructor(name, code, problems) {
+        super(`${code}: ${problems.join("; ")}`);
+        this.name = name;
+        this.code = code;
+        this.problems = [...problems];
+    }
+}

package/lib/error/authzError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Authorization errors: a denied capability, or a grant that would amplify
+ * rights or lifetime. They share the `AmpError` shape so the kernel can turn
+ * any of them into a blocked receipt.
+ */
+import { AmpError } from "./ampError.js";
+export type AuthzCode = "permission_denied" | "invalid_grant" | "rights_amplification" | "expiry_amplification" | "unknown_capability";
+export declare class AuthzError extends AmpError<AuthzCode> {
+    constructor(code: AuthzCode, problems: readonly string[]);
+}