@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/memory/write-adapters.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Mechanical adapters between the public memory write surfaces and the
+ * knowledge command boundary.
+ *
+ * Every write funnels through `appendJudgment` (or `ingestSource` for raw
+ * evidence): the adapter builds exactly one command, derives honest access —
+ * never fabricating authority the caller did not present — and maps the receipt
+ * back to the legacy result shape.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsignedWriteAccess = unsignedWriteAccess;
+exports.writeAccessForProvenance = writeAccessForProvenance;
+exports.boundScopesOf = boundScopesOf;
+exports.assertRelationshipTargetsVisible = assertRelationshipTargetsVisible;
+exports.relationshipsToCommandFields = relationshipsToCommandFields;
+exports.commandEmbedder = commandEmbedder;
+exports.appendOutcomeAmendment = appendOutcomeAmendment;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const canonicalize_js_1 = require("../canonicalize.js");
+const db_manager_js_1 = require("../db-manager.js");
+const judgments_js_1 = require("../knowledge/judgments.js");
+/** Principal label for writes that carry no authenticated identity. */
+const UNSIGNED_PRINCIPAL = 'unsigned-local';
+/** Access for a caller with no signed identity: it is admitted to exactly the
+ * scopes it declared, nothing more. */
+function unsignedWriteAccess(scopes) {
+    return {
+        principalId: UNSIGNED_PRINCIPAL,
+        agentId: UNSIGNED_PRINCIPAL,
+        scopes: [...scopes],
+        // Not a principal and not a caller of actions: this access exists for the
+        // direct-write path below dispatch. Empty is what it can truthfully claim,
+        // and if it ever did reach dispatch every action would be denied.
+        actions: [],
+    };
+}
+/**
+ * Access derived from normalized write provenance — the legacy direct-write
+ * path, where the caller is the process itself and declares its own scopes.
+ * Unified-action writes do NOT come through here: dispatch passes the real
+ * `JudgmentAccess` (the call authority) straight to `appendJudgment`.
+ */
+function writeAccessForProvenance(provenance, requestedScopes) {
+    const identity = provenance.agent_id ?? provenance.actor;
+    return {
+        principalId: identity,
+        agentId: provenance.agent_id ?? identity,
+        scopes: [...requestedScopes],
+        // Same as above: provenance names who wrote, not what they may call.
+        actions: [],
+    };
+}
+/** Scope refs currently bound to a memory row — the partition a write into
+ * that row must be admitted to. */
+function boundScopesOf(adapter, memoryId) {
+    return adapter
+        .prepare(`SELECT ms.kind, ms.external_id
+       FROM memory_scope_bindings msb
+       JOIN memory_scopes ms ON ms.id = msb.scope_id
+       WHERE msb.memory_id = ?
+       ORDER BY msb.is_primary DESC`)
+        .all(memoryId)
+        .map((row) => {
+        const record = row;
+        return { kind: record.kind, id: record.external_id };
+    });
+}
+/**
+ * Fail-first visibility check for explicitly authored relationship targets,
+ * preserving the legacy error contract.
+ *
+ * Trusted envelopes check visibility strictly inside admitted scopes (unbound
+ * legacy rows are not reachable — same as the pre-boundary envelope check).
+ * Unsigned callers keep the legacy existence check for the original error
+ * text; scope admission is then enforced by the command boundary itself.
+ */
+function assertRelationshipTargetsVisible(adapter, targetIds, admittedScopes, trustedEnvelope) {
+    for (const targetId of targetIds) {
+        if (trustedEnvelope) {
+            const scopeIds = admittedScopes.map((scope) => (0, db_manager_js_1.buildMemoryScopeId)(scope.kind, scope.id));
+            const placeholders = scopeIds.map(() => '?').join(', ');
+            const visible = scopeIds.length > 0 &&
+                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(targetId, ...scopeIds) !== undefined;
+            if (!visible) {
+                const denied = new Error('Relationship target is unavailable');
+                denied.code = 'relationship_target_unavailable';
+                throw denied;
+            }
+            continue;
+        }
+        const target = adapter.prepare('SELECT id FROM decisions WHERE id = ?').get(targetId);
+        if (!target) {
+            throw new Error(`mama.save() relationship target does not exist: ${targetId}`);
+        }
+    }
+}
+const LINK_RELATIONS = new Set([
+    'supersedes',
+    'refines',
+    'contradicts',
+    'mentions',
+    'derived_from',
+    'builds_on',
+    'debates',
+    'synthesizes',
+    'blocks',
+    'next_action_for',
+    'case_member',
+]);
+/**
+ * Map deduplicated legacy relationships onto command fields.
+ *
+ * Trusted envelopes get the authored form: `supersedes` targets become
+ * scope-checked `replaces`, and link-able relations also enter the twin edge
+ * graph as explicit `links` — both fail closed inside the boundary.
+ *
+ * Unsigned callers keep the legacy contract: the adapter already checked that
+ * each target exists, so relationships are written only as `decision_edges`
+ * projection rows and `supersedes` targets are moved out of current truth
+ * through the `supersedeTargets` projection — never as scope-checked authored
+ * links the caller was not admitted to.
+ */
+function relationshipsToCommandFields(relationships, options) {
+    const trusted = options?.trusted === true;
+    const links = [];
+    const replaces = [];
+    const supersedeTargets = [];
+    const decisionEdges = [];
+    const seen = new Set();
+    for (const relationship of relationships) {
+        const key = `${relationship.type}:${relationship.targetId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const reason = `Explicit ${relationship.type} reference in reasoning`;
+        decisionEdges.push({
+            targetId: relationship.targetId,
+            relationship: relationship.type,
+            reason,
+            weight: 1,
+        });
+        if (relationship.type === 'supersedes') {
+            if (trusted) {
+                replaces.push({ id: relationship.targetId, reason });
+            }
+            else {
+                supersedeTargets.push(relationship.targetId);
+            }
+            continue;
+        }
+        if (trusted && LINK_RELATIONS.has(relationship.type)) {
+            links.push({
+                relation: relationship.type,
+                target: { kind: 'memory', id: relationship.targetId },
+            });
+        }
+    }
+    return { links, replaces, decisionEdges, supersedeTargets };
+}
+/**
+ * Embedder for the command boundary that preserves the legacy enhanced
+ * embedding input.
+ */
+function commandEmbedder(decision) {
+    return { embed: () => (0, db_manager_js_1.prepareDecisionEmbedding)(decision) };
+}
+/**
+ * Append one judgment record carrying an authored outcome change and apply the
+ * maintained `decisions` projection columns on the target in the same
+ * transaction. Identical payloads on the same target replay the stored receipt
+ * instead of appending a second record.
+ */
+async function appendOutcomeAmendment(decisionId, input, options) {
+    const adapter = options.adapter;
+    const target = adapter.prepare('SELECT id, topic FROM decisions WHERE id = ?').get(decisionId);
+    if (!target) {
+        throw new Error(`Decision not found: ${decisionId}`);
+    }
+    const scopes = boundScopesOf(adapter, decisionId);
+    const payload = {
+        amended: decisionId,
+        outcome: input.outcome ?? null,
+        failure_reason: input.failureReason ?? null,
+        limitation: input.limitation ?? null,
+        confidence: input.confidence ?? null,
+        duration_days: input.durationDays ?? null,
+        ...(input.payload ?? {}),
+    };
+    const commandId = input.commandId ??
+        `outcome:${decisionId}:${node_crypto_1.default
+            .createHash('sha256')
+            .update((0, canonicalize_js_1.canonicalizeJSON)(payload))
+            .digest('hex')
+            .slice(0, 16)}`;
+    const amendment = { target: { kind: 'memory', id: decisionId } };
+    if (input.outcome !== undefined)
+        amendment.outcome = input.outcome;
+    if (input.failureReason !== undefined)
+        amendment.failureReason = input.failureReason;
+    if (input.limitation !== undefined)
+        amendment.limitation = input.limitation;
+    if (input.confidence !== undefined && input.confidence !== null) {
+        amendment.confidence = input.confidence;
+    }
+    if (input.durationDays !== undefined)
+        amendment.durationDays = input.durationDays;
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        commandId,
+        // Audit records point at the amended memory through the 'amends' link
+        // rather than sharing its topic, so they never enter the topic's
+        // evolution candidate pool or current-truth recall.
+        topic: `judgment/${decisionId}`,
+        summary: `Outcome ${input.outcome ?? 'update'} recorded for ${decisionId}`,
+        ...(input.failureReason || input.limitation
+            ? { reasoning: (input.failureReason ?? input.limitation) }
+            : {}),
+        recordKind: 'judgment',
+        payload,
+        scopes,
+        agentId: null,
+        links: [
+            {
+                relation: 'amends',
+                target: { kind: 'memory', id: decisionId },
+            },
+        ],
+        amends: [amendment],
+        record: { kind: 'fact', status: 'active', summary: `Outcome ${input.outcome ?? 'update'}` },
+        ...(input.recordedAt !== undefined ? { recordedAt: input.recordedAt } : {}),
+        event: { reason: input.eventReason ?? `outcome amendment for ${decisionId}` },
+    }, unsignedWriteAccess(scopes), { adapter });
+    return { recordId: receipt.recordId, commandId: receipt.commandId };
+}
+//# sourceMappingURL=write-adapters.js.map

package/dist/operations/owner-action-effects.d.ts

@@ -0,0 +1,53 @@
+export interface OwnerActionContext {
+    ownerScope: string;
+    occurrenceKey: string;
+    modelRunId?: string;
+    operationId?: string;
+    envelopeHash: string;
+    workOrderAttemptId?: number;
+}
+export interface VerifiedOwnerActionContext {
+    ownerScope: string;
+    occurrenceKey: string;
+    modelRunId: string | null;
+    operationId: string | null;
+    envelopeHash: string;
+    workOrderAttemptId: number | null;
+}
+export type OwnerActionEffectState = 'transmitting' | 'unknown' | 'confirmed';
+export interface OwnerActionPendingEffect {
+    actionKey: string;
+    effectKind: string;
+    state: Exclude<OwnerActionEffectState, 'confirmed'>;
+    originModelRunId: string | null;
+    originOperationId: string | null;
+}
+export interface OwnerActionPendingPage {
+    items: OwnerActionPendingEffect[];
+    nextCursor: {
+        createdAt: number;
+        actionKey: string;
+    } | null;
+}
+export interface OwnerActionEffectStoragePort {
+    begin(context: OwnerActionContext, actionKey: string, effectKind: string, intent?: Record<string, unknown>): unknown;
+    confirm(context: OwnerActionContext, actionKey: string, effectKind: string, result: Record<string, unknown> | null): void;
+    markUnknown(context: OwnerActionContext, actionKey: string, effectKind: string, error: string): void;
+    releaseUnstarted(context: OwnerActionContext, actionKey: string, effectKind: string): void;
+    pending(context: OwnerActionContext, options?: {
+        limit?: number;
+        cursor?: {
+            createdAt: number;
+            actionKey: string;
+        };
+    }): OwnerActionPendingPage;
+}
+export declare function canonicalizeOwnerActionValue(value: unknown, path?: string): unknown;
+export declare function canonicalOwnerActionJson(value: Record<string, unknown>): string;
+export declare function ownerActionIntentSha256(value: Record<string, unknown>): string;
+export declare function verifyOwnerActionContext(context: OwnerActionContext): VerifiedOwnerActionContext;
+export declare function ownerActionOriginMatch(context: VerifiedOwnerActionContext): {
+    clause: string;
+    params: string[];
+};
+//# sourceMappingURL=owner-action-effects.d.ts.map

package/dist/operations/owner-action-effects.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeOwnerActionValue = canonicalizeOwnerActionValue;
+exports.canonicalOwnerActionJson = canonicalOwnerActionJson;
+exports.ownerActionIntentSha256 = ownerActionIntentSha256;
+exports.verifyOwnerActionContext = verifyOwnerActionContext;
+exports.ownerActionOriginMatch = ownerActionOriginMatch;
+const node_crypto_1 = require("node:crypto");
+const IDENTITY_MAX_LENGTH = 512;
+function canonicalizeOwnerActionValue(value, path = '$') {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`owner action intent ${path} must be a finite number`);
+        }
+        return value;
+    }
+    if (typeof value !== 'object') {
+        throw new Error(`owner action intent ${path} is not JSON-representable (${typeof value})`);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => canonicalizeOwnerActionValue(item, `${path}[${index}]`));
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error(`owner action intent ${path} must be a plain JSON object`);
+    }
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [
+        key,
+        canonicalizeOwnerActionValue(value[key], `${path}.${key}`),
+    ]));
+}
+function canonicalOwnerActionJson(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('owner action intent must be a plain JSON object');
+    }
+    return JSON.stringify(canonicalizeOwnerActionValue(value));
+}
+function ownerActionIntentSha256(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(canonicalOwnerActionJson(value)).digest('hex');
+}
+function requireIdentity(value, field) {
+    if (typeof value !== 'string') {
+        throw new Error(`owner action ${field} must be a non-blank string`);
+    }
+    const trimmed = value.trim();
+    if (!trimmed || trimmed !== value || trimmed.length > IDENTITY_MAX_LENGTH) {
+        throw new Error(`owner action ${field} must be a non-blank string without surrounding space and at most ${IDENTITY_MAX_LENGTH} characters`);
+    }
+    return trimmed;
+}
+function optionalIdentity(value, field) {
+    return value === undefined || value === null ? null : requireIdentity(value, field);
+}
+function verifyOwnerActionContext(context) {
+    if (context === null || typeof context !== 'object') {
+        throw new Error('owner action context is required');
+    }
+    const workOrderAttemptId = context.workOrderAttemptId;
+    if (workOrderAttemptId !== undefined &&
+        (!Number.isSafeInteger(workOrderAttemptId) || workOrderAttemptId <= 0)) {
+        throw new Error('owner action workOrderAttemptId must be a positive integer when present');
+    }
+    const modelRunId = optionalIdentity(context.modelRunId, 'modelRunId');
+    const operationId = optionalIdentity(context.operationId, 'operationId');
+    if (modelRunId === null && operationId === null) {
+        throw new Error('owner action context requires a modelRunId or operationId origin');
+    }
+    return {
+        ownerScope: requireIdentity(context.ownerScope, 'ownerScope'),
+        occurrenceKey: requireIdentity(context.occurrenceKey, 'occurrenceKey'),
+        modelRunId,
+        operationId,
+        envelopeHash: requireIdentity(context.envelopeHash, 'envelopeHash'),
+        workOrderAttemptId: workOrderAttemptId ?? null,
+    };
+}
+function ownerActionOriginMatch(context) {
+    if (context.operationId !== null) {
+        return { clause: 'origin_operation_id = ?', params: [context.operationId] };
+    }
+    return {
+        clause: '(origin_operation_id IS NULL AND origin_model_run_id = ?)',
+        params: [context.modelRunId],
+    };
+}
+//# sourceMappingURL=owner-action-effects.js.map

package/dist/provenance/source-ref.d.ts

@@ -1,4 +1,4 @@
-export declare const STRICT_SOURCE_REF_KINDS: readonly ["memory", "raw", "entity", "case", "decision", "os_task", "agent_situation_packet", "report_slot", "context_packet", "model_run", "tool_trace", "wiki_page", "report"];
+export declare const STRICT_SOURCE_REF_KINDS: readonly ["memory", "raw", "case", "decision", "os_task", "report_slot", "context_packet", "model_run", "tool_trace", "wiki_page", "report"];
 export type StrictSourceRefKind = (typeof STRICT_SOURCE_REF_KINDS)[number];
 export declare const LEGACY_SOURCE_REF_KINDS: readonly ["message", "conversation", "raw_memory"];
 export type LegacySourceRefKind = (typeof LEGACY_SOURCE_REF_KINDS)[number];

package/dist/provenance/source-ref.js

@@ -5,11 +5,9 @@ exports.serializeSourceRef = serializeSourceRef;
 exports.STRICT_SOURCE_REF_KINDS = [
     'memory',
     'raw',
-    'entity',
     'case',
     'decision',
     'os_task',
-    'agent_situation_packet',
     'report_slot',
     'context_packet',
     'model_run',

package/dist/registry/corrections.d.ts

@@ -0,0 +1,31 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { MemoryScopeRef } from '../memory/types.js';
+import type { IdentityCorrection, IdentityCorrectionReceipt } from '../memory/judgment-types.js';
+type Endpoint = 'from' | 'to';
+type Db = DatabaseAdapter;
+export type { IdentityCorrection, IdentityCorrectionAssignment, IdentityCorrectionReceipt, } from '../memory/judgment-types.js';
+export interface TrustedIdentityCorrectionContext {
+    principalId: string;
+    agentId: string;
+    scopes: readonly MemoryScopeRef[];
+    connectors: readonly string[];
+    channels?: Readonly<Record<string, readonly string[]>>;
+}
+export interface IdentityAssignment {
+    edgeId: string;
+    endpoint: Endpoint;
+    originalRef: {
+        kind: string;
+        id: string;
+    };
+    resolvedRef: {
+        kind: 'registry';
+        id: string;
+    } | null;
+    identityRevision: number;
+    commandId: string;
+}
+export declare function appendIdentityCorrection(adapter: Db, correction: IdentityCorrection, trusted: TrustedIdentityCorrectionContext): IdentityCorrectionReceipt;
+export declare function readIdentityAssignments(adapter: Db, edgeId: string): IdentityAssignment[];
+export declare function newCorrectionCommandId(): string;
+//# sourceMappingURL=corrections.d.ts.map