@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/memory/judgment-types.d.ts

@@ -0,0 +1,394 @@
+import type { MemoryEventRecord, MemoryScopeRef } from './types.js';
+import type { TwinRef } from '../knowledge/twin-edge-types.js';
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type WorkReference = TwinRef | {
+    kind: 'registry' | 'observation';
+    id: string;
+};
+export type WorkRef = WorkReference;
+export interface RecordLink {
+    relation: 'supersedes' | 'refines' | 'contradicts' | 'mentions' | 'derived_from' | 'builds_on' | 'debates' | 'synthesizes' | 'blocks' | 'next_action_for' | 'case_member' | 'amends';
+    target: WorkReference;
+    attrs?: {
+        role?: string;
+        slot?: string;
+        [key: string]: JsonValue | undefined;
+    };
+}
+/**
+ * What a revision sets on a piece of work.
+ *
+ * The core reads exactly three of these: the date fields, because a commitment's due
+ * time is something it reasons about. Everything else round-trips as JSON through
+ * `set_json` and is never destructured here -- it is one product's board vocabulary
+ * (status, priority, assignee, resolution) and the product's own action schema is
+ * where it is spelled out and checked.
+ */
+export interface OwnerWorkPatch {
+    dueAt?: string | null;
+    deadline?: string | null;
+    /**
+     * The offset (minutes from UTC, -840..840) a bare `deadline`'s day starts in.
+     * Pairs with the date fields: an exact `dueAt` derives it, a bare deadline
+     * may state it alone. Absent means the owner's zone answers.
+     */
+    deadlineOffsetMinutes?: number | null;
+    [field: string]: JsonValue | undefined;
+}
+/**
+ * The named lifecycle judgments an owner row accepts. A reclassification is a
+ * revision whose status and resolutionKind are the SAME statement: completed
+ * work and an item that was never a task must not close identically.
+ */
+export declare const WORK_RECLASSIFY_DISPOSITIONS: readonly ["completed_evidence", "completed_no_issue", "non_task_record", "non_task_memory", "reopen"];
+export type WorkReclassifyDisposition = (typeof WORK_RECLASSIFY_DISPOSITIONS)[number];
+export type WorkAssignment = {
+    set?: OwnerWorkPatch;
+    clear?: Array<keyof OwnerWorkPatch>;
+} & ({
+    operation: 'create';
+    /**
+     * Import vocabulary: the identity this work already had in a predecessor
+     * store. A migration that brings existing owner rows into the commitment
+     * log names their task id and revision so the log keeps the row's number
+     * and CAS history instead of minting a new identity. Absent for work
+     * first stated through this command log.
+     */
+    imported?: {
+        rowId: number;
+        revision?: number;
+        createdAt?: number;
+    };
+} | {
+    operation: 'revise';
+    commitmentId: string;
+    expectedRevision?: number;
+} | {
+    operation: 'withdraw';
+    commitmentId: string;
+    expectedRevision: number;
+});
+/**
+ * Legacy decisions-row fields that public save adapters keep projecting. These
+ * columns remain the read model for existing recall/provenance surfaces until
+ * the readers migrate to the command log.
+ */
+export interface JudgmentRecordFields {
+    kind?: string | null;
+    status?: string | null;
+    summary?: string | null;
+    isStatic?: number | null;
+    userInvolvement?: string | null;
+    sessionId?: string | null;
+    needsValidation?: number | null;
+    trustContext?: string | null;
+    refinedFrom?: string[] | null;
+    /**
+     * Legacy `decisions.supersedes` column for records whose predecessor was
+     * declared through the supersedeTargets projection rather than the
+     * scope-checked `replaces` command field.
+     */
+    supersedes?: string | null;
+}
+/**
+ * Append-only correction to an existing memory row's projection columns. The
+ * judgment record stays the authority; the named columns on the target row are
+ * the maintained projection that current readers consume.
+ */
+export interface JudgmentAmendment {
+    target: {
+        kind: 'memory';
+        id: string;
+    };
+    outcome?: string | null;
+    failureReason?: string | null;
+    limitation?: string | null;
+    status?: string | null;
+    confidence?: number | null;
+    durationDays?: number | null;
+    supersedes?: string | null;
+    supersededBy?: string | null;
+}
+/** Provenance carried onto the record's memory_events row. */
+export interface JudgmentEventMeta {
+    eventType?: MemoryEventRecord['event_type'];
+    actor?: MemoryEventRecord['actor'];
+    sourceTurnId?: string;
+    reason?: string;
+    evidenceRefs?: string[];
+}
+/**
+ * Compatibility projections the command applies inside the same transaction so
+ * pre-command readers keep working. None of these create authority beyond the
+ * command itself; they mirror what the legacy writers used to persist inline.
+ */
+export interface JudgmentProjections {
+    /** Legacy decision_edges rows kept in sync for recall readers. `fromId`
+     * defaults to the appended record; amendment commands may name another row. */
+    decisionEdges?: Array<{
+        fromId?: string;
+        targetId: string;
+        relationship: string;
+        reason?: string | null;
+        weight?: number;
+        createdBy?: string;
+        approvedByUser?: number | null;
+    }>;
+    /**
+     * Rows the command marks as superseded by the appended record. This mirrors
+     * the legacy save surface where an unsigned caller's explicit `supersedes`
+     * relationship moved the named target out of current truth; the command
+     * boundary keeps `replaces` for scope-admitted supersession instead.
+     */
+    supersedeTargets?: string[];
+    /** Registry record identity binding (item + actors). */
+    recordIdentity?: {
+        itemId?: string | null;
+        actors?: Array<{
+            personId: string;
+            role: string;
+        }>;
+    };
+}
+export interface JudgmentCommand {
+    commandId: string;
+    topic: string;
+    summary: string;
+    reasoning?: string;
+    recordKind: 'judgment' | 'commitment';
+    payload?: Record<string, JsonValue>;
+    appliesFrom?: number;
+    appliesUntil?: number;
+    links?: RecordLink[];
+    replaces?: Array<{
+        id: string;
+        reason: string;
+    }>;
+    work?: WorkAssignment;
+    scopes?: MemoryScopeRef[];
+    /** Confidence supplied by the caller; no synthesis happens here. */
+    confidence?: number;
+    /** ISO 8601 YYYY-MM-DD for when the recorded event actually occurred. */
+    eventDate?: string | null;
+    /** Milliseconds epoch for when the recorded event actually occurred. */
+    eventDatetime?: number | null;
+    outcome?: string | null;
+    failureReason?: string | null;
+    limitation?: string | null;
+    evidence?: string | string[] | null;
+    alternatives?: string | string[] | null;
+    risks?: string | null;
+    /** Source references carried from normalized write provenance. */
+    sourceRefs?: string[];
+    /** Compact provenance record persisted on the decision row. */
+    provenance?: Record<string, JsonValue>;
+    /**
+     * Authored record agent. Absent means the access principal writes the record;
+     * an explicit null keeps the column empty for honest unsigned writes.
+     */
+    agentId?: string | null;
+    modelRunId?: string | null;
+    envelopeHash?: string | null;
+    gatewayCallId?: string | null;
+    /** Domain capture time for the record (decisions.created_at). */
+    recordedAt?: number;
+    /** Legacy decisions-row projection fields. */
+    record?: JudgmentRecordFields;
+    /** Append-only amendments applied to existing memory rows in-transaction. */
+    amends?: JudgmentAmendment[];
+    /** Memory event metadata for the record's save event. */
+    event?: JudgmentEventMeta;
+    /** Legacy compatibility projections written in the same transaction. */
+    projections?: JudgmentProjections;
+}
+export interface JudgmentReceipt {
+    status: 'committed';
+    recordId: string;
+    commandId: string;
+    edgeIds: string[];
+    watermark: number;
+    work?: {
+        commitmentId: string;
+        revision: number;
+    };
+    diagnostics: Array<{
+        stage: string;
+        code: string;
+        message: string;
+    }>;
+}
+export type IdentityCorrectionAssignment = {
+    edgeId: string;
+    endpoint: 'from' | 'to';
+} & ({
+    targetNodeId: string | null;
+    targetClientKey?: never;
+} | {
+    targetClientKey: string;
+    targetNodeId?: never;
+});
+export type IdentityCorrection = {
+    commandId: string;
+    expectedRevision: number;
+    reason: string;
+    scopes?: MemoryScopeRef[];
+    evidence?: ReadonlyArray<{
+        kind: 'observation';
+        id: string;
+    }>;
+} & ({
+    operation: 'add_alias';
+    nodeId: string;
+    alias: string;
+} | {
+    operation: 'merge';
+    survivorId: string;
+    memberIds: readonly string[];
+} | {
+    operation: 'split';
+    parentId: string;
+    children: ReadonlyArray<{
+        clientKey?: string;
+        name: string;
+        aliases?: readonly string[];
+    }>;
+    assignments: readonly IdentityCorrectionAssignment[];
+} | {
+    operation: 'assign_refs';
+    parentId: string;
+    assignments: readonly IdentityCorrectionAssignment[];
+});
+export interface IdentityCorrectionReceipt {
+    commandId: string;
+    identityRevision: number;
+    children: Array<{
+        clientKey: string;
+        ref: {
+            kind: 'registry';
+            id: string;
+        };
+    }>;
+    changedSlots: Array<{
+        edgeId: string;
+        endpoint: 'from' | 'to';
+    }>;
+    unresolved: Array<{
+        edgeId: string;
+        endpoint: 'from' | 'to';
+    }>;
+}
+export interface WorkGraphQuery {
+    seeds?: WorkReference[];
+    search?: {
+        text: string;
+        kinds?: WorkReference['kind'][];
+    };
+    view: 'overview' | 'browse' | 'neighbors' | 'timeline' | 'paths' | 'detail';
+    section?: 'summary' | 'reasoning' | 'payload';
+    textOffset?: number;
+    textLimit?: number;
+    from?: WorkReference;
+    to?: WorkReference;
+    maxDepth?: number;
+    direction?: 'in' | 'out' | 'both';
+    relations?: string[];
+    history?: 'current' | 'all';
+    eventRange?: {
+        start?: number;
+        end?: number;
+    };
+    recordedRange?: {
+        start?: number;
+        end?: number;
+    };
+    asOf?: number;
+    limit?: number;
+    cursor?: string;
+}
+export type WorkGraphNodeData = {
+    kind: 'memory';
+    recordKind: 'legacy' | 'judgment' | 'commitment';
+    /** Stored classification, independent of the graph reference kind. */
+    memoryKind?: string | null;
+    topic: string;
+    summary: string;
+    recordedAt: number;
+    appliesFrom: number | null;
+    appliesUntil: number | null;
+    stateAtSnapshot: 'current' | 'replaced' | 'withdrawn' | 'not_yet_effective' | 'expired';
+    replaces: string[];
+    payload: Record<string, JsonValue>;
+    /** The commitment this record is a revision of, when it is one. */
+    work: {
+        commitmentId: string;
+        rowId: number;
+        revision: number;
+        latestJudgmentRef: WorkReference;
+    } | null;
+    /**
+     * Whether `summary` holds the whole selected section text. When it does not,
+     * `nextRead` is the same query with the offset advanced past what was returned.
+     */
+    content: {
+        complete: boolean;
+        nextRead: WorkGraphQuery | null;
+    };
+} | {
+    kind: 'registry';
+    nodeKind: 'item' | 'person' | 'client';
+    name: string;
+    parentId: string | null;
+    visibleAliases: string[];
+    identityRevision: number;
+    visibleChildren: Array<{
+        kind: 'registry';
+        id: string;
+        name: string;
+    }>;
+    unresolvedSlots: Array<{
+        edgeId: string;
+        endpoint: 'from' | 'to';
+    }>;
+} | {
+    kind: 'observation';
+    connector: string;
+    sourceId: string;
+    sourceAt: number | null;
+    observedAt: number;
+    contentHash: string;
+} | {
+    kind: 'case' | 'entity' | 'report' | 'edge' | 'raw';
+    data: Record<string, JsonValue>;
+};
+export interface WorkGraphPage {
+    nodes: Array<{
+        ref: WorkReference;
+        resolvedRef: WorkReference;
+        label: string;
+        data: WorkGraphNodeData;
+    }>;
+    edges: Array<{
+        id: string;
+        relation: string;
+        from: WorkReference;
+        to: WorkReference;
+        resolvedFrom: WorkReference;
+        resolvedTo: WorkReference;
+        attrs: JsonValue;
+    }>;
+    coverage: {
+        returned: number;
+        total: number | null;
+        complete: boolean;
+        reasons: string[];
+    };
+    snapshot: {
+        judgmentWatermark: number;
+        identityRevision: number;
+        asOf: number;
+    };
+    nextCursor: string | null;
+}
+//# sourceMappingURL=judgment-types.d.ts.map

