@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/knowledge/judgments.js

@@ -0,0 +1,808 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JudgmentError = void 0;
+exports.judgmentRecordId = judgmentRecordId;
+exports.admittedScopeIds = admittedScopeIds;
+exports.boundScopeIdsFor = boundScopeIdsFor;
+exports.appendJudgment = appendJudgment;
+exports.createJudgmentWriter = createJudgmentWriter;
+exports.mapTwinEdgeRow = mapTwinEdgeRow;
+exports.insertTwinEdge = insertTwinEdge;
+exports.getTwinEdge = getTwinEdge;
+exports.listTwinEdgesForRefs = listTwinEdgesForRefs;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const db_manager_js_1 = require("../db-manager.js");
+const canonicalize_js_1 = require("../canonicalize.js");
+const twin_edge_types_js_1 = require("./twin-edge-types.js");
+const event_store_js_1 = require("../memory/event-store.js");
+const record_identity_js_1 = require("../registry/record-identity.js");
+class JudgmentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'JudgmentError';
+    }
+}
+exports.JudgmentError = JudgmentError;
+function commandHash(command) {
+    return node_crypto_1.default.createHash('sha256').update((0, canonicalize_js_1.canonicalizeJSON)(command)).digest('hex');
+}
+function recordIdForCommand(command) {
+    return judgmentRecordId(command.commandId);
+}
+/** Deterministic record id a command will be bound to — lets adapters build
+ * projections (timeline events, identity bindings) before the write commits. */
+function judgmentRecordId(commandId) {
+    return `judgment_${node_crypto_1.default.createHash('sha256').update(commandId).digest('hex').slice(0, 24)}`;
+}
+function commitmentIdForCommand(command) {
+    return `commitment_${node_crypto_1.default
+        .createHash('sha256')
+        .update(command.commandId)
+        .digest('hex')
+        .slice(0, 24)}`;
+}
+function requireText(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new JudgmentError('INVALID_COMMAND', `${field} must be nonblank`);
+    }
+}
+function scopeIdFor(scope) {
+    return `scope_${scope.kind}_${Buffer.from(scope.id).toString('base64url')}`;
+}
+function scopeKey(scope) {
+    return `${scope.kind}\0${scope.id}`;
+}
+/** Scopes the caller was admitted to; bounds what the command may reference.
+ * Exported for the sibling source-ingest command path; not part of the public API. */
+function admittedScopeIds(access) {
+    const seen = new Set();
+    return access.scopes.map((scope) => {
+        requireText(scope.kind, 'scope kind');
+        requireText(scope.id, 'scope id');
+        const key = scopeKey(scope);
+        if (seen.has(key)) {
+            throw new JudgmentError('INVALID_SCOPE', 'Access scopes must be unique');
+        }
+        seen.add(key);
+        return scopeIdFor(scope);
+    });
+}
+/**
+ * Scopes bound to the new record. An explicit `scopes: []` declares an
+ * unscoped record (legacy parity); an omitted field inherits the access scope.
+ * Exported for the sibling source-ingest command path; not part of the public API.
+ */
+function boundScopeIdsFor(access, command) {
+    const scopes = command.scopes ?? access.scopes;
+    if (command.scopes === undefined && scopes.length === 0) {
+        throw new JudgmentError('INVALID_SCOPE', 'At least one judgment scope is required');
+    }
+    const admitted = new Set(access.scopes.map(scopeKey));
+    const seen = new Set();
+    return scopes.map((scope) => {
+        // A kind is nonblank text. Which kinds exist is the writer's statement; this
+        // compared against a list the core kept, so a consumer whose world had a kind
+        // of its own could not append a judgment at all.
+        requireText(scope.kind, 'scope kind');
+        requireText(scope.id, 'scope id');
+        const key = scopeKey(scope);
+        if (seen.has(key)) {
+            throw new JudgmentError('INVALID_SCOPE', 'Judgment scopes must be unique');
+        }
+        seen.add(key);
+        if (!admitted.has(key)) {
+            throw new JudgmentError('SCOPE_DENIED', 'Judgment scope is outside the admitted access');
+        }
+        return scopeIdFor(scope);
+    });
+}
+function validateBounds(command) {
+    for (const [name, value] of [
+        ['appliesFrom', command.appliesFrom],
+        ['appliesUntil', command.appliesUntil],
+    ]) {
+        if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+            throw new JudgmentError('INVALID_TIME', `${name} must be a finite nonnegative epoch`);
+        }
+    }
+    if (command.appliesFrom !== undefined &&
+        command.appliesUntil !== undefined &&
+        command.appliesFrom > command.appliesUntil) {
+        throw new JudgmentError('INVALID_TIME', 'appliesFrom cannot be after appliesUntil');
+    }
+}
+const AMEND_FIELDS = [
+    'outcome',
+    'failureReason',
+    'limitation',
+    'status',
+    'confidence',
+    'durationDays',
+    'supersedes',
+    'supersededBy',
+];
+/** Public-save parity fields carried by the command are validated up front so a
+ * malformed command fails before any write or embedder call. */
+function validateCommandFields(command) {
+    if (command.confidence !== undefined &&
+        (!Number.isFinite(command.confidence) || command.confidence < 0 || command.confidence > 1)) {
+        throw new JudgmentError('INVALID_COMMAND', 'confidence must be a number between 0 and 1');
+    }
+    if (command.eventDate !== undefined && command.eventDate !== null) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(command.eventDate) ||
+            Number.isNaN(new Date(command.eventDate).getTime())) {
+            throw new JudgmentError('INVALID_TIME', `eventDate must be ISO 8601 YYYY-MM-DD (got: ${command.eventDate})`);
+        }
+    }
+    if (command.eventDatetime !== undefined && command.eventDatetime !== null) {
+        if (!Number.isFinite(command.eventDatetime) || command.eventDatetime <= 0) {
+            throw new JudgmentError('INVALID_TIME', `eventDatetime must be a positive millisecond timestamp (got: ${command.eventDatetime})`);
+        }
+    }
+    if (command.recordedAt !== undefined &&
+        (!Number.isFinite(command.recordedAt) || command.recordedAt < 0)) {
+        throw new JudgmentError('INVALID_TIME', 'recordedAt must be a finite nonnegative epoch');
+    }
+    if (command.sourceRefs !== undefined &&
+        (!Array.isArray(command.sourceRefs) ||
+            command.sourceRefs.some((ref) => typeof ref !== 'string' || ref.length === 0))) {
+        throw new JudgmentError('INVALID_COMMAND', 'sourceRefs must be an array of nonblank strings');
+    }
+    for (const amendment of command.amends ?? []) {
+        if (amendment.target?.kind !== 'memory') {
+            throw new JudgmentError('INVALID_COMMAND', 'amends targets must be memory references');
+        }
+        requireText(amendment.target.id, 'amends target id');
+        if (!AMEND_FIELDS.some((field) => field in amendment)) {
+            throw new JudgmentError('INVALID_COMMAND', 'amends requires at least one projection field to set');
+        }
+    }
+    for (const edge of command.projections?.decisionEdges ?? []) {
+        if (edge.fromId !== undefined) {
+            requireText(edge.fromId, 'projection edge source');
+        }
+        requireText(edge.targetId, 'projection edge target');
+        requireText(edge.relationship, 'projection edge relationship');
+    }
+}
+function referenceExists(adapter, reference, admittedScopeIds) {
+    if (reference.kind === 'memory') {
+        const row = adapter
+            .prepare(`SELECT (SELECT COUNT(*) FROM memory_scope_bindings b WHERE b.memory_id = d.id) AS bindings
+         FROM decisions d WHERE d.id = ?`)
+            .get(reference.id);
+        if (!row)
+            return false;
+        // A record with no scope bindings has no partition boundary to violate.
+        if (row.bindings === 0)
+            return true;
+        if (admittedScopeIds.length === 0)
+            return false;
+        const placeholders = admittedScopeIds.map(() => '?').join(', ');
+        return (adapter
+            .prepare(`SELECT 1 FROM decisions d
+           JOIN memory_scope_bindings b ON b.memory_id = d.id
+           WHERE d.id = ? AND b.scope_id IN (${placeholders}) LIMIT 1`)
+            .get(reference.id, ...admittedScopeIds) !== undefined);
+    }
+    if (reference.kind === 'registry') {
+        const node = adapter.prepare('SELECT 1 FROM registry_nodes WHERE id = ?').get(reference.id) !== undefined;
+        if (!node)
+            return false;
+        const bindings = adapter
+            .prepare('SELECT scope_kind, scope_id FROM registry_scope_bindings WHERE node_id = ?')
+            .all(reference.id);
+        return (bindings.length === 0 ||
+            bindings.some((binding) => admittedScopeIds.includes(`scope_${binding.scope_kind}_${Buffer.from(binding.scope_id).toString('base64url')}`)));
+    }
+    if (reference.kind === 'observation') {
+        return (adapter
+            .prepare('SELECT 1 FROM observation_versions WHERE observation_id = ?')
+            .get(reference.id) !== undefined);
+    }
+    if (reference.kind === 'edge') {
+        return (adapter.prepare('SELECT 1 FROM twin_edges WHERE edge_id = ?').get(reference.id) !== undefined);
+    }
+    return false;
+}
+function validateLinks(adapter, links, admittedScopeIds) {
+    const keys = new Set();
+    for (const link of links) {
+        requireText(link.relation, 'link relation');
+        requireText(link.target.id, 'link target id');
+        const attrs = link.attrs ?? {};
+        const key = (0, canonicalize_js_1.canonicalizeJSON)({
+            relation: link.relation,
+            target: link.target,
+            role: attrs.role ?? null,
+            slot: attrs.slot ?? null,
+        });
+        if (keys.has(key)) {
+            throw new JudgmentError('DUPLICATE_LINK', 'A judgment cannot repeat the same relation target slot');
+        }
+        keys.add(key);
+        if (!referenceExists(adapter, link.target, admittedScopeIds)) {
+            // Echo only the caller's own input: an unavailable id reads the same whether wrong or outside scope.
+            throw new JudgmentError('REFERENCE_NOT_FOUND', `A judgment reference is unavailable: ${link.target.kind} ${link.target.id}`);
+        }
+    }
+}
+function validateAmends(adapter, amends, admittedScopeIds) {
+    for (const amendment of amends) {
+        if (!referenceExists(adapter, amendment.target, admittedScopeIds)) {
+            throw new JudgmentError('REFERENCE_NOT_FOUND', 'An amendment target is unavailable');
+        }
+    }
+}
+function toColumnText(value) {
+    if (value === undefined || value === null)
+        return null;
+    return Array.isArray(value) ? JSON.stringify(value) : value;
+}
+const AMEND_COLUMN_MAP = {
+    outcome: 'outcome',
+    failureReason: 'failure_reason',
+    limitation: 'limitation',
+    status: 'status',
+    confidence: 'confidence',
+    durationDays: 'duration_days',
+    supersedes: 'supersedes',
+    supersededBy: 'superseded_by',
+};
+function applyAmendment(adapter, amendment, now) {
+    const sets = ['updated_at = ?'];
+    const params = [now];
+    for (const field of AMEND_FIELDS) {
+        if (field in amendment) {
+            sets.push(`${AMEND_COLUMN_MAP[field]} = ?`);
+            params.push(amendment[field] ?? null);
+        }
+    }
+    adapter
+        .prepare(`UPDATE decisions SET ${sets.join(', ')} WHERE id = ?`)
+        .run(...params, amendment.target.id);
+}
+function applyProjections(adapter, command, recordId, effectiveScopes, now) {
+    const projections = command.projections;
+    if (!projections)
+        return;
+    if (projections.recordIdentity) {
+        (0, record_identity_js_1.writeRecordIdentity)(adapter, {
+            recordId,
+            itemId: projections.recordIdentity.itemId,
+            actors: projections.recordIdentity.actors ?? [],
+            scopes: effectiveScopes,
+        });
+    }
+    for (const targetId of projections.supersedeTargets ?? []) {
+        adapter
+            .prepare("UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?")
+            .run(recordId, now, targetId);
+    }
+    const edgeInsert = adapter.prepare(`INSERT INTO decision_edges
+     (from_id, to_id, relationship, reason, weight, created_at, created_by, approved_by_user)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const edge of projections.decisionEdges ?? []) {
+        edgeInsert.run(edge.fromId ?? recordId, edge.targetId, edge.relationship, edge.reason ?? null, edge.weight ?? 1, now, edge.createdBy ?? 'user', edge.approvedByUser ?? 1);
+    }
+}
+function parseReceipt(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error('judgment_commands.receipt_json is malformed', { cause: error });
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('judgment_commands.receipt_json must contain an object');
+    }
+    return parsed;
+}
+function assertReplay(adapter, command, access, hash) {
+    const binding = adapter
+        .prepare('SELECT principal_id, action, payload_hash, receipt_key FROM command_bindings WHERE command_id = ?')
+        .get(command.commandId);
+    if (!binding)
+        return null;
+    if (binding.principal_id !== access.principalId ||
+        binding.action !== 'judgment.append' ||
+        binding.payload_hash !== hash) {
+        throw new JudgmentError('COMMAND_CONFLICT', 'The command id is already bound to another request');
+    }
+    const row = adapter
+        .prepare('SELECT receipt_json FROM judgment_commands WHERE command_id = ?')
+        .get(command.commandId);
+    if (!row) {
+        throw new Error('Command binding has no judgment receipt');
+    }
+    return parseReceipt(row.receipt_json);
+}
+function edgeId(commandId, index, relation, target) {
+    return `edge_${node_crypto_1.default
+        .createHash('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({ commandId, index, relation, target }))
+        .digest('hex')
+        .slice(0, 24)}`;
+}
+function insertLink(adapter, command, recordId, link, index, access, now) {
+    const id = edgeId(command.commandId, index, link.relation, link.target);
+    const attrs = link.attrs ?? {};
+    const contentHash = node_crypto_1.default
+        .createHash('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({ id, recordId, link }))
+        .digest();
+    insertTwinEdge(adapter, {
+        edge_id: id,
+        edge_type: link.relation,
+        subject_ref: { kind: 'memory', id: recordId },
+        object_ref: link.target,
+        relation_attrs: attrs,
+        confidence: 1.0,
+        source: access.edgeSource ?? 'agent',
+        agent_id: Object.hasOwn(command, 'agentId') ? (command.agentId ?? undefined) : access.agentId,
+        model_run_id: command.modelRunId ?? undefined,
+        reason_text: typeof link.attrs?.reason === 'string' ? link.attrs.reason : (command.reasoning ?? undefined),
+        evidence_refs: command.replaces?.length ? command.replaces : undefined,
+        content_hash: contentHash,
+        created_at: now,
+    });
+    return id;
+}
+function workPatch(value) {
+    return value?.set ?? {};
+}
+async function appendJudgmentOnAdapter(adapter, command, access, embedder) {
+    requireText(command.commandId, 'commandId');
+    requireText(command.topic, 'topic');
+    requireText(command.summary, 'summary');
+    requireText(access.principalId, 'principalId');
+    requireText(access.agentId, 'agentId');
+    if (command.recordKind !== 'judgment' && command.recordKind !== 'commitment') {
+        throw new JudgmentError('INVALID_COMMAND', 'recordKind is invalid');
+    }
+    if ((command.recordKind === 'commitment') !== (command.work !== undefined)) {
+        throw new JudgmentError('INVALID_COMMAND', 'Commitment records require a work assignment');
+    }
+    validateBounds(command);
+    validateCommandFields(command);
+    const admittedScopeIdList = admittedScopeIds(access);
+    const boundScopeIdList = boundScopeIdsFor(access, command);
+    const effectiveScopes = command.scopes ?? [...access.scopes];
+    const effectiveCommand = command.scopes ? command : { ...command, scopes: [...access.scopes] };
+    const hash = commandHash(effectiveCommand);
+    const replay = assertReplay(adapter, command, access, hash);
+    if (replay) {
+        validateLinks(adapter, command.links ?? [], admittedScopeIdList);
+        for (const replacement of command.replaces ?? []) {
+            if (!referenceExists(adapter, { kind: 'memory', id: replacement.id }, admittedScopeIdList)) {
+                throw new JudgmentError('REFERENCE_NOT_FOUND', 'A replacement target is unavailable');
+            }
+        }
+        validateAmends(adapter, command.amends ?? [], admittedScopeIdList);
+        return replay;
+    }
+    validateLinks(adapter, command.links ?? [], admittedScopeIdList);
+    validateAmends(adapter, command.amends ?? [], admittedScopeIdList);
+    const recordId = recordIdForCommand(command);
+    const now = Date.now();
+    const domainNow = command.recordedAt ?? now;
+    const embedding = embedder
+        ? await embedder.embed(`${command.topic}\n${command.summary}`, 'passage')
+        : null;
+    const edgeIds = [];
+    let workReceipt;
+    let replayedReceipt = null;
+    const transaction = adapter.transactionImmediate
+        ? adapter.transactionImmediate.bind(adapter)
+        : adapter.transaction.bind(adapter);
+    transaction(() => {
+        const bindingResult = adapter
+            .prepare(`INSERT OR IGNORE INTO command_bindings
+         (command_id, principal_id, action, payload_hash, receipt_kind, receipt_key, created_at)
+         VALUES (?, ?, 'judgment.append', ?, 'judgment', ?, ?)`)
+            .run(command.commandId, access.principalId, hash, recordId, now);
+        if (bindingResult.changes === 0) {
+            replayedReceipt = assertReplay(adapter, command, access, hash);
+            if (!replayedReceipt) {
+                throw new Error('Command binding was not readable after a conflict-free insert');
+            }
+            return;
+        }
+        const decisionRowId = (0, db_manager_js_1.insertPreparedDecision)(adapter, {
+            id: recordId,
+            topic: command.topic,
+            decision: command.summary,
+            reasoning: command.reasoning ?? null,
+            outcome: command.outcome ?? null,
+            failure_reason: command.failureReason ?? null,
+            limitation: command.limitation ?? null,
+            user_involvement: command.record?.userInvolvement ?? null,
+            session_id: command.record?.sessionId ?? null,
+            supersedes: command.replaces?.[0]?.id ?? command.record?.supersedes ?? null,
+            refined_from: command.record?.refinedFrom ?? null,
+            confidence: command.confidence ?? 0.5,
+            created_at: domainNow,
+            updated_at: now,
+            needs_validation: command.record?.needsValidation ?? 0,
+            trust_context: command.record?.trustContext ?? null,
+            evidence: toColumnText(command.evidence),
+            alternatives: toColumnText(command.alternatives),
+            risks: command.risks ?? null,
+            event_date: command.eventDate ?? null,
+            event_datetime: command.eventDatetime ?? null,
+            agent_id: Object.hasOwn(command, 'agentId') ? (command.agentId ?? null) : access.agentId,
+            model_run_id: command.modelRunId ?? null,
+            envelope_hash: command.envelopeHash ?? null,
+            gateway_call_id: command.gatewayCallId ?? null,
+            source_refs_json: command.sourceRefs ? (0, canonicalize_js_1.canonicalizeJSON)(command.sourceRefs) : null,
+            provenance_json: command.provenance ? (0, canonicalize_js_1.canonicalizeJSON)(command.provenance) : null,
+        }, embedding);
+        if (!Number.isSafeInteger(decisionRowId) || decisionRowId <= 0) {
+            throw new Error('Judgment decision row was not inserted');
+        }
+        adapter
+            .prepare(`UPDATE decisions
+         SET record_kind = ?, payload_json = ?, applies_from = ?, applies_until = ?,
+             kind = COALESCE(?, kind), status = COALESCE(?, status),
+             summary = COALESCE(?, summary), is_static = COALESCE(?, is_static)
+         WHERE id = ?`)
+            .run(command.recordKind, (0, canonicalize_js_1.canonicalizeJSON)(command.payload ?? {}), command.appliesFrom ?? null, command.appliesUntil ?? null, command.record?.kind ?? null, command.record?.status ?? null, 
+        // Never leave summary NULL: legacy readers (evolution candidates,
+        // recall) assume it is text. The command summary is the authored
+        // summary when the record does not carry a distinct one.
+        command.record?.summary ?? command.summary, command.record?.isStatic ?? null, recordId);
+        for (const [index, scopeId] of boundScopeIdList.entries()) {
+            const scope = effectiveScopes[index];
+            (0, db_manager_js_1.ensureMemoryScope)(adapter, scope.kind, scope.id);
+            adapter
+                .prepare('INSERT INTO memory_scope_bindings (memory_id, scope_id, is_primary) VALUES (?, ?, ?)')
+                .run(recordId, scopeId, index === 0 ? 1 : 0);
+        }
+        for (const [index, link] of (command.links ?? []).entries()) {
+            edgeIds.push(insertLink(adapter, command, recordId, link, index, access, now));
+        }
+        for (const replacement of command.replaces ?? []) {
+            if (!referenceExists(adapter, { kind: 'memory', id: replacement.id }, admittedScopeIdList)) {
+                throw new JudgmentError('REFERENCE_NOT_FOUND', 'A replacement target is unavailable');
+            }
+            adapter
+                .prepare("UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?")
+                .run(recordId, domainNow, replacement.id);
+            edgeIds.push(insertLink(adapter, { ...command, links: [] }, recordId, {
+                relation: 'supersedes',
+                target: { kind: 'memory', id: replacement.id },
+                attrs: { reason: replacement.reason },
+            }, edgeIds.length, access, now));
+        }
+        for (const amendment of command.amends ?? []) {
+            if (!referenceExists(adapter, amendment.target, admittedScopeIdList)) {
+                throw new JudgmentError('REFERENCE_NOT_FOUND', 'An amendment target is unavailable');
+            }
+            applyAmendment(adapter, amendment, domainNow);
+        }
+        applyProjections(adapter, command, recordId, effectiveScopes, domainNow);
+        // A commitment's own clock is domain time, like the record's: `updated_at`
+        // is what the board sorts and filters on, so a caller that states when a
+        // revision happened must see that time on the row, not the wall clock the
+        // write happened to land on.
+        if (command.recordKind === 'commitment' && command.work) {
+            const work = command.work;
+            if (work.operation === 'create') {
+                const commitmentId = commitmentIdForCommand(command);
+                const imported = work.imported;
+                if (imported !== undefined) {
+                    if (!Number.isSafeInteger(imported.rowId) || imported.rowId <= 0) {
+                        throw new JudgmentError('INVALID_COMMAND', `imported.rowId must be a positive integer (got: ${imported.rowId})`);
+                    }
+                    if (imported.revision !== undefined &&
+                        (!Number.isSafeInteger(imported.revision) || imported.revision <= 0)) {
+                        throw new JudgmentError('INVALID_COMMAND', `imported.revision must be a positive integer (got: ${imported.revision})`);
+                    }
+                    if (imported.createdAt !== undefined &&
+                        (!Number.isFinite(imported.createdAt) || imported.createdAt < 0)) {
+                        throw new JudgmentError('INVALID_COMMAND', `imported.createdAt must be a finite nonnegative epoch (got: ${imported.createdAt})`);
+                    }
+                }
+                const revision = imported?.revision ?? 1;
+                const createdAt = imported?.createdAt ?? domainNow;
+                if (imported !== undefined) {
+                    // An imported row keeps the task id it already had; sqlite_sequence
+                    // moves with the explicit insert, so work first stated here still
+                    // takes the next number after it.
+                    adapter
+                        .prepare(`INSERT INTO commitments
+               (row_id, commitment_id, current_revision, head_record_id, withdrawn, created_at, updated_at, agent_id, model_run_id)
+               VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?)`)
+                        .run(imported.rowId, commitmentId, revision, recordId, createdAt, domainNow, access.agentId, command.modelRunId ?? null);
+                }
+                else {
+                    adapter
+                        .prepare(`INSERT INTO commitments
+               (commitment_id, current_revision, head_record_id, withdrawn, created_at, updated_at, agent_id, model_run_id)
+               VALUES (?, ?, ?, 0, ?, ?, ?, ?)`)
+                        .run(commitmentId, revision, recordId, createdAt, domainNow, access.agentId, command.modelRunId ?? null);
+                }
+                adapter
+                    .prepare(`INSERT INTO commitment_assignments
+             (commitment_id, revision, record_id, operation, set_json, clear_json, applies_from, applies_until, created_at, agent_id, model_run_id)
+            VALUES (?, ?, ?, 'create', ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(commitmentId, revision, recordId, (0, canonicalize_js_1.canonicalizeJSON)(workPatch(work)), (0, canonicalize_js_1.canonicalizeJSON)(work.clear ?? []), command.eventDatetime ?? null, command.appliesUntil ?? null, domainNow, access.agentId, command.modelRunId ?? null);
+                workReceipt = { commitmentId, revision };
+            }
+            else {
+                const current = adapter
+                    .prepare('SELECT current_revision, withdrawn FROM commitments WHERE commitment_id = ?')
+                    .get(work.commitmentId);
+                if (!current) {
+                    throw new JudgmentError('REFERENCE_NOT_FOUND', `Commitment is unavailable: ${work.commitmentId}`);
+                }
+                // Only revise may omit the revision (it appends to the head); withdraw always states it.
+                if ((work.expectedRevision !== undefined || work.operation === 'withdraw') &&
+                    current.current_revision !== work.expectedRevision) {
+                    throw new JudgmentError('STALE_REVISION', 'Commitment revision is stale');
+                }
+                if (work.operation === 'revise' && current.withdrawn === 1) {
+                    throw new JudgmentError('COMMITMENT_WITHDRAWN', 'Withdrawn commitments cannot be revised');
+                }
+                const revision = current.current_revision + 1;
+                adapter
+                    .prepare(`INSERT INTO commitment_assignments
+             (commitment_id, revision, record_id, operation, set_json, clear_json, applies_from, applies_until, created_at, agent_id, model_run_id)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(work.commitmentId, revision, recordId, work.operation, (0, canonicalize_js_1.canonicalizeJSON)(workPatch(work)), (0, canonicalize_js_1.canonicalizeJSON)(work.clear ?? []), command.eventDatetime ?? null, command.appliesUntil ?? null, domainNow, access.agentId, command.modelRunId ?? null);
+                adapter
+                    .prepare('UPDATE commitments SET current_revision = ?, head_record_id = ?, withdrawn = ?, updated_at = ?, agent_id = ?, model_run_id = ? WHERE commitment_id = ?')
+                    .run(revision, recordId, work.operation === 'withdraw' ? 1 : 0, domainNow, access.agentId, command.modelRunId ?? null, work.commitmentId);
+                workReceipt = { commitmentId: work.commitmentId, revision };
+            }
+        }
+        (0, event_store_js_1.insertMemoryEventInTransaction)(adapter, {
+            event_type: command.event?.eventType ?? 'save',
+            actor: command.event?.actor ?? `actor:${access.principalId}`,
+            source_turn_id: command.event?.sourceTurnId,
+            memory_id: recordId,
+            topic: command.topic,
+            scope_refs: effectiveScopes,
+            evidence_refs: command.event?.evidenceRefs,
+            reason: command.event?.reason ?? 'agent judgment command',
+            created_at: domainNow,
+        });
+        const receipt = {
+            status: 'committed',
+            recordId,
+            commandId: command.commandId,
+            edgeIds,
+            watermark: now,
+            ...(workReceipt ? { work: workReceipt } : {}),
+            diagnostics: [],
+        };
+        adapter
+            .prepare(`INSERT INTO judgment_commands (command_id, record_id, committed_watermark, receipt_json, created_at)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(command.commandId, recordId, receipt.watermark, (0, canonicalize_js_1.canonicalizeJSON)(receipt), now);
+    });
+    if (replayedReceipt) {
+        return replayedReceipt;
+    }
+    // Sync the adapter's status cache for every row whose projection columns were
+    // touched: the new record, superseded targets, and amended outcome rows.
+    refreshDecisionStatusCaches(adapter, [
+        recordId,
+        ...(command.replaces ?? []).map((replacement) => replacement.id),
+        ...(command.amends ?? []).map((amendment) => amendment.target.id),
+    ]);
+    return {
+        status: 'committed',
+        recordId,
+        commandId: command.commandId,
+        edgeIds,
+        watermark: now,
+        ...(workReceipt ? { work: workReceipt } : {}),
+        diagnostics: [],
+    };
+}
+function refreshDecisionStatusCaches(adapter, memoryIds) {
+    if (!adapter.refreshDecisionStatusCache)
+        return;
+    const stmt = adapter.prepare('SELECT rowid FROM decisions WHERE id = ?');
+    for (const memoryId of new Set(memoryIds)) {
+        const row = stmt.get(memoryId);
+        if (row) {
+            adapter.refreshDecisionStatusCache(row.rowid);
+        }
+    }
+}
+async function appendJudgment(command, access, options) {
+    // The command boundary no longer reaches the process-global store: the
+    // caller names the database this judgment commits to.
+    if (!options?.adapter) {
+        throw new JudgmentError('INVALID_COMMAND', 'appendJudgment requires an explicit adapter; the process-global store is not a write path');
+    }
+    return appendJudgmentOnAdapter(options.adapter, command, access, options.embedder);
+}
+function createJudgmentWriter(options) {
+    return {
+        appendJudgment: (command, access) => appendJudgmentOnAdapter(options.adapter, command, access, options.embedder),
+    };
+}
+const EDGE_TYPE_SET = new Set(twin_edge_types_js_1.TWIN_EDGE_TYPES);
+const REF_KIND_SET = new Set(twin_edge_types_js_1.TWIN_REF_KINDS);
+const SOURCE_SET = new Set(twin_edge_types_js_1.TWIN_EDGE_SOURCES);
+function nullableString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`twin_edges.${field} must be a non-empty string`);
+    }
+    return value;
+}
+function normalizeEdgeType(value) {
+    if (typeof value === 'string' && EDGE_TYPE_SET.has(value)) {
+        return value;
+    }
+    throw new Error(`Unsupported twin edge type: ${String(value)}`);
+}
+function normalizeSource(value) {
+    if (typeof value === 'string' && SOURCE_SET.has(value)) {
+        return value;
+    }
+    throw new Error(`Unsupported twin edge source: ${String(value)}`);
+}
+function normalizeRef(ref, field) {
+    if (!ref || typeof ref !== 'object') {
+        throw new Error(`${field} must be a TwinRef`);
+    }
+    if (!REF_KIND_SET.has(ref.kind)) {
+        throw new Error(`${field}.kind is unsupported: ${String(ref.kind)}`);
+    }
+    return {
+        kind: ref.kind,
+        id: requireNonEmptyString(ref.id, `${field}.id`),
+    };
+}
+function parseJsonField(value, field, edgeId) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const text = String(value);
+    if (text.length === 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid twin_edges.${field} for ${edgeId}: ${message}`);
+    }
+}
+function toBuffer(value) {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value);
+    }
+    throw new Error('twin_edges.content_hash must be a 32-byte Buffer');
+}
+function mapTwinEdgeRow(row) {
+    const edgeId = String(row.edge_id);
+    return {
+        edge_id: edgeId,
+        edge_type: normalizeEdgeType(row.edge_type),
+        subject_ref: {
+            kind: String(row.subject_kind),
+            id: String(row.subject_id),
+        },
+        object_ref: {
+            kind: String(row.object_kind),
+            id: String(row.object_id),
+        },
+        relation_attrs_json: nullableString(row.relation_attrs_json),
+        relation_attrs: parseJsonField(row.relation_attrs_json, 'relation_attrs_json', edgeId),
+        confidence: Number(row.confidence),
+        source: normalizeSource(row.source),
+        agent_id: nullableString(row.agent_id),
+        model_run_id: nullableString(row.model_run_id),
+        envelope_hash: nullableString(row.envelope_hash),
+        human_actor_id: nullableString(row.human_actor_id),
+        human_actor_role: nullableString(row.human_actor_role),
+        authority_scope_json: nullableString(row.authority_scope_json),
+        authority_scope: parseJsonField(row.authority_scope_json, 'authority_scope_json', edgeId),
+        reason_classification: nullableString(row.reason_classification),
+        reason_text: nullableString(row.reason_text),
+        evidence_refs_json: nullableString(row.evidence_refs_json),
+        evidence_refs: parseJsonField(row.evidence_refs_json, 'evidence_refs_json', edgeId),
+        request_idempotency_key: nullableString(row.request_idempotency_key),
+        edge_idempotency_key: nullableString(row.edge_idempotency_key),
+        content_hash: toBuffer(row.content_hash),
+        created_at: Number(row.created_at),
+    };
+}
+function jsonColumn(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return typeof value === 'string' ? value : (0, canonicalize_js_1.canonicalizeJSON)(value);
+}
+/**
+ * The single write boundary for twin_edges. Both former write sites (the
+ * alias_of edge inside the alias write and the judgment-command link insert)
+ * now resolve their columns into a TwinEdgeInsert and call here, inside the
+ * caller's transaction. The row is read back so callers get the stored record.
+ */
+function insertTwinEdge(adapter, input) {
+    adapter
+        .prepare(`
+        INSERT INTO twin_edges (
+          edge_id, edge_type, subject_kind, subject_id, object_kind, object_id,
+          relation_attrs_json, confidence, source, agent_id, model_run_id, envelope_hash,
+          human_actor_id, human_actor_role, authority_scope_json, reason_classification,
+          reason_text, evidence_refs_json, request_idempotency_key, edge_idempotency_key,
+          content_hash, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(input.edge_id, input.edge_type, input.subject_ref.kind, input.subject_ref.id, input.object_ref.kind, input.object_ref.id, jsonColumn(input.relation_attrs), input.confidence ?? 1, input.source, input.agent_id ?? null, input.model_run_id ?? null, input.envelope_hash ?? null, input.human_actor_id ?? null, input.human_actor_role ?? null, jsonColumn(input.authority_scope_json), input.reason_classification ?? null, input.reason_text ?? null, jsonColumn(input.evidence_refs), input.request_idempotency_key ?? null, input.edge_idempotency_key ?? null, input.content_hash, input.created_at);
+    const record = getTwinEdge(adapter, input.edge_id);
+    if (!record) {
+        throw new Error(`Twin edge was not written: ${input.edge_id}`);
+    }
+    return record;
+}
+function getTwinEdge(adapter, edgeId) {
+    const row = adapter.prepare('SELECT * FROM twin_edges WHERE edge_id = ?').get(edgeId);
+    return row ? mapTwinEdgeRow(row) : null;
+}
+function listTwinEdgesForRefs(adapter, refs, page) {
+    const normalizedRefs = refs.map((ref, index) => normalizeRef(ref, `refs[${index}]`));
+    if (normalizedRefs.length === 0) {
+        return [];
+    }
+    const clauses = [];
+    const params = [];
+    for (const ref of normalizedRefs) {
+        clauses.push('(subject_kind = ? AND subject_id = ?)');
+        params.push(ref.kind, ref.id);
+        clauses.push('(object_kind = ? AND object_id = ?)');
+        params.push(ref.kind, ref.id);
+    }
+    const where = [`(${clauses.join(' OR ')})`];
+    if (page?.edgeTypes?.length) {
+        where.push(`edge_type IN (${page.edgeTypes.map(() => '?').join(', ')})`);
+        params.push(...page.edgeTypes);
+    }
+    if (typeof page?.startMs === 'number') {
+        where.push('created_at >= ?');
+        params.push(page.startMs);
+    }
+    if (typeof page?.asOfMs === 'number') {
+        where.push('created_at <= ?');
+        params.push(page.asOfMs);
+    }
+    if (page?.after) {
+        where.push('(created_at < ? OR (created_at = ? AND edge_id > ?))');
+        params.push(page.after.createdAt, page.after.createdAt, page.after.edgeId);
+    }
+    if (page && (!Number.isSafeInteger(page.limit) || page.limit < 1)) {
+        throw new Error('Twin edge scan limit must be a positive safe integer');
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT *
+        FROM twin_edges
+        WHERE ${where.join(' AND ')}
+        ORDER BY created_at ${page ? 'DESC' : 'ASC'}, edge_id ASC
+        ${page ? 'LIMIT ?' : ''}
+      `)
+        .all(...params, ...(page ? [page.limit] : []));
+    return rows.map(mapTwinEdgeRow);
+}
+//# sourceMappingURL=judgments.js.map