@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/runtime/operations.d.ts

@@ -0,0 +1,236 @@
+/**
+ * The durable record of what this system actually changed, and what caused it.
+ *
+ * One table, `evidence_effects`. A `cause_state` CHECK forbids both "attributed
+ * with no cause" and "unattributed with a cause", and a BEFORE INSERT trigger
+ * rejects unusable cause ids, so the numerator and the denominator of coverage
+ * cannot be separated.
+ *
+ * This lives in core, next to the commitments it describes, for one reason: a
+ * change and its cause have to commit or roll back together. While owner work
+ * was stored in the daemon's operator database and this ledger beside it, that
+ * held. Moving owner work into the knowledge database without moving this would
+ * have put a change in one database and its cause in another, and a ledger that
+ * can disagree with the rows it describes is worse than no ledger.
+ *
+ * Every function here takes its adapter, so the caller decides which database is
+ * being recorded; nothing is resolved from a global.
+ *
+ * @module runtime/operations
+ */
+import type { JudgmentReceipt } from '../memory/judgment-types.js';
+import type { JudgmentAccess } from '../knowledge/judgments.js';
+export type EffectKind = 'task_create' | 'task_update' | 'report_update' | 'report_publish' | 'memory_write' | 'wiki_write' | 'file_export' | 'repair_request' | 'run_budget_stop';
+/** What it happened to. */
+export type EffectTarget = 'task' | 'report_slot' | 'memory' | 'wiki_page' | 'file' | 'issue' | 'run';
+/** Whether the change could name what caused it. */
+export type CauseState = 'attributed' | 'unattributed';
+/**
+ * WHY the change happened - the closed set (S2). `event` is the only kind that
+ * carries source event ids; the others are honestly id-less: a clock advanced,
+ * the owner asked in chat, or a card transition cascaded. Writers pass their
+ * kind explicitly - the ledger never infers.
+ */
+export type CauseKind = 'event' | 'owner_message' | 'clock' | 'card_transition';
+/** Kinds an unattributed (id-less) change may claim. */
+export type UnattributedCauseKind = Exclude<CauseKind, 'event'>;
+/** Fields every durable change carries, whether or not it can name a cause. */
+export interface ChangeInput {
+    /**
+     * The model run that produced the change, so it is traceable to a transcript.
+     * Null when no model run did - a host-internal write is not made more honest by
+     * inventing a run id for it.
+     */
+    runId?: string | null;
+    /** Evidence channel this change concerns, when it concerns one. */
+    channelId?: string | null;
+    kind: EffectKind;
+    targetType: EffectTarget;
+    targetId: string;
+    /** The written payload; hashed, never stored, so the ledger cannot leak content. */
+    payload: unknown;
+    atMs: number;
+}
+export interface EffectInput extends ChangeInput {
+    /** Events that caused it. Must not be empty. */
+    sourceEventIds: readonly string[];
+}
+export interface EffectRecord {
+    id: number;
+    runId: string | null;
+    channelId: string | null;
+    causeState: CauseState;
+    causeKind: CauseKind;
+    sourceEventIds: string[];
+    kind: EffectKind;
+    targetType: EffectTarget;
+    targetId: string;
+    payloadHash: string;
+    atMs: number;
+}
+/**
+ * Whether a value can serve as a cause at all.
+ *
+ * Callers ask before writing rather than discovering it as a constraint violation,
+ * because the answer changes what they record, not whether they may proceed: a malformed
+ * cause makes a change unattributed, it does not make the change illegitimate. Legacy
+ * rows really do carry 400-character source identifiers, and refusing to let the operator
+ * update a work item because its upstream id is the wrong shape would be enforcement
+ * bought with the owner's work.
+ */
+export declare function isUsableCause(value: string | null | undefined): value is string;
+export declare const EVIDENCE_EFFECTS_DDL: string;
+export interface EffectAdapter {
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            lastInsertRowid?: number | bigint;
+        };
+        all(...params: unknown[]): unknown[];
+    };
+}
+export declare function ensureEffectLedger(adapter: EffectAdapter): void;
+export declare class EffectWithoutCauseError extends Error {
+    constructor(kind: EffectKind, targetId: string);
+}
+/** Stable hash of what was written. The ledger proves a change happened, not what it said. */
+export declare function payloadHash(payload: unknown): string;
+/**
+ * Record a durable change.
+ *
+ * Throws rather than returning a failure when the cause is missing. A caller that wrote
+ * something and then could not say why must not proceed as if the write were accounted
+ * for - silently skipping the ledger row is how 1,169 runs closed as `done` while five
+ * receipts existed.
+ */
+export declare function recordEffect(adapter: EffectAdapter, input: EffectInput): number;
+/**
+ * Record a durable change that could not name what caused it.
+ *
+ * Deliberately a separate function with an uncomfortable name. Every call is an admission
+ * that the system changed something it cannot explain, and the point is that the count of
+ * these is visible next to the count of real effects rather than absent from both.
+ */
+export declare function recordUnattributedChange(adapter: EffectAdapter, input: ChangeInput, causeKind: UnattributedCauseKind): number;
+export interface EffectQuery {
+    id?: number;
+    runId?: string;
+    targetType?: EffectTarget;
+    targetId?: string;
+    causeState?: CauseState;
+    sinceMs?: number;
+    limit?: number;
+}
+/** Read effects back, newest first - the substrate a report projects from. */
+export declare function listEffects(adapter: EffectAdapter, query?: EffectQuery): EffectRecord[];
+export interface ChangeCoverage {
+    /** Changes that named the events behind them. */
+    attributed: number;
+    /** Changes the system made and could not explain. */
+    unattributed: number;
+}
+/**
+ * How much of what the system changed rests on evidence.
+ *
+ * The single number this ledger exists to make answerable, and the one the previous shape
+ * of the system could not produce at all.
+ */
+export declare function changeCoverage(adapter: EffectAdapter, sinceMs?: number, targetType?: EffectTarget): ChangeCoverage;
+export interface OperationRead {
+    operationId: string;
+    /** The command action the binding recorded — e.g. 'judgment.append'. */
+    action: string;
+    principalId: string;
+    payloadHash: string;
+    boundAt: number;
+    receiptKind: string | null;
+    receiptKey: string | null;
+    /** The committed judgment receipt, when the binding carries one. */
+    receipt: JudgmentReceipt | null;
+}
+export declare class OperationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type OperationReadAdapter = {
+    prepare(sql: string): {
+        get(...params: unknown[]): unknown;
+    };
+};
+/**
+ * §293: start from the command binding — principal, action, original receipt
+ * ref — check the caller's authority, then read the actual result. An absent
+ * binding and one bound to another principal answer identically: the caller
+ * may not learn the id exists.
+ */
+export declare function readOperation(adapter: OperationReadAdapter, operationId: string, access: JudgmentAccess): OperationRead;
+export declare const CHANGES_READ_TARGET_TYPES: readonly EffectTarget[];
+export declare const CHANGES_READ_CAUSE_STATES: readonly CauseState[];
+/**
+ * The read port over `evidence_effects`. The table lives in whichever database
+ * the host opened it in, so the catalog takes the port rather than an adapter —
+ * the port's owner decides the physical store.
+ */
+export interface ChangesLedger {
+    listChanges(query: EffectQuery): EffectRecord[];
+    changeCoverage(sinceMs?: number, targetType?: EffectTarget): ChangeCoverage;
+    listTurnInputs?(modelRunId: string, principalId: string, options?: {
+        afterId?: number;
+        limit?: number;
+    }): {
+        items: Array<{
+            inputId: number;
+            stimulusId: string;
+            kind: string;
+            principalId: string;
+            channelKey: string;
+            occurredAt: number;
+            status: string;
+            nativeState: string;
+        }>;
+        nextCursor: number | null;
+        runStatus: string;
+    };
+}
+export interface ChangesReadInput {
+    since?: unknown;
+    target_type?: unknown;
+    cause_state?: unknown;
+    limit?: unknown;
+}
+export interface ChangesReadFailure {
+    success: false;
+    code: 'invalid_argument';
+    error: string;
+}
+export interface ChangesReadResult {
+    success: true;
+    coverage: ChangeCoverage;
+    since: string;
+    /** Changes matching the filter in the window - not the number returned. */
+    total: number;
+    returned: number;
+    changes: Array<{
+        effect_id: number;
+        kind: string;
+        target_type: string;
+        target_id: string;
+        cause_state: string;
+        /** What KIND of cause moved this - the rubric's cause-citation item reads it. */
+        cause_kind: string;
+        source_event_ids: string[];
+        channel: string | null;
+        run_id: string | null;
+        at: string;
+    }>;
+}
+/**
+ * The window a read covers.
+ *
+ * Unparseable input falls back to the default and the resolved window is returned to the
+ * caller, so whatever was asked for, what was actually read is stated. Non-string input is
+ * not a window at all - a model emitting epoch milliseconds used to crash the tool on
+ * `.trim()`.
+ */
+export declare function parseChangesSince(since: unknown, nowMs: number): number;
+export declare function readChanges(ledger: ChangesLedger, input: ChangesReadInput, nowMs: number): ChangesReadResult | ChangesReadFailure;
+//# sourceMappingURL=operations.d.ts.map