package/dist/memory/judgment-types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORK_RECLASSIFY_DISPOSITIONS = void 0;
+/**
+ * The named lifecycle judgments an owner row accepts. A reclassification is a
+ * revision whose status and resolutionKind are the SAME statement: completed
+ * work and an item that was never a task must not close identically.
+ */
+exports.WORK_RECLASSIFY_DISPOSITIONS = [
+    'completed_evidence',
+    'completed_no_issue',
+    'non_task_record',
+    'non_task_memory',
+    'reopen',
+];
+//# sourceMappingURL=judgment-types.js.map

package/dist/memory/provenance-audit.d.ts

@@ -1,3 +1,5 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+type ProvenanceAuditAdapter = Pick<DatabaseAdapter, 'prepare'>;
 import type { MemoryEventRecord, MemoryScopeRef } from './types.js';
 export interface MemoryProvenanceAuditRecord {
     memory_id: string;
@@ -17,6 +19,7 @@ export interface MemoryProvenanceAuditListOptions {
     gateway_call_id?: string;
     limit?: number;
 }
-export declare function getMemoryProvenanceAudit(memoryId: string): Promise<MemoryProvenanceAuditRecord | null>;
-export declare function listMemoryProvenanceAudit(options: MemoryProvenanceAuditListOptions): Promise<MemoryProvenanceAuditRecord[]>;
+export declare function getMemoryProvenanceAudit(adapter: ProvenanceAuditAdapter, memoryId: string): Promise<MemoryProvenanceAuditRecord | null>;
+export declare function listMemoryProvenanceAudit(adapter: ProvenanceAuditAdapter, options: MemoryProvenanceAuditListOptions): Promise<MemoryProvenanceAuditRecord[]>;
+export {};
 //# sourceMappingURL=provenance-audit.d.ts.map

package/dist/memory/provenance-audit.js

@@ -2,11 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMemoryProvenanceAudit = getMemoryProvenanceAudit;
 exports.listMemoryProvenanceAudit = listMemoryProvenanceAudit;
-const db_manager_js_1 = require("../db-manager.js");
 const event_store_js_1 = require("./event-store.js");
-async function getMemoryProvenanceAudit(memoryId) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function getMemoryProvenanceAudit(adapter, memoryId) {
     const row = adapter
         .prepare(`
         SELECT id, topic, decision, summary, envelope_hash, model_run_id, gateway_call_id,
@@ -15,11 +12,9 @@ async function getMemoryProvenanceAudit(memoryId) {
         WHERE id = ?
       `)
         .get(memoryId);
-    return row ? toAuditRecord(row) : null;
+    return row ? toAuditRecord(adapter, row) : null;
 }
-async function listMemoryProvenanceAudit(options) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function listMemoryProvenanceAudit(adapter, options) {
     const filter = buildAuditFilter(options);
     const rows = adapter
         .prepare(`
@@ -33,7 +28,7 @@ async function listMemoryProvenanceAudit(options) {
         .all(...filter.params, normalizeLimit(options.limit));
     const records = [];
     for (const row of rows) {
-        records.push(await toAuditRecord(row));
+        records.push(await toAuditRecord(adapter, row));
     }
     return records;
 }
@@ -52,9 +47,9 @@ function buildAuditFilter(options) {
     }
     return { sql: filters[0], params };
 }
-async function toAuditRecord(row) {
-    const events = await (0, event_store_js_1.listMemoryEventsForMemory)(row.id);
-    const scopeRefs = listScopeRefs(row.id);
+async function toAuditRecord(adapter, row) {
+    const events = await (0, event_store_js_1.listMemoryEventsForMemory)(adapter, row.id);
+    const scopeRefs = listScopeRefs(adapter, row.id);
     const provenance = parseObject(row.provenance_json);
     const legacyCaveats = [];
     if (provenance.source_type === 'legacy') {
@@ -76,8 +71,7 @@ async function toAuditRecord(row) {
         legacy_caveats: legacyCaveats,
     };
 }
-function listScopeRefs(memoryId) {
-    const adapter = (0, db_manager_js_1.getAdapter)();
+function listScopeRefs(adapter, memoryId) {
     const rows = adapter
         .prepare(`
         SELECT ms.kind, ms.external_id

package/dist/memory/provenance-live.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The live wiring for provenance resolution: real memory records, real events, real scope.
+ *
+ * The resolver itself is pure. This is where it meets the database, and the one rule that
+ * governs the whole file is that CITATION MUST NOT OUT-READ READING. If this path were
+ * more permissive than the path that reads raw events normally, then citing a claim would
+ * become a way to see events the read path denies - the handle would launder access.
+ * So this path does not have its own rule any more. When the caller holds a channel grant
+ * it calls the SAME function the reader compiles into SQL (mama-core channel-grant.ts).
+ * Mirroring by hand is what this file used to do, and the mirror held right up until the
+ * reader changed - at which point citation started refusing excerpts for the very events
+ * the reader was citing, and the differential test kept passing because its fixtures never
+ * set a grant.
+ *
+ * The pre-grant rule below is retained for callers that hold no channel or connector-wide
+ * grant. Connector-wide authority is stated by the principal, not by the tool payload,
+ * and mirrors the owner's stored-source read path. This matters for unscoped rows:
+ * denying them outright would make provenance useless for most of the corpus.
+ */
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { MemoryScopeRef } from './types.js';
+import { type ChannelGrant } from '../knowledge/access.js';
+import { type IndexedEvent, type ParsedSourceRef, type ProvenanceResolution } from './provenance-resolver.js';
+/** The columns the predicate needs. Shared so a test reads exactly what production does. */
+/**
+ * The evidence columns, read from observations under the names the resolver uses.
+ *
+ * This selected them from the connector event index, which is how "what does this
+ * memory rest on" came to require the connector package. An observation is what a
+ * judgment rests on, and it is the core's own table.
+ */
+export declare const OBSERVATION_COLUMNS = "observation_id AS event_index_id, source AS source_connector,\n            source_id, channel, body AS content, observed_at, source_at,\n            memory_scope_kind, memory_scope_id, project_id, tenant_id";
+export interface EventRow {
+    event_index_id: unknown;
+    source_connector: unknown;
+    source_id: unknown;
+    channel: unknown;
+    content: unknown;
+    observed_at: unknown;
+    source_at: unknown;
+    memory_scope_kind: unknown;
+    memory_scope_id: unknown;
+    project_id: unknown;
+    tenant_id: unknown;
+}
+export interface LiveProvenanceOptions {
+    /** Scopes active NOW. Not the scopes the memory was written under. */
+    scopes: MemoryScopeRef[];
+    /** Raw connectors this caller may read. Empty means NO raw events, never all. */
+    connectors: readonly string[];
+    /** Connector-wide read authority stated by the principal, never by tool input. */
+    wideConnectors?: readonly string[];
+    /** Exact caller for durable scheduled/native input support visibility. */
+    principalId?: string;
+    /**
+     * The channels of each connector this caller may read, when the caller holds a grant.
+     * Present means the grant decides, exactly as it does in the reader. Absent means the
+     * pre-grant rule applies, so a caller that has not been given one is unaffected.
+     */
+    channels?: ChannelGrant;
+    /** Project and tenant window, mirroring the reader's filters on the same columns. */
+    projectIds?: readonly string[];
+    tenantId?: string | null;
+    /**
+     * Visibility clamp on observation time, in epoch ms. Only the MAX is threaded from the
+     * call site, deliberately: the reader's lower bound comes solely from `range.start_ms`,
+     * which is caller-chosen narrowing, while the upper bound folds in `as_of`, which is an
+     * authority clamp. A future reader should not "fix" the asymmetry. The reader bounds raw candidates
+     * by `COALESCE(event_datetime, source_timestamp_ms)`; without a counterpart here, an
+     * `as_of` boundary would hold for reading and not for citation. Nothing assigns
+     * `envelope.scope.as_of` today, so these are null in practice - implemented now
+     * because a filter with no counterpart is exactly the shape the tenant leak had.
+     */
+    minObservedMs?: number | null;
+    maxObservedMs?: number | null;
+    /** Inclusive source/event-time ceiling for replay visibility. */
+    maxSourceMs?: number | null;
+    excerptChars?: number;
+    /** Redaction to apply to excerpts, so this surface scrubs what recall scrubs. */
+    redact?: (text: string) => string;
+}
+/**
+ * Parse a stored source ref into what it actually is.
+ *
+ * The shapes here were measured, not guessed. Of the source refs on this machine 13,403
+ * are `memory:`, 1,748 are `envelope:`, 9 are `message:` and none are `raw:`. An earlier
+ * version of this parser understood only `raw:` and reported every real memory as
+ * `unsupported_ref` - a tool that was wired, callable, and answered nothing.
+ */
+export declare function parseSourceRef(ref: string): ParsedSourceRef;
+/**
+ * Whether an event may be shown under the authority active now.
+ *
+ * When a channel grant is supplied this DELEGATES to the shared rule rather than copying
+ * it. The previous version copied the reader clause for clause and said so in a comment,
+ * which held until the reader changed - then the copy silently became a different rule
+ * that refused excerpts for the very events the reader was citing. The differential test
+ * meant to catch that kept passing, because its fixtures never set a grant.
+ *
+ * "A shared predicate would be better than a faithful copy" is what the old comment here
+ * said. It was right.
+ *
+ * Without a grant the pre-grant rule still applies, so callers that have not been given
+ * one behave exactly as before.
+ */
+export declare function isEventVisibleNow(event: IndexedEvent, options: {
+    scopes: readonly MemoryScopeRef[];
+    connectors: readonly string[];
+    wideConnectors?: readonly string[];
+    channels?: ChannelGrant;
+    projectIds?: readonly string[];
+    tenantId?: string | null;
+    minObservedMs?: number | null;
+    maxObservedMs?: number | null;
+    maxSourceMs?: number | null;
+}): boolean;
+/**
+ * Row to the struct the predicate judges.
+ *
+ * Exported because it is the layer BELOW the predicate, and a differential that
+ * hand-builds its own struct proves the predicate mirrors the reader while leaving this
+ * mapping unjudged - which is where a scope-column coercion bug already lived once.
+ */
+export declare function toIndexedEvent(row: EventRow): IndexedEvent;
+/**
+ * Whether a message ref may be named.
+ *
+ * `sourceMessageRef` is built as `source:channelId:turnId` (message-router.ts), and a
+ * channel scope id as `source:channelId` (scope-context.ts) - so a ref belongs to a
+ * caller's channel exactly when an active channel scope is its prefix. Compared as a
+ * prefix rather than parsed, because a turn id can itself contain a colon
+ * (`generated:<uuid>`) and splitting on the last one would silently mis-attribute it.
+ *
+ * This matters beyond tidiness: every memory carrying such a ref is also bound to
+ * global:system, which every caller holds, so an unchecked ref handed a private channel
+ * identifier to any agent that could read the memory at all.
+ */
+export declare function isMessageRefVisible(ref: string, scopes: readonly MemoryScopeRef[]): boolean;
+/** Resolve one memory's support against the live index and the scopes active now. */
+export declare function resolveMemoryProvenanceLive(adapter: DatabaseAdapter, memoryId: string, options: LiveProvenanceOptions): Promise<ProvenanceResolution>;
+//# sourceMappingURL=provenance-live.d.ts.map