@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/decision-adapter.js

@@ -0,0 +1,586 @@
+import { randomUUID } from 'node:crypto';
+import { initializePersonalOs, loadPersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/** Public version of the adapter contract. It is independent from the old organization route. */
+export const DECISION_ADAPTER_VERSION = 'decision-adapter.v1';
+/** The sidecar contains references and compatibility metadata, never canonical definitions. */
+export const DECISION_ADAPTER_SIDECAR = 'evidence/decision-adapter.json';
+export class DecisionAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'DecisionAdapterError';
+        this.code = code;
+    }
+}
+/**
+ * Personal canonical implementation. It never creates a second Decision
+ * store: `decisions.jsonl` and the Graph entity remain the canonical records.
+ */
+export class GraphDecisionAdapterStore {
+    dataDir;
+    sidecarPath;
+    conditionValidator;
+    authorization;
+    constructor(options) {
+        if (!options.dataDir)
+            throw new DecisionAdapterError('validation_error', 'dataDir is required');
+        this.dataDir = options.dataDir;
+        this.sidecarPath = options.sidecarPath ?? DECISION_ADAPTER_SIDECAR;
+        assertSidecarPath(this.sidecarPath);
+        this.conditionValidator = options.conditionValidator;
+        this.authorization = options.authorization;
+    }
+    async createDecision(input, context) {
+        const request = normalizeDecisionRequest(input);
+        assertContext(context);
+        await initializePersonalOs(this.dataDir);
+        const decisionId = request.decision_id ?? `dec-${randomUUID()}`;
+        const eventId = `evt-${randomUUID()}`;
+        const now = new Date().toISOString();
+        const decision = omitUndefined({
+            id: decisionId,
+            title: request.title,
+            decision: request.decision,
+            topic: request.topic,
+            rationale: request.rationale,
+            effectiveAt: request.effectiveAt,
+            tags: request.tags === undefined ? undefined : [...request.tags],
+            updatedAt: now
+        });
+        const entity = omitUndefined({
+            id: decisionId,
+            type: 'decision',
+            name: request.title,
+            summary: request.decision,
+            tags: request.tags === undefined ? undefined : [...request.tags]
+        });
+        const snapshot = await this.loadSnapshot();
+        const sidecar = parseSidecar(snapshot.sidecarContent);
+        assertCreateDecisionState(snapshot.current, sidecar, decisionId);
+        // Trusted providers may read the SSOT. Run them before acquiring the
+        // mutation lock; the commit callback below only performs pure checks and
+        // the optimistic canonical/sidecar compare-and-swap.
+        await this.validateConditions(request.conditions, context);
+        await this.authorize({
+            action: 'create',
+            context,
+            current: snapshot.current,
+            decision,
+            graph_entity: entity
+        });
+        const result = await this.mutateSidecar((current, sidecarContent) => {
+            assertDecisionSnapshotUnchanged(snapshot, current, sidecarContent);
+            const currentSidecar = parseSidecar(sidecarContent);
+            assertCreateDecisionState(current, currentSidecar, decisionId);
+            if (current.graph.version !== 2) {
+                throw new DecisionAdapterError('graph_unsupported', 'New Decision writes require canonical Graph v2');
+            }
+            const stored = {
+                decision_id: decisionId,
+                conditions: clone(request.conditions),
+                created_at: now,
+                ai_logs: []
+            };
+            const nextSidecar = {
+                ...currentSidecar,
+                decisions: { ...currentSidecar.decisions, [decisionId]: stored }
+            };
+            const nextGraph = {
+                ...current.graph,
+                entities: [...current.graph.entities, entity]
+            };
+            const next = {
+                ...current,
+                decisions: [...current.decisions, decision],
+                graph: nextGraph
+            };
+            assertStagedDecision(next, serializeSidecar(nextSidecar), decisionId, request.conditions);
+            return {
+                next,
+                sidecarContent: serializeSidecar(nextSidecar),
+                result: { decision_id: decisionId, event_id: eventId }
+            };
+        });
+        return result;
+    }
+    async createAiDecisionLog(input, context) {
+        const request = normalizeAiDecisionLogRequest(input);
+        assertContext(context);
+        await initializePersonalOs(this.dataDir);
+        const aiDecisionId = `aid-${randomUUID()}`;
+        const eventId = `evt-${randomUUID()}`;
+        const now = new Date().toISOString();
+        const aiLog = omitUndefined({
+            ai_decision_id: aiDecisionId,
+            event_id: eventId,
+            summary: request.summary,
+            decision_type: request.decision_type,
+            rationale: request.rationale,
+            confidence: request.confidence,
+            related_entity_id: request.related_entity_id,
+            references: request.references === undefined ? undefined : [...request.references],
+            conditions: clone(request.conditions),
+            created_at: now
+        });
+        const snapshot = await this.loadSnapshot();
+        const snapshotDecision = snapshot.current.decisions.find((candidate) => candidate.id === request.decision_id);
+        if (!snapshotDecision) {
+            throw new DecisionAdapterError('decision_not_found', `Decision ${request.decision_id} was not found`);
+        }
+        if (snapshot.current.graph.version !== 2) {
+            throw new DecisionAdapterError('graph_unsupported', 'AI decision-log writes require canonical Graph v2');
+        }
+        const snapshotGraphEntity = snapshot.current.graph.entities.find((candidate) => candidate.id === request.decision_id);
+        if (!snapshotGraphEntity || snapshotGraphEntity.type !== 'decision') {
+            throw new DecisionAdapterError('readback_mismatch', `Canonical Graph entity ${request.decision_id} is missing`);
+        }
+        const snapshotSidecar = parseSidecar(snapshot.sidecarContent);
+        const snapshotExisting = snapshotSidecar.decisions[request.decision_id];
+        if (snapshotExisting && !sameConditions(snapshotExisting.conditions, request.conditions)) {
+            throw new DecisionAdapterError('condition_unavailable', `Decision ${request.decision_id} has different recorded conditions`);
+        }
+        // Trusted providers may read the SSOT. They must complete before the
+        // mutation lock is acquired; the callback below is intentionally pure.
+        await this.validateConditions(request.conditions, context);
+        await this.authorize({
+            action: 'create',
+            context,
+            current: snapshot.current,
+            decision: snapshotDecision,
+            graph_entity: snapshotGraphEntity
+        });
+        const result = await this.mutateSidecar((current, sidecarContent) => {
+            assertDecisionSnapshotUnchanged(snapshot, current, sidecarContent);
+            const decision = current.decisions.find((candidate) => candidate.id === request.decision_id);
+            if (!decision) {
+                throw new DecisionAdapterError('decision_not_found', `Decision ${request.decision_id} was not found`);
+            }
+            if (current.graph.version !== 2) {
+                throw new DecisionAdapterError('graph_unsupported', 'AI decision-log writes require canonical Graph v2');
+            }
+            const graphEntity = current.graph.entities.find((candidate) => candidate.id === request.decision_id);
+            if (!graphEntity || graphEntity.type !== 'decision') {
+                throw new DecisionAdapterError('readback_mismatch', `Canonical Graph entity ${request.decision_id} is missing`);
+            }
+            const sidecar = parseSidecar(sidecarContent);
+            const existing = sidecar.decisions[request.decision_id];
+            if (existing && !sameConditions(existing.conditions, request.conditions)) {
+                throw new DecisionAdapterError('condition_unavailable', `Decision ${request.decision_id} has different recorded conditions`);
+            }
+            const stored = existing ?? {
+                decision_id: request.decision_id,
+                conditions: clone(request.conditions),
+                created_at: now,
+                ai_logs: []
+            };
+            const nextStored = {
+                ...stored,
+                ai_logs: [...stored.ai_logs, aiLog]
+            };
+            const nextSidecar = {
+                ...sidecar,
+                decisions: { ...sidecar.decisions, [request.decision_id]: nextStored }
+            };
+            assertStagedAiDecisionLog(current, serializeSidecar(nextSidecar), request.decision_id, aiDecisionId, request.conditions);
+            return {
+                next: current,
+                sidecarContent: serializeSidecar(nextSidecar),
+                result: { ai_decision_id: aiDecisionId, event_id: eventId }
+            };
+        });
+        return result;
+    }
+    async readDecision(input, context) {
+        const decisionId = normalizeIdentifier(input?.decision_id, 'decision_id');
+        assertContext(context);
+        await initializePersonalOs(this.dataDir);
+        const current = await this.loadCurrent();
+        const decision = current.decisions.find((candidate) => candidate.id === decisionId);
+        if (!decision)
+            throw new DecisionAdapterError('decision_not_found', `Decision ${decisionId} was not found`);
+        const graphEntity = current.graph.version === 2
+            ? current.graph.entities.find((candidate) => candidate.id === decisionId)
+            : undefined;
+        if (graphEntity && graphEntity.type !== 'decision') {
+            throw new DecisionAdapterError('store_corrupt', `Canonical Graph ID ${decisionId} is not a Decision`);
+        }
+        await this.authorize({ action: 'read', context, current, decision, graph_entity: graphEntity });
+        const sidecar = parseSidecar(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
+        const stored = sidecar.decisions[decisionId];
+        if (!stored) {
+            return {
+                decision: clone(decision),
+                ...(graphEntity ? { graph_entity: clone(graphEntity) } : {}),
+                condition_status: 'unrecorded',
+                authority_status: 'unrecorded',
+                ai_logs: []
+            };
+        }
+        validateStoredDecision(stored, decisionId);
+        await this.validateConditions(stored.conditions, context);
+        return {
+            decision: clone(decision),
+            ...(graphEntity ? { graph_entity: clone(graphEntity) } : {}),
+            condition_status: 'recorded',
+            conditions: clone(stored.conditions),
+            authority_status: 'unrecorded',
+            ai_logs: stored.ai_logs.map(clone)
+        };
+    }
+    async mutateSidecar(mutator) {
+        try {
+            return await mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, mutator);
+        }
+        catch (error) {
+            if (error instanceof DecisionAdapterError)
+                throw error;
+            throw new DecisionAdapterError('store_corrupt', formatError(error));
+        }
+    }
+    async loadCurrent() {
+        try {
+            return await loadPersonalOs(this.dataDir);
+        }
+        catch (error) {
+            throw new DecisionAdapterError('store_corrupt', formatError(error));
+        }
+    }
+    async loadSnapshot() {
+        try {
+            return {
+                current: await loadPersonalOs(this.dataDir),
+                sidecarContent: await readPersonalOsSidecar(this.dataDir, this.sidecarPath)
+            };
+        }
+        catch (error) {
+            throw new DecisionAdapterError('store_corrupt', formatError(error));
+        }
+    }
+    async validateConditions(conditions, context) {
+        validateDecisionAdapterConditions(conditions);
+        if (!this.conditionValidator)
+            return;
+        try {
+            const allowed = await this.conditionValidator.validate({ conditions: clone(conditions), context });
+            if (allowed === false) {
+                throw new DecisionAdapterError('condition_unavailable', 'A trusted condition provider denied the references');
+            }
+        }
+        catch (error) {
+            if (error instanceof DecisionAdapterError)
+                throw error;
+            throw new DecisionAdapterError('condition_unavailable', formatError(error));
+        }
+    }
+    async authorize(request) {
+        assertContext(request.context);
+        if (this.authorization) {
+            try {
+                const allowed = await this.authorization.authorize({
+                    ...request,
+                    current: clone(request.current),
+                    ...(request.decision ? { decision: clone(request.decision) } : {}),
+                    ...(request.graph_entity ? { graph_entity: clone(request.graph_entity) } : {})
+                });
+                if (allowed === false) {
+                    throw new DecisionAdapterError('authorization_denied', 'Decision adapter policy denied the operation');
+                }
+            }
+            catch (error) {
+                if (error instanceof DecisionAdapterError)
+                    throw error;
+                throw new DecisionAdapterError('authorization_denied', formatError(error));
+            }
+            return;
+        }
+        const ownerId = request.current.graph.version === 2 ? request.current.graph.owner?.id : undefined;
+        if (ownerId && ownerId !== request.context.principal) {
+            throw new DecisionAdapterError('authorization_denied', 'The personal canonical Graph owner denied the operation');
+        }
+    }
+}
+export function createDecisionAdapter(options) {
+    return new GraphDecisionAdapterStore(options);
+}
+export const createGraphDecisionAdapter = createDecisionAdapter;
+export function validateDecisionAdapterConditions(value) {
+    if (!value || typeof value !== 'object') {
+        throw new DecisionAdapterError('validation_error', 'conditions are required');
+    }
+    const conditions = value;
+    const snapshot = conditions.problem_snapshot;
+    if (!snapshot || typeof snapshot !== 'object') {
+        throw new DecisionAdapterError('validation_error', 'conditions.problem_snapshot is required');
+    }
+    const snapshotRecord = snapshot;
+    const snapshotId = normalizeIdentifier(snapshotRecord.snapshot_id, 'conditions.problem_snapshot.snapshot_id');
+    if (!/^sha256:[0-9a-f]{64}$/u.test(snapshotId)) {
+        throw new DecisionAdapterError('validation_error', 'conditions.problem_snapshot.snapshot_id must be sha256:<64 lowercase hex>');
+    }
+    normalizeIdentifier(snapshotRecord.problem_id, 'conditions.problem_snapshot.problem_id');
+    assertRevision(snapshotRecord.revision, 'conditions.problem_snapshot.revision');
+    const method = conditions.method;
+    if (!method || typeof method !== 'object') {
+        throw new DecisionAdapterError('validation_error', 'conditions.method is required');
+    }
+    const methodRecord = method;
+    normalizeIdentifier(methodRecord.id, 'conditions.method.id');
+    normalizeIdentifier(methodRecord.version, 'conditions.method.version');
+    if (!Array.isArray(conditions.objective_refs) || conditions.objective_refs.length === 0) {
+        throw new DecisionAdapterError('validation_error', 'conditions.objective_refs must contain at least one Objective revision');
+    }
+    const seen = new Set();
+    for (const [index, ref] of conditions.objective_refs.entries()) {
+        if (!ref || typeof ref !== 'object') {
+            throw new DecisionAdapterError('validation_error', `conditions.objective_refs[${index}] must be an object`);
+        }
+        const record = ref;
+        const id = normalizeIdentifier(record.id, `conditions.objective_refs[${index}].id`);
+        if (record.type !== 'objective') {
+            throw new DecisionAdapterError('validation_error', `conditions.objective_refs[${index}].type must be objective`);
+        }
+        const revision = assertRevision(record.revision, `conditions.objective_refs[${index}].revision`);
+        const key = `${id}@${revision}`;
+        if (seen.has(key))
+            throw new DecisionAdapterError('validation_error', `Duplicate Objective reference ${key}`);
+        seen.add(key);
+    }
+}
+function normalizeDecisionRequest(input) {
+    if (!input || typeof input !== 'object')
+        throw new DecisionAdapterError('validation_error', 'Decision request is required');
+    const request = input;
+    return {
+        ...(request.decision_id === undefined ? {} : { decision_id: normalizeIdentifier(request.decision_id, 'decision_id') }),
+        title: normalizeText(request.title, 'title'),
+        decision: normalizeText(request.decision, 'decision'),
+        ...(request.topic === undefined ? {} : { topic: normalizeText(request.topic, 'topic') }),
+        ...(request.rationale === undefined ? {} : { rationale: normalizeText(request.rationale, 'rationale', 8_192) }),
+        ...(request.effectiveAt === undefined ? {} : { effectiveAt: normalizeTimestamp(request.effectiveAt, 'effectiveAt') }),
+        ...(request.tags === undefined ? {} : { tags: normalizeStringArray(request.tags, 'tags') }),
+        conditions: normalizeConditions(request.conditions)
+    };
+}
+function normalizeAiDecisionLogRequest(input) {
+    if (!input || typeof input !== 'object')
+        throw new DecisionAdapterError('validation_error', 'AI decision-log request is required');
+    const request = input;
+    const decisionId = request.decision_id === undefined
+        ? request.related_decision_id
+        : request.related_decision_id === undefined
+            ? request.decision_id
+            : normalizeIdentifier(request.decision_id, 'decision_id') === normalizeIdentifier(request.related_decision_id, 'related_decision_id')
+                ? request.decision_id
+                : undefined;
+    if (decisionId === undefined)
+        throw new DecisionAdapterError('validation_error', 'decision_id or related_decision_id is required and must match');
+    return {
+        decision_id: normalizeIdentifier(decisionId, 'decision_id'),
+        summary: normalizeText(request.summary, 'summary'),
+        ...(request.decision_type === undefined ? {} : { decision_type: normalizeText(request.decision_type, 'decision_type') }),
+        ...(request.rationale === undefined ? {} : { rationale: normalizeText(request.rationale, 'rationale', 8_192) }),
+        ...(request.confidence === undefined ? {} : { confidence: normalizeConfidence(request.confidence) }),
+        ...(request.related_entity_id === undefined ? {} : { related_entity_id: normalizeIdentifier(request.related_entity_id, 'related_entity_id') }),
+        ...(request.references === undefined ? {} : { references: normalizeStringArray(request.references, 'references') }),
+        conditions: normalizeConditions(request.conditions)
+    };
+}
+function normalizeConditions(value) {
+    if (!value || typeof value !== 'object')
+        throw new DecisionAdapterError('validation_error', 'conditions are required');
+    const input = value;
+    const snapshot = input.problem_snapshot;
+    const method = input.method;
+    const objectives = input.objective_refs;
+    const normalized = {
+        problem_snapshot: {
+            snapshot_id: String(snapshot?.snapshot_id ?? ''),
+            problem_id: String(snapshot?.problem_id ?? ''),
+            revision: String(snapshot?.revision ?? '')
+        },
+        method: {
+            id: String(method?.id ?? ''),
+            version: String(method?.version ?? '')
+        },
+        objective_refs: Array.isArray(objectives)
+            ? objectives.map((ref) => {
+                const record = ref;
+                return {
+                    id: String(record?.id ?? ''),
+                    type: 'objective',
+                    revision: String(record?.revision ?? '')
+                };
+            })
+            : []
+    };
+    validateDecisionAdapterConditions(normalized);
+    return normalized;
+}
+function normalizeText(value, field, max = 2_048) {
+    if (typeof value !== 'string')
+        throw new DecisionAdapterError('validation_error', `${field} is required`);
+    const normalized = value.normalize('NFKC').trim();
+    if (!normalized || normalized.length > max || /[\u0000-\u001f\u007f-\u009f]/u.test(normalized)) {
+        throw new DecisionAdapterError('validation_error', `${field} must be bounded text`);
+    }
+    return normalized;
+}
+function normalizeIdentifier(value, field) {
+    return normalizeText(value, field, 512);
+}
+function assertRevision(value, field) {
+    const revision = normalizeIdentifier(value, field);
+    if (!/^[1-9][0-9]*$/u.test(revision)) {
+        throw new DecisionAdapterError('validation_error', `${field} must be a positive decimal revision`);
+    }
+    return revision;
+}
+function normalizeTimestamp(value, field) {
+    const timestamp = normalizeText(value, field, 64);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new DecisionAdapterError('validation_error', `${field} must be an ISO timestamp`);
+    return timestamp;
+}
+function normalizeStringArray(value, field) {
+    if (!Array.isArray(value))
+        throw new DecisionAdapterError('validation_error', `${field} must be an array`);
+    return value.map((entry, index) => normalizeText(entry, `${field}[${index}]`, 512));
+}
+function normalizeConfidence(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new DecisionAdapterError('validation_error', 'confidence must be a number between 0 and 1');
+    }
+    return value;
+}
+function assertContext(context) {
+    normalizeIdentifier(context?.principal, 'context.principal');
+}
+function assertSidecarPath(path) {
+    if (!path || path.startsWith('/') || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new DecisionAdapterError('validation_error', 'sidecarPath must remain relative to the SSOT root');
+    }
+}
+function parseSidecar(content) {
+    if (content === undefined || content.trim() === '')
+        return { version: DECISION_ADAPTER_VERSION, decisions: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new DecisionAdapterError('store_corrupt', `Decision adapter sidecar is not valid JSON: ${formatError(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new DecisionAdapterError('store_corrupt', 'Decision adapter sidecar must be an object');
+    }
+    const value = parsed;
+    if (value.version !== DECISION_ADAPTER_VERSION || !value.decisions || typeof value.decisions !== 'object' || Array.isArray(value.decisions)) {
+        throw new DecisionAdapterError('store_corrupt', 'Decision adapter sidecar has an unsupported schema');
+    }
+    const decisions = {};
+    for (const [key, candidate] of Object.entries(value.decisions)) {
+        validateStoredDecision(candidate, key);
+        decisions[key] = clone(candidate);
+    }
+    return { version: DECISION_ADAPTER_VERSION, decisions };
+}
+function validateStoredDecision(value, key) {
+    if (!value || typeof value !== 'object' || value.decision_id !== key) {
+        throw new DecisionAdapterError('store_corrupt', `Decision adapter sidecar entry ${key} has an invalid ID`);
+    }
+    validateDecisionAdapterConditions(value.conditions);
+    normalizeTimestamp(value.created_at, `decisions.${key}.created_at`);
+    if (!Array.isArray(value.ai_logs))
+        throw new DecisionAdapterError('store_corrupt', `Decision adapter sidecar entry ${key} has invalid ai_logs`);
+    const ids = new Set();
+    for (const log of value.ai_logs) {
+        if (!log || typeof log !== 'object')
+            throw new DecisionAdapterError('store_corrupt', `Decision adapter sidecar entry ${key} has an invalid AI log`);
+        normalizeIdentifier(log.ai_decision_id, 'ai_decision_id');
+        normalizeIdentifier(log.event_id, 'event_id');
+        normalizeText(log.summary, 'summary');
+        if (log.decision_type !== undefined)
+            normalizeText(log.decision_type, 'decision_type');
+        if (log.rationale !== undefined)
+            normalizeText(log.rationale, 'rationale', 8_192);
+        if (log.confidence !== undefined)
+            normalizeConfidence(log.confidence);
+        if (log.related_entity_id !== undefined)
+            normalizeIdentifier(log.related_entity_id, 'related_entity_id');
+        if (log.references !== undefined)
+            normalizeStringArray(log.references, 'references');
+        validateDecisionAdapterConditions(log.conditions);
+        if (!sameConditions(log.conditions, value.conditions)) {
+            throw new DecisionAdapterError('store_corrupt', `AI log ${log.ai_decision_id} has conditions different from ${key}`);
+        }
+        normalizeTimestamp(log.created_at, 'created_at');
+        if (ids.has(log.ai_decision_id))
+            throw new DecisionAdapterError('store_corrupt', `Duplicate AI log ${log.ai_decision_id}`);
+        ids.add(log.ai_decision_id);
+    }
+}
+function assertCreateDecisionState(current, sidecar, decisionId) {
+    if (current.graph.version !== 2) {
+        throw new DecisionAdapterError('graph_unsupported', 'New Decision writes require canonical Graph v2');
+    }
+    if (current.decisions.some((candidate) => candidate.id === decisionId)
+        || current.graph.entities.some((candidate) => candidate.id === decisionId)) {
+        throw new DecisionAdapterError('decision_conflict', `Decision ${decisionId} already exists`);
+    }
+    if (Object.prototype.hasOwnProperty.call(sidecar.decisions, decisionId)) {
+        throw new DecisionAdapterError('decision_conflict', `Decision sidecar entry ${decisionId} already exists`);
+    }
+}
+function assertDecisionSnapshotUnchanged(snapshot, current, sidecarContent) {
+    if (!sameCanonicalAggregate(snapshot.current, current) || snapshot.sidecarContent !== sidecarContent) {
+        throw new DecisionAdapterError('decision_conflict', 'Canonical Decision aggregate or sidecar changed while trusted references were being validated');
+    }
+}
+function sameCanonicalAggregate(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function assertStagedDecision(next, sidecarContent, decisionId, expectedConditions) {
+    assertStagedCanonicalDecision(next, decisionId);
+    const sidecar = parseSidecar(sidecarContent);
+    const stored = sidecar.decisions[decisionId];
+    if (!stored || !sameConditions(stored.conditions, expectedConditions)) {
+        throw new DecisionAdapterError('readback_mismatch', `Staged Decision ${decisionId} does not contain its canonical references`);
+    }
+}
+function assertStagedAiDecisionLog(next, sidecarContent, decisionId, aiDecisionId, expectedConditions) {
+    assertStagedCanonicalDecision(next, decisionId);
+    const sidecar = parseSidecar(sidecarContent);
+    const stored = sidecar.decisions[decisionId];
+    const log = stored?.ai_logs.find((candidate) => candidate.ai_decision_id === aiDecisionId);
+    if (!stored || !log || !sameConditions(stored.conditions, expectedConditions) || !sameConditions(log.conditions, expectedConditions)) {
+        throw new DecisionAdapterError('readback_mismatch', `Staged AI decision-log ${aiDecisionId} is not attached to ${decisionId}`);
+    }
+}
+function assertStagedCanonicalDecision(next, decisionId) {
+    if (next.graph.version !== 2) {
+        throw new DecisionAdapterError('readback_mismatch', `Staged canonical Graph ${decisionId} is not Graph v2`);
+    }
+    const decision = next.decisions.find((candidate) => candidate.id === decisionId);
+    const graphEntity = next.graph.entities.find((candidate) => candidate.id === decisionId);
+    if (!decision || !graphEntity || graphEntity.type !== 'decision') {
+        throw new DecisionAdapterError('readback_mismatch', `Staged canonical Decision ${decisionId} is incomplete`);
+    }
+}
+function serializeSidecar(sidecar) {
+    return `${JSON.stringify({
+        version: DECISION_ADAPTER_VERSION,
+        decisions: Object.fromEntries(Object.entries(sidecar.decisions).sort(([left], [right]) => left.localeCompare(right, 'en')))
+    }, null, 2)}\n`;
+}
+function sameConditions(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, candidate]) => candidate !== undefined));
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/durable-wait-http.d.ts

@@ -0,0 +1,51 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { type DurableWaitStore } from './durable-waits.js';
+/** Version of the HTTP boundary. The store version is returned separately. */
+export declare const DURABLE_WAIT_HTTP_VERSION: "durable-wait-http.v1";
+type MaybePromise<T> = T | Promise<T>;
+/** Context resolved by the host after authentication and tenant selection. */
+export interface TrustedDurableWaitRequestContext {
+    readonly tenantId: string;
+    readonly principal: string;
+    readonly scopeId: string;
+    /** A non-empty value means that the host already verified the mutation origin. */
+    readonly verifiedMutationOrigin?: string;
+}
+/** A host creates the store with current ACL and Problem snapshot providers. */
+export type DurableWaitStoreFactory = (context: TrustedDurableWaitRequestContext) => MaybePromise<DurableWaitStore>;
+export interface DurableWaitMutationVerificationInput {
+    readonly request: IncomingMessage;
+    readonly context: TrustedDurableWaitRequestContext;
+}
+export interface DurableWaitHttpOptions {
+    readonly storeFactory: DurableWaitStoreFactory;
+    readonly basePath?: string;
+    readonly bodyLimitBytes?: number;
+    /** Required for hosts that do not attach verifiedMutationOrigin to context. */
+    readonly verifyMutationRequest?: (input: DurableWaitMutationVerificationInput) => MaybePromise<boolean>;
+}
+/**
+ * The smallest canonical Node host composition for this transport.
+ *
+ * Authentication and tenant/scope resolution remain host-owned.  The resolver
+ * must return a context only after those checks have completed; a missing or
+ * failed resolution is deliberately passed to the handler as an unauthenticated
+ * request.  This helper only mounts the canonical handler and never infers
+ * identity from request headers or body fields.
+ */
+export interface DurableWaitHttpHostOptions extends DurableWaitHttpOptions {
+    readonly resolveContext: (request: IncomingMessage) => MaybePromise<TrustedDurableWaitRequestContext | null>;
+}
+/** A composable route handler. `false` means that another host route may handle it. */
+export type DurableWaitHttpHandler = (request: IncomingMessage, response: ServerResponse, context: TrustedDurableWaitRequestContext | null) => Promise<boolean>;
+export declare function createDurableWaitHttpHandler(options: DurableWaitHttpOptions): DurableWaitHttpHandler;
+/**
+ * Create a startable Node HTTP host around the canonical handler.
+ *
+ * The caller owns `server.listen()` and the authentication implementation.
+ * A route outside the durable-wait base path is answered with a generic 404 so
+ * a standalone fixture cannot leave the request hanging; larger hosts can use
+ * `createDurableWaitHttpHandler` directly when they need route delegation.
+ */
+export declare function createDurableWaitHttpHost(options: DurableWaitHttpHostOptions): Server;
+export {};