@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/agent-situation/types.d.ts

@@ -0,0 +1,195 @@
+import type { MemoryScopeRef } from '../memory/types.js';
+import type { TwinRef } from '../edges/types.js';
+export type SituationFocus = 'decisions' | 'risks' | 'open_questions' | 'cases' | 'raw';
+export type SituationRefKind = TwinRef['kind'] | 'memory';
+export interface SituationRef {
+    kind: SituationRefKind;
+    id: string;
+}
+export interface SituationProjectRef {
+    kind: 'project';
+    id: string;
+}
+export interface AgentSituationEffectiveFilters {
+    scopes: MemoryScopeRef[];
+    connectors: string[];
+    project_refs: SituationProjectRef[];
+    tenant_id: string;
+    as_of?: string | null;
+}
+export interface AgentSituationCacheKeyInput extends AgentSituationEffectiveFilters {
+    range_start_ms: number;
+    range_end_ms: number;
+    focus: SituationFocus[];
+    limit: number;
+    ranking_policy_version: string;
+}
+export interface AgentSituationCacheKeyResult {
+    cacheKey: string;
+    canonicalInput: AgentSituationCacheKeyInput;
+    canonicalJson: string;
+    filtersHash: string;
+    scopeHash: string;
+}
+export type SituationCaveatCode = 'connector_stale' | 'some_sources_unavailable' | 'low_confidence_visible_memory' | 'graph_api_unavailable_until_m6' | 'case_visibility_incomplete' | 'no_visible_sources';
+export interface SituationSourceCoverage {
+    connector?: string;
+    channel_id?: string | null;
+    memory_scope?: MemoryScopeRef;
+    raw_count: number;
+    memory_count: number;
+    case_count: number;
+    edge_count: number;
+    last_seen: string | null;
+    stale: boolean;
+}
+export interface SituationBriefing {
+    decisions: string[];
+    facts: string[];
+    open_questions: string[];
+    risks: string[];
+}
+export interface SituationRankedItem {
+    ref: SituationRef;
+    kind: string;
+    score: number;
+    reasons: string[];
+    caveats: string[];
+}
+export interface SituationPendingHumanQuestion {
+    memory_id: string;
+    title: string;
+    summary: string;
+}
+export interface SituationEntityCluster {
+    label: string;
+    entity_refs: Array<{
+        kind: 'entity';
+        id: string;
+    }>;
+    source_refs: Array<{
+        kind: 'raw' | 'memory' | 'case';
+        id: string;
+    }>;
+    caveats: string[];
+}
+export interface SituationRecommendedTool {
+    tool: 'raw.search' | 'raw.searchAll' | 'raw.window' | 'memory.recall' | 'graph.neighborhood';
+    args: Record<string, unknown>;
+    reason: string;
+    expected_refs: SituationRef[];
+}
+export interface AgentSituationPacket {
+    packet_id: string;
+    scope: MemoryScopeRef[];
+    range_start: string;
+    range_end: string;
+    generated_at: string;
+    freshness: Record<string, unknown>;
+    source_coverage: SituationSourceCoverage[];
+    briefing: SituationBriefing;
+    ranked_items: SituationRankedItem[];
+    top_memory_refs: string[];
+    pending_human_questions: SituationPendingHumanQuestion[];
+    entity_clusters: SituationEntityCluster[];
+    recommended_next_tools: SituationRecommendedTool[];
+    ranking_policy_version: string;
+    ttl_seconds: number;
+    generated_from_slice_ids: string[];
+    caveats: string[];
+    cache: {
+        hit: boolean;
+        cache_key: string;
+        expires_at: string;
+    };
+}
+export interface AgentSituationInput {
+    scope: MemoryScopeRef[];
+    range_start_ms: number;
+    range_end_ms: number;
+    focus: SituationFocus[];
+    limit: number;
+    effective_filters: AgentSituationEffectiveFilters;
+    envelope_hash: string;
+    agent_id: string;
+    model_run_id: string;
+    ranking_policy_version?: string;
+    refresh?: boolean;
+    now_ms?: number;
+}
+export interface AgentSituationPacketRecord {
+    packet_id: string;
+    cache_key: string;
+    scope_json: string;
+    scope: MemoryScopeRef[];
+    scope_hash: string;
+    range_start_ms: number;
+    range_end_ms: number;
+    focus_json: string;
+    focus: SituationFocus[];
+    envelope_hash: string;
+    envelope_effective_filters_json: string;
+    envelope_effective_filters: AgentSituationEffectiveFilters;
+    envelope_effective_filters_hash: string;
+    ranking_policy_version: string;
+    generated_at: number;
+    expires_at: number;
+    ttl_seconds: number;
+    freshness_json: string;
+    freshness: Record<string, unknown>;
+    source_coverage_json: string;
+    source_coverage: SituationSourceCoverage[];
+    briefing_json: string;
+    briefing: SituationBriefing;
+    ranked_items_json: string;
+    ranked_items: SituationRankedItem[];
+    top_memory_refs_json: string;
+    top_memory_refs: string[];
+    pending_human_questions_json: string;
+    pending_human_questions: SituationPendingHumanQuestion[];
+    entity_clusters_json: string;
+    entity_clusters: SituationEntityCluster[];
+    recommended_next_tools_json: string;
+    recommended_next_tools: SituationRecommendedTool[];
+    generated_from_slice_ids_json: string;
+    generated_from_slice_ids: string[];
+    caveats_json: string;
+    caveats: string[];
+    agent_id: string;
+    model_run_id: string;
+    input_snapshot_ref: string;
+    source_refs_json: string;
+    source_refs: SituationRef[];
+    tenant_id: string;
+    project_id: string;
+    memory_scope_kind: MemoryScopeRef['kind'];
+    memory_scope_id: string;
+    created_at: number;
+}
+export interface AgentSituationLease {
+    cache_key: string;
+    ranking_policy_version: string;
+    lease_owner: string;
+    lease_expires_at: number;
+    created_at: number;
+}
+export interface AgentSituationCandidate {
+    ref: SituationRef;
+    kind: string;
+    title: string;
+    summary: string;
+    timestamp_ms: number;
+    confidence?: number | null;
+    status?: string | null;
+    is_open_question?: boolean;
+    has_debate_edge?: boolean;
+    connector?: string | null;
+    channel_id?: string | null;
+    scope?: MemoryScopeRef | null;
+}
+export interface SituationScore {
+    score: number;
+    reasons: string[];
+    caveats: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent-situation/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/canonicalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Canonical JSON serializer + SHA-256 hash for `case_corrections.target_ref`.
+ *
+ * Phase 1 of MAMA Case-First Memory System (spec §5.4 Option C).
+ *
+ * Behavior:
+ * - recursively sort object keys in lexicographic UTF-8 order
+ * - preserve array order (semantic)
+ * - reject undefined values with typed error code `canonicalize.undefined_value`
+ * - reject function values with typed error code `canonicalize.function_value`
+ * - reject non-finite numbers (NaN, +/- Infinity) with `canonicalize.non_finite_number`
+ * - serialize normalized value via JSON.stringify (after normalization)
+ * - hash canonical JSON string with SHA-256 over UTF-8 bytes → 32-byte Buffer
+ *
+ * No top-level await. No ESM-only runtime dependency. Safe for CJS consumers
+ * (mcp-server, claude-code-plugin) via package export `./canonicalize`.
+ *
+ * @module canonicalize
+ */
+export type CanonicalizeErrorCode = 'canonicalize.undefined_value' | 'canonicalize.function_value' | 'canonicalize.non_finite_number';
+export declare class CanonicalizeError extends Error {
+    readonly code: CanonicalizeErrorCode;
+    constructor(code: CanonicalizeErrorCode, message: string);
+}
+/**
+ * Produce a canonical JSON string for `value`.
+ *
+ * Two calls with semantically equivalent input produce byte-identical output.
+ */
+export declare function canonicalizeJSON(value: unknown): string;
+/**
+ * Produce the 32-byte SHA-256 digest of the canonical JSON form of `value`.
+ *
+ * Invariant: `targetRefHash(obj)` === `targetRefHash(canonicalizeJSON(obj))`.
+ */
+export declare function targetRefHash(value: unknown): Buffer;
+export declare function targetRefHashCanonicalJSON(canonicalJson: string): Buffer;
+//# sourceMappingURL=canonicalize.d.ts.map

package/dist/canonicalize.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Canonical JSON serializer + SHA-256 hash for `case_corrections.target_ref`.
+ *
+ * Phase 1 of MAMA Case-First Memory System (spec §5.4 Option C).
+ *
+ * Behavior:
+ * - recursively sort object keys in lexicographic UTF-8 order
+ * - preserve array order (semantic)
+ * - reject undefined values with typed error code `canonicalize.undefined_value`
+ * - reject function values with typed error code `canonicalize.function_value`
+ * - reject non-finite numbers (NaN, +/- Infinity) with `canonicalize.non_finite_number`
+ * - serialize normalized value via JSON.stringify (after normalization)
+ * - hash canonical JSON string with SHA-256 over UTF-8 bytes → 32-byte Buffer
+ *
+ * No top-level await. No ESM-only runtime dependency. Safe for CJS consumers
+ * (mcp-server, claude-code-plugin) via package export `./canonicalize`.
+ *
+ * @module canonicalize
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalizeError = void 0;
+exports.canonicalizeJSON = canonicalizeJSON;
+exports.targetRefHash = targetRefHash;
+exports.targetRefHashCanonicalJSON = targetRefHashCanonicalJSON;
+const node_crypto_1 = require("node:crypto");
+class CanonicalizeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CanonicalizeError';
+        this.code = code;
+    }
+}
+exports.CanonicalizeError = CanonicalizeError;
+function normalize(value, path = '$') {
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === 'undefined') {
+        throw new CanonicalizeError('canonicalize.undefined_value', `undefined is not serializable (at ${path})`);
+    }
+    if (type === 'function') {
+        throw new CanonicalizeError('canonicalize.function_value', `functions are not serializable (at ${path})`);
+    }
+    if (type === 'number') {
+        const n = value;
+        if (!Number.isFinite(n)) {
+            throw new CanonicalizeError('canonicalize.non_finite_number', `non-finite number ${String(n)} is not serializable (at ${path})`);
+        }
+        return n;
+    }
+    if (type === 'bigint') {
+        return value.toString();
+    }
+    if (type === 'string' || type === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, idx) => normalize(item, `${path}[${idx}]`));
+    }
+    if (type === 'object') {
+        const obj = value;
+        const sortedKeys = Object.keys(obj).sort();
+        const out = {};
+        for (const key of sortedKeys) {
+            out[key] = normalize(obj[key], `${path}.${key}`);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Produce a canonical JSON string for `value`.
+ *
+ * Two calls with semantically equivalent input produce byte-identical output.
+ */
+function canonicalizeJSON(value) {
+    return JSON.stringify(normalize(value));
+}
+/**
+ * Produce the 32-byte SHA-256 digest of the canonical JSON form of `value`.
+ *
+ * Invariant: `targetRefHash(obj)` === `targetRefHash(canonicalizeJSON(obj))`.
+ */
+function targetRefHash(value) {
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            const canonicalJson = canonicalizeJSON(parsed);
+            if (canonicalJson === value) {
+                return targetRefHashCanonicalJSON(value);
+            }
+        }
+        catch {
+            // Raw strings are canonicalized below.
+        }
+    }
+    const json = canonicalizeJSON(value);
+    return targetRefHashCanonicalJSON(json);
+}
+function targetRefHashCanonicalJSON(canonicalJson) {
+    const json = canonicalJson;
+    return (0, node_crypto_1.createHash)('sha256').update(json, 'utf8').digest();
+}
+//# sourceMappingURL=canonicalize.js.map

