@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/db/migrations/098-workflow-memory-kind.sql

@@ -0,0 +1,105 @@
+-- Workflow is a core memory kind. Rebuild the constrained projection while
+-- retaining every column, rowid, index, and full-text index trigger.
+DROP TABLE IF EXISTS decisions_w14;
+CREATE TABLE decisions_w14 (
+  id TEXT PRIMARY KEY,
+  topic TEXT NOT NULL,
+  decision TEXT NOT NULL,
+  reasoning TEXT,
+  outcome TEXT,
+  failure_reason TEXT,
+  limitation TEXT,
+  user_involvement TEXT,
+  session_id TEXT,
+  supersedes TEXT,
+  superseded_by TEXT,
+  refined_from TEXT,
+  confidence REAL DEFAULT 0.5 CHECK (confidence >= 0.0 AND confidence <= 1.0),
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+  needs_validation INTEGER DEFAULT 0 CHECK (needs_validation IN (0, 1)),
+  validation_attempts INTEGER DEFAULT 0,
+  last_validated_at INTEGER,
+  usage_count INTEGER DEFAULT 0,
+  trust_context TEXT,
+  usage_success INTEGER DEFAULT 0,
+  usage_failure INTEGER DEFAULT 0,
+  time_saved INTEGER DEFAULT 0,
+  evidence TEXT,
+  alternatives TEXT,
+  risks TEXT,
+  event_date TEXT,
+  kind TEXT DEFAULT 'decision'
+    CHECK (kind IN ('decision', 'preference', 'constraint', 'lesson', 'fact', 'task', 'schedule', 'workflow')),
+  status TEXT DEFAULT 'active'
+    CHECK (status IN ('active', 'superseded', 'contradicted', 'stale')),
+  summary TEXT,
+  is_static INTEGER DEFAULT 0,
+  event_datetime INTEGER,
+  agent_id TEXT,
+  model_run_id TEXT,
+  envelope_hash TEXT,
+  gateway_call_id TEXT,
+  source_refs_json TEXT,
+  provenance_json TEXT,
+  item_id TEXT,
+  record_kind TEXT NOT NULL DEFAULT 'legacy'
+    CHECK (record_kind IN ('legacy', 'judgment', 'commitment')),
+  payload_json TEXT NOT NULL DEFAULT '{}'
+    CHECK (json_valid(payload_json)),
+  applies_from INTEGER,
+  applies_until INTEGER,
+  duration_days INTEGER
+);
+
+INSERT INTO decisions_w14 (
+  rowid, id, topic, decision, reasoning, outcome, failure_reason, limitation,
+  user_involvement, session_id, supersedes, superseded_by, refined_from, confidence,
+  created_at, updated_at, needs_validation, validation_attempts, last_validated_at,
+  usage_count, trust_context, usage_success, usage_failure, time_saved, evidence,
+  alternatives, risks, event_date, kind, status, summary, is_static, event_datetime,
+  agent_id, model_run_id, envelope_hash, gateway_call_id, source_refs_json,
+  provenance_json, item_id, record_kind, payload_json, applies_from, applies_until,
+  duration_days
+)
+SELECT
+  rowid, id, topic, decision, reasoning, outcome, failure_reason, limitation,
+  user_involvement, session_id, supersedes, superseded_by, refined_from, confidence,
+  created_at, updated_at, needs_validation, validation_attempts, last_validated_at,
+  usage_count, trust_context, usage_success, usage_failure, time_saved, evidence,
+  alternatives, risks, event_date, kind, status, summary, is_static, event_datetime,
+  agent_id, model_run_id, envelope_hash, gateway_call_id, source_refs_json,
+  provenance_json, item_id, record_kind, payload_json, applies_from, applies_until,
+  duration_days
+FROM decisions;
+
+DROP TABLE decisions;
+ALTER TABLE decisions_w14 RENAME TO decisions;
+
+CREATE INDEX idx_decisions_event_datetime ON decisions(event_datetime);
+CREATE INDEX idx_decisions_event_datetime_backfill ON decisions(event_datetime);
+CREATE INDEX idx_decisions_envelope_hash ON decisions(envelope_hash);
+CREATE INDEX idx_decisions_model_run_id ON decisions(model_run_id);
+CREATE INDEX idx_decisions_gateway_call_id ON decisions(gateway_call_id);
+CREATE INDEX idx_decisions_item ON decisions(item_id);
+
+CREATE TRIGGER decisions_ai AFTER INSERT ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+CREATE TRIGGER decisions_ad BEFORE DELETE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES ('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+CREATE TRIGGER decisions_au BEFORE UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES ('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+CREATE TRIGGER decisions_au2 AFTER UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+INSERT INTO decisions_fts(decisions_fts) VALUES ('rebuild');
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (98, 'Add workflow as a memory kind');

package/dist/action-contracts.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Action contracts — the one surface CLI/MCP clients call.
+ *
+ * §4.2: schema, description, examples and the exec binding live in ONE catalog
+ * entry; help/schema/examples are generated from the same contract. Input that
+ * fails the schema never reaches exec.
+ */
+/** JSON-Schema subset the catalog validates against. */
+export interface ActionSchemaObject {
+    /** Short caller-facing meaning and example shape for this input field. */
+    description?: string;
+    type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    properties?: Record<string, ActionSchemaObject>;
+    required?: readonly string[];
+    additionalProperties?: boolean;
+    items?: ActionSchemaObject;
+    enum?: readonly unknown[];
+    const?: unknown;
+    oneOf?: readonly ActionSchemaObject[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    /** Longest a string value may be. */
+    maxLength?: number;
+    /** Fewest elements an array value may carry. */
+    minItems?: number;
+    /** Most elements an array value may carry. */
+    maxItems?: number;
+    /** Anchored regular expression a string value must match. */
+    pattern?: string;
+}
+export interface ActionExample {
+    title: string;
+    input: Record<string, unknown>;
+}
+/**
+ * What `client.describe(action)` returns. Everything a caller needs to build a
+ * call — name, summary, input schema, examples — without executing anything.
+ */
+export interface ActionContract {
+    name: string;
+    summary: string;
+    inputSchema: ActionSchemaObject;
+    examples?: readonly ActionExample[];
+    /**
+     * This action persists text that a later read can return. Dispatch scans the
+     * input of such a call for secret-shaped material and refuses it, because
+     * the one real leak path a chat-reachable caller has is writing a secret
+     * into something recall will hand back. Declared by the contract rather than
+     * listed in dispatch, so a new recallable write cannot be added without
+     * saying that it is one.
+     */
+    recallableWrite?: boolean;
+    /**
+     * This action reads a raw connector. Dispatch refuses the call unless the
+     * principal's grant names that connector.
+     *
+     * The rule existed before as a host enforcer keyed on tool names, reachable
+     * only from the one caller that went through the tool layer. A program
+     * calling the same action over the socket carried no envelope and met no
+     * check, so the same read was bounded for one caller and unbounded for the
+     * other. Declared by the contract for the same reason `recallableWrite` is:
+     * a new connector read cannot be added without saying that it is one.
+     *
+     * `fromInput` names the input field carrying the connector, for an action
+     * that reads whichever source it is told to. `fixed` names it outright, for
+     * an action that always reads the same one.
+     */
+    readsConnector?: {
+        fromInput: string;
+    } | {
+        fixed: string;
+    };
+}
+/**
+ * One call. `operationId` is issued by the common client before the call and,
+ * for knowledge commands, becomes the commandId — retransmission reuses it,
+ * topic/body similarity is never used to guess sameness.
+ */
+export interface ActionCall {
+    action: string;
+    input?: unknown;
+    operationId?: string;
+}
+export type ActionFailureKind = 'unknown_action' | 'invalid_input' | 'denied' | 'failed' | 'internal';
+/**
+ * Call-site facts the SERVER side knows — never caller input. Provenance is
+ * composed from the call authority plus these facts (§240: provenance is
+ * composed from the current call authority); a field stays absent rather than
+ * being trusted from
+ * the payload. The model run, the tool call, the context packet, and the
+ * source turn are all things only the host can truthfully state.
+ */
+/** Native harness identity, supplied per call by the transport hook, never action input. */
+export interface NativeToolCaller {
+    session_id: string;
+    tool_use_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+/** Wire facts carry identity only; the host resolves authority and run provenance. */
+export interface ClientSessionFacts {
+    nativeCaller?: NativeToolCaller;
+}
+export interface ActionSessionFacts {
+    nativeCaller?: NativeToolCaller;
+    /** The model run this call belongs to. */
+    modelRunId?: string;
+    /** The surface the call arrived on (e.g. 'mama_save'). */
+    toolName?: string;
+    /** The tool-call id the host issued for this invocation. */
+    gatewayCallId?: string;
+    /** The verified envelope hash this call ran under — an audit fact, not authority. */
+    envelopeHash?: string;
+    /** The compiled context packet this call is bound to, if any. */
+    contextPacketId?: string;
+    /** The conversation turn this call belongs to. */
+    sourceTurnId?: string;
+    /** The source message ref this call is bound to. */
+    sourceMessageRef?: string;
+    /** Which lane wrote — 'memory_agent' for the memory lane, else main. */
+    actor?: 'memory_agent' | 'main_agent';
+    /** Extra source refs the host attests (packet refs, message refs). */
+    sourceRefs?: readonly string[];
+    /** The workorder attempt this call is bound to, if the host bound one. */
+    workorderAttemptId?: number;
+    /** The call ran under a member-scope-required envelope — owner actions must refuse. */
+    memberScopeRequired?: boolean;
+    /** The bounded-run batch this call inherits — effects record it as their cause. */
+    causeEventIds?: readonly string[];
+    /** The channel this call runs on, if the host bound one. */
+    channelId?: string;
+    /**
+     * Inclusive source-event ceiling for a replay turn. The feeder states this
+     * fact; callers cannot widen it through action input. Absent means live time.
+     */
+    replaySourceEndMs?: number;
+    /**
+     * The turn's recent conversation, for a checkpoint that hands work over.
+     *
+     * A host fact and only a host fact: the model does not hold the transcript,
+     * so asking it for one asks it to write one. It was an input field that one
+     * caller filled from the session store and every other caller left empty.
+     */
+    recentConversation?: readonly unknown[];
+    /**
+     * Host-issued wiki workorder range: the owner date and the updated bounds
+     * the wiki turn is allowed to touch. An agent cannot mint or widen this; a
+     * null field is an honest "not bounded" from the host.
+     */
+    wikiTaskRange?: {
+        ownerDate: string | null;
+        rangeStartMs: number | null;
+        rangeEndMs: number | null;
+        connectors: readonly string[] | null;
+        updatedSince: string | null;
+        updatedBefore: string | null;
+    };
+    /**
+     * The verified envelope's allowed destinations (e.g. drive roots) — host
+     * state for destination-gated reads like source.search's folder resolve.
+     */
+    allowedDestinations?: readonly {
+        kind: string;
+        id: string;
+    }[];
+    /** The host-resolved role name this call runs under (e.g. 'owner_console'). */
+    agentRole?: string;
+    /**
+     * Whose run this is, for the call receipt: owner scope, project and channel.
+     *
+     * Stated, never derived here. A host that can name all three says so and its
+     * calls are attributable; a host that cannot omits the field and its calls are
+     * honestly unattributed. Deriving it from `access` would be a second answer to
+     * a question the host already answers.
+     */
+    runEvidenceScope?: {
+        ownerScope: string;
+        projectId: string;
+        channelId?: string | null;
+    };
+    /** The verified envelope's expiry (ISO) — bounds any capability a host port mints. */
+    envelopeExpiresAt?: string;
+}
+export interface ActionFailure {
+    kind: ActionFailureKind;
+    code: string;
+    message: string;
+}
+/**
+ * The common result every call returns. `unknown` is reserved for the case the
+ * transport loses the answer after a possible commit — dispatch itself only
+ * produces `completed` or `failed`.
+ */
+/**
+ * `experienceRef` points at the call's own receipt, so the agent that made the
+ * call can read what the run recorded. It rides the envelope rather than the
+ * answer: `data` is the action's shape and a refusal has no `data` at all,
+ * while a refusal is exactly the call whose receipt is worth reading.
+ */
+export type ActionResult = {
+    status: 'completed';
+    operationId?: string;
+    experienceRef?: string;
+    data: unknown;
+} | {
+    status: 'failed' | 'unknown';
+    operationId?: string;
+    experienceRef?: string;
+    error: ActionFailure;
+};
+//# sourceMappingURL=action-contracts.d.ts.map

package/dist/action-contracts.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Action contracts — the one surface CLI/MCP clients call.
+ *
+ * §4.2: schema, description, examples and the exec binding live in ONE catalog
+ * entry; help/schema/examples are generated from the same contract. Input that
+ * fails the schema never reaches exec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=action-contracts.js.map

package/dist/api/catalog.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Action catalog — one contract bound to its implementation.
+ *
+ * §4.2: each entry carries schema, description, examples and exec together; an
+ * action that is not implemented is not listed. Legacy name translation lives
+ * here exactly once, in the alias table — a retired tool never survives as an
+ * alias that calls the old implementation.
+ */
+import type { ActionContract, ActionSchemaObject, ActionSessionFacts } from '../action-contracts.js';
+import { type JudgmentAccess } from '../knowledge/judgments.js';
+import type { TextCompletion } from '../runtime/text-completion.js';
+import type { DatabaseInstance } from '../db-manager.js';
+import type { Knowledge } from '../knowledge/index.js';
+import { type ChangesLedger, type EffectAdapter } from '../runtime/operations.js';
+/**
+ * Server-side authority for one call — from the session credential, never
+ * input. `operationId` is the id the common client issued for this call; for
+ * knowledge commands it becomes the commandId, so a command action cannot run
+ * without one. `session` carries the call-site facts only the host can
+ * truthfully state (model run, tool call id, context packet) — provenance is
+ * composed from these plus `access`, never trusted from the payload.
+ */
+export interface ActionContext {
+    access: JudgmentAccess;
+    operationId?: string;
+    session?: ActionSessionFacts;
+    /**
+     * The host-composed read window for citation reads — connector grant,
+     * project/tenant filters, and the observation-time clamp the envelope states.
+     * Like `access` and `session` it is server-stated, never caller input: the
+     * caller can only narrow within it through `input.scopes`, and an absent
+     * window fails closed (no connectors means no raw events).
+     */
+    readAllowance?: MemoryReadAllowance;
+    /**
+     * Host-bound cancellation handle for long reads/downloads. Absent over
+     * transports that cannot carry it — actions must run without it.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Host-composed visibility window for reads that cite raw events. Every field
+ * is derived from envelope state by the host, the same way the reader derives
+ * it — the action consumes it as-is rather than trusting payload claims.
+ */
+export interface MemoryReadAllowance {
+    /** Raw connectors this call may read. Empty means NO raw events, never all. */
+    connectors: readonly string[];
+    /** Explicit connector-wide reads stated by the principal, independent of tenant scoping. */
+    wideConnectors?: readonly string[];
+    /** Per-connector channel grant, already narrowed to the envelope's scopes. */
+    channels?: Record<string, readonly string[]>;
+    /** Project window, mirroring the reader's filter on the same column. */
+    projectIds?: readonly string[];
+    /** Tenant window for narrower reads; an explicit connector-wide owner grant is separate. */
+    tenantId?: string | null;
+    /** Observation-time clamp (envelope `as_of`), epoch ms. */
+    minObservedMs?: number | null;
+    maxObservedMs?: number | null;
+    /** Inclusive source/event-time ceiling stated by an active replay turn. */
+    maxSourceMs?: number | null;
+}
+export type ActionExec = (input: unknown, context: ActionContext) => unknown | Promise<unknown>;
+export interface ActionRegistration {
+    contract: ActionContract;
+    exec: ActionExec;
+}
+export declare class UnknownActionError extends Error {
+    readonly code = "unknown_action";
+    constructor(name: string);
+}
+export interface ActionCatalog {
+    /** Every registered contract — the executable surface, nothing more. */
+    list(): ActionContract[];
+    /** One contract by name or alias; throws UnknownActionError. */
+    describe(name: string): ActionContract;
+    /** The exec binding by name or alias; throws UnknownActionError. */
+    entry(name: string): ActionRegistration;
+}
+export declare function createCatalog(registrations: readonly ActionRegistration[], aliases?: Readonly<Record<string, string>>): ActionCatalog;
+export declare const scopeRefSchema: ActionSchemaObject;
+export declare const recordLinkSchema: ActionSchemaObject;
+/**
+ * The actions this build actually implements. `graph.query` reads the twin-edge
+ * graph and `graph.identity.correct` is the registry_corrections transaction —
+ * the action behind `registry_correct`; the `work.*` commands are the
+ * commitment log's public write/read surface — the actions behind `task_create`
+ * / `task_update` / `task_reclassify` / `task_list`; `operation.get` is how a
+ * caller settles a call whose reply was lost.
+ */
+export declare function coreActionRegistrations(knowledge: Knowledge, adapter: DatabaseInstance, deps?: {
+    /**
+     * The host's effect-ledger read port for `work.changes`. The
+     * `evidence_effects` store is host-opened, so the catalog takes the port —
+     * absent means the action is absent (the catalog never lists an action it
+     * cannot execute).
+     */
+    effects?: ChangesLedger;
+    /**
+     * The host's effect-ledger WRITE handle. A recallable write leaves a
+     * receipt naming what caused it, so a crash between the write and the
+     * batch ACK does not re-run the batch and save the same thing twice. The
+     * store is host-opened like the read port above; absent means the write
+     * still happens and leaves no receipt, which the coverage count shows.
+     */
+    effectLedger?: () => EffectAdapter | undefined;
+    /**
+     * The model the runtime opened, read at call time.
+     *
+     * A lookup rather than a value because the runtime opens after the catalog
+     * is built — the same late binding every other host-opened dependency
+     * uses. Absent means this host states no model, and the one action that
+     * would ask for one (`memory.search` with `useReranking`) says so instead
+     * of opening its own (§2.1).
+     */
+    runner?: () => TextCompletion | undefined;
+}): ActionRegistration[];
+//# sourceMappingURL=catalog.d.ts.map