package/dist/cases/case-links.d.ts

@@ -0,0 +1,116 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import { type ImmediateTransactionAdapter } from './sqlite-transaction.js';
+export type CaseLinkType = 'related' | 'supersedes-case' | 'subcase-of' | 'blocked-by' | 'duplicate-of';
+export type CaseLinkSourceKind = 'manual' | 'wiki_compiler' | 'hitl_correction' | 'system_backfill';
+export interface CaseLinkRecord {
+    link_id: string;
+    case_id_from: string;
+    case_id_to: string;
+    link_type: CaseLinkType;
+    created_at: string;
+    created_by: string;
+    confidence: number | null;
+    reason_json: string | null;
+    source_kind: CaseLinkSourceKind;
+    source_ref: string | null;
+    source_ref_fingerprint: Buffer | null;
+    source_ref_fingerprint_hex: string | null;
+    revoked_at: string | null;
+    revoked_by: string | null;
+    revoke_reason: string | null;
+}
+export interface CaseLinkCreateInput {
+    link_id?: string;
+    case_id_from: string;
+    case_id_to: string;
+    link_type: CaseLinkType;
+    created_by: string;
+    confidence?: number | null;
+    reason_json?: string | Record<string, unknown> | null;
+    source_kind?: CaseLinkSourceKind;
+    source_ref?: string | null;
+    source_ref_fingerprint?: Buffer | Uint8Array | null;
+    unsuppress_wiki_tombstone?: boolean;
+    expected_current_value_json?: string | null;
+    reconfirm_token?: string | null;
+    session_id?: string | null;
+    now?: string;
+}
+export interface CaseLinkRevokeInput {
+    link_id: string;
+    revoked_by: string;
+    revoke_reason: string;
+    expected_current_value_json?: string | null;
+    reconfirm_token?: string | null;
+    session_id?: string | null;
+    now?: string;
+}
+export interface CaseLinkRequiresReconfirmResult {
+    kind: 'requires_reconfirm';
+    code: 'case.correction_requires_reconfirm';
+    case_id: string;
+    target_kind: 'case_link';
+    target_ref_json: string;
+    current_value_json: string;
+    old_value_json: string | null;
+    proposed_new_value_json: string;
+    reconfirm_token: string;
+    reconfirm_token_expires_at: string;
+    message: string;
+}
+export type CaseLinkCreateResult = {
+    kind: 'created';
+    link_id: string;
+    source_ref_fingerprint_hex: string;
+} | CaseLinkRequiresReconfirmResult | {
+    kind: 'rejected';
+    code: 'case.precompile_gap' | 'case.terminal_status' | 'case.self_link' | 'case.wiki_tombstone_conflict' | 'case.correction_active_conflict' | 'case.reconfirm_token_replayed';
+    message: string;
+    case_id?: string;
+};
+export type CaseLinkRevokeResult = {
+    kind: 'revoked';
+    link_id: string;
+} | CaseLinkRequiresReconfirmResult | {
+    kind: 'rejected';
+    code: 'case.case_link_not_found' | 'case.wiki_tombstone_fingerprint_missing' | 'case.reconfirm_token_replayed';
+    message: string;
+    link_id?: string;
+};
+export interface ListActiveCaseLinksResult {
+    terminal_case_id: string;
+    resolved_via_case_id: string | null;
+    chain: string[];
+    links: CaseLinkRecord[];
+}
+export interface BackfillStructuralLinksResult {
+    duplicate_of_inserted: number;
+    subcase_of_inserted: number;
+}
+type CaseLinkAdapter = Pick<DatabaseAdapter, 'prepare' | 'transaction'> & Partial<Pick<ImmediateTransactionAdapter, 'exec'>>;
+export declare function sha256TombstoneFingerprint(input: {
+    source_case_id: string;
+    target_case_id: string;
+    link_type: CaseLinkType;
+}): Buffer;
+export declare function createCaseLink(adapter: DatabaseAdapter, input: CaseLinkCreateInput): CaseLinkCreateResult;
+export declare function revokeCaseLink(adapter: DatabaseAdapter, input: CaseLinkRevokeInput): CaseLinkRevokeResult;
+export declare function listActiveCaseLinks(adapter: DatabaseAdapter, caseId: string): ListActiveCaseLinksResult;
+export declare function isWikiTombstoneActive(adapter: DatabaseAdapter | CaseLinkAdapter, input: {
+    source_case_id: string;
+    target_case_id: string;
+    link_type: CaseLinkType;
+}): boolean;
+export declare function unsuppressWikiTombstone(adapter: DatabaseAdapter, input: {
+    source_case_id: string;
+    target_case_id: string;
+    link_type: CaseLinkType;
+    unsuppressed_by: string;
+    now?: string;
+}): {
+    kind: 'unsuppressed';
+    unsuppressed_count: number;
+};
+export declare function backfillStructuralLinks(adapter: DatabaseAdapter): BackfillStructuralLinksResult;
+export {};
+//# sourceMappingURL=case-links.d.ts.map