@jungjaehoon/mama-core 1.5.0 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @jungjaehoon/mama-core
 
-Shared core modules for MAMA (Memory-Augmented MCP Assistant).
+Shared memory, provenance, graph, and context substrate for MAMA.
 
 ## What is MAMA Core?
 
@@ -10,7 +10,9 @@ MAMA Core is a shared package containing the fundamental modules used by all MAM
 - **claude-code-plugin**: Claude Code plugin
 - **standalone**: Standalone HTTP server
 
-This package provides embedding generation, database management, decision tracking, and other core functionality without the transport layer (MCP/HTTP).
+This package provides embedding generation, database management, scoped memory, provenance, raw
+evidence refs, graph/entity helpers, and worker context primitives without the transport layer
+(MCP/HTTP).
 
 ## Installation
 
@@ -78,7 +80,7 @@ const mamaApi = require('@jungjaehoon/mama-core/mama-api');
 
 - **memory/api** - Scoped memory operations
   - `saveMemory(input)` - Save typed memory with scopes and optional event_date (preference, fact, decision, lesson, constraint)
-  - `recallMemory(query, options)` - Truth-aware recall with scope filtering
+  - `recallMemory(query, options)` - Truth-aware recall with scope filtering, strictness modes, and retrieval diagnostics
   - `buildProfile(scopes)` - Build memory profile (static/dynamic/evidence)
   - `ingestMemory(input)` - Ingest raw content as memory
   - `ingestConversation(input)` - Decompose conversations into typed memory units via optional LLM extraction
@@ -102,14 +104,39 @@ const mamaApi = require('@jungjaehoon/mama-core/mama-api');
 - **memory/channel-summary-state-store** - Channel state management
   - `recordChannelAudit(input)` - Accumulate audit outcomes into channel state
 
+- **memory/provenance** - Trusted memory provenance
+  - Preserves compact runtime origin metadata in `provenance_json`
+  - Keeps underlying raw/memory/case/entity refs in `source_refs_json`
+  - Ignores caller-supplied untrusted provenance on public paths
+
+- **model-runs** - Agent execution lineage
+  - `model-runs/store` records model run lifecycle and replay metadata
+  - `model-runs/tool-trace-store` records tool calls for later audit and reconstruction
+
+- **connectors/raw-query** - Unified raw evidence reads
+  - Query raw connector rows through scope-aware filters
+  - Preserve raw source ids for downstream provenance
+
+- **agent-situation** - Worker situation packets
+  - Build, rank, cache, insert, and read append-only situation packets for worker context
+
+- **agent-graph** - Worker graph/entity helpers
+  - Query graph neighborhoods, resolve entities, and write aliases with visibility checks
+
 ### Core API (Legacy)
 
 - **mama-api** - High-level API interface (wraps memory API)
   - `save(decision)` - Save decision
   - `recall(topic)` - Retrieve decision history
-  - `suggest(query)` - Semantic search with hybrid FTS5 + vector + recency
+  - `suggest(query, options)` - Semantic search with hybrid FTS5 + vector + recency, strictness controls, and diagnostics
   - `updateOutcome(id, outcome)` - Update decision outcome
 
+- **search/search-quality** - Search option normalization
+  - `normalizeSearchQualityOptions(options)` - Normalize recall/balanced/strict thresholds and confirmation requirements
+
+- **edges** - Twin edge ledger
+  - Validate refs and store durable edges between memory, raw, entity, case, and packet refs
+
 - **decision-tracker** - Decision graph management
   - `learnDecision(decision)` - Learn from decision
   - `createEdgesFromReasoning(reasoning)` - Parse decision links
@@ -135,7 +162,7 @@ const mamaApi = require('@jungjaehoon/mama-core/mama-api');
 ## Dependencies
 
 - **@huggingface/transformers** - Local embedding generation
-- **node:sqlite** - Built-in SQLite runtime (Node.js 22+)
+- **better-sqlite3** - SQLite runtime with FTS5 support
 - **Pure-TS cosine similarity** - Vector search (no native extensions)
 
 ## Development
@@ -153,7 +180,7 @@ pnpm test:watch
 
 ## Test Coverage
 
-- 72 unit tests across 17 test files
+- 120+ unit/integration test files in `packages/mama-core/tests`
 - 100% passing
 - Tests cover:
   - Config loader, database initialization, module exports
@@ -161,6 +188,9 @@ pnpm test:watch
   - Truth store, evolution engine, scope schema
   - Channel summary, channel summary state
   - Event store, finding store, bootstrap builder
+  - Memory provenance, model runs, tool traces
+  - Twin edges, raw query, agent situation, agent graph
+  - Strict search diagnostics and rollup provenance
   - Legacy shim compatibility
 
 ## Architecture
@@ -175,7 +205,7 @@ packages/mama-core/
 │   ├── db-manager.ts         # Database management
 │   ├── mama-api.ts           # High-level API (wraps memory API)
 │   ├── db-adapter/           # Database adapter (SQLite)
-│   └── memory/               # Memory infrastructure
+│   ├── memory/               # Memory infrastructure
 │       ├── types.ts          # MemoryRecord, MemoryScopeRef, RecallBundle, etc.
 │       ├── api.ts            # saveMemory, recallMemory, buildProfile, etc.
 │       ├── truth-store.ts    # Truth projection layer
@@ -188,13 +218,19 @@ packages/mama-core/
 │       ├── channel-summary-state-store.ts # Channel state reducer
 │       ├── bootstrap-builder.ts           # Memory agent bootstrap
 │       └── profile-builder.ts             # Profile classification
-├── db/migrations/            # SQLite migrations (001-023)
-└── tests/                    # 16 test files, 59 tests
+│   ├── model-runs/           # Model run + tool trace lineage
+│   ├── connectors/           # Raw connector query/index helpers
+│   ├── edges/                # Twin edge ledger
+│   ├── agent-situation/      # Worker situation packets
+│   ├── agent-graph/          # Worker graph/entity helpers
+│   └── search/               # Search quality option normalization
+├── db/migrations/            # SQLite migrations (001-036)
+└── tests/                    # Unit and integration tests
 ```
 
 ## Migration Files
 
-Database migrations are included in `db/migrations/` (001-023):
+Database migrations are included in `db/migrations/` (001-036):
 
 - 001-013: Core schema (decisions, embeddings, graph edges)
 - 014: Add is_static column
@@ -204,6 +240,8 @@ Database migrations are included in `db/migrations/` (001-023):
 - 019-020: Memory events and audit findings
 - 021: Memory truth projection
 - 022-023: Channel summaries and state
+- 024-036: event dates, connector memory kinds, canonical entities, case-first memory, wiki/index
+  provenance, model/tool traces, twin edges, and agent situation packets
 
 ## License
 

package/db/migrations/032-add-memory-provenance-columns.sql

@@ -0,0 +1,21 @@
+ALTER TABLE decisions ADD COLUMN agent_id TEXT;
+ALTER TABLE decisions ADD COLUMN model_run_id TEXT;
+ALTER TABLE decisions ADD COLUMN envelope_hash TEXT;
+ALTER TABLE decisions ADD COLUMN gateway_call_id TEXT;
+ALTER TABLE decisions ADD COLUMN source_refs_json TEXT;
+ALTER TABLE decisions ADD COLUMN provenance_json TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_decisions_envelope_hash
+  ON decisions(envelope_hash);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_model_run_id
+  ON decisions(model_run_id);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_gateway_call_id
+  ON decisions(gateway_call_id);
+
+CREATE INDEX IF NOT EXISTS idx_memory_events_memory_created
+  ON memory_events(memory_id, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (32, 'Add nullable memory provenance columns');

package/db/migrations/033-create-model-runs-and-tool-traces.sql

@@ -0,0 +1,53 @@
+CREATE TABLE IF NOT EXISTS model_runs (
+  model_run_id TEXT PRIMARY KEY,
+  model_id TEXT,
+  model_provider TEXT,
+  prompt_version TEXT,
+  tool_manifest_version TEXT,
+  output_schema_version TEXT,
+  agent_id TEXT,
+  instance_id TEXT,
+  envelope_hash TEXT,
+  parent_model_run_id TEXT,
+  input_snapshot_ref TEXT,
+  input_refs_json TEXT,
+  completion_summary TEXT,
+  status TEXT NOT NULL CHECK (status IN ('running', 'committed', 'failed', 'legacy')),
+  error_summary TEXT,
+  token_count INTEGER DEFAULT 0,
+  cost_estimate REAL,
+  created_at INTEGER NOT NULL,
+  completed_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_envelope_hash
+  ON model_runs(envelope_hash);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_status_created
+  ON model_runs(status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_agent_created
+  ON model_runs(agent_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS tool_traces (
+  trace_id TEXT PRIMARY KEY,
+  model_run_id TEXT NOT NULL,
+  gateway_call_id TEXT,
+  tool_name TEXT NOT NULL,
+  input_summary TEXT,
+  output_summary TEXT,
+  execution_status TEXT,
+  duration_ms INTEGER DEFAULT 0,
+  envelope_hash TEXT,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (model_run_id) REFERENCES model_runs(model_run_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tool_traces_model_run_id
+  ON tool_traces(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_tool_traces_gateway_call_id
+  ON tool_traces(gateway_call_id);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (33, 'Create model runs and tool traces');

package/db/migrations/034-add-connector-event-scope-columns.sql

@@ -0,0 +1,14 @@
+ALTER TABLE connector_event_index ADD COLUMN source_cursor TEXT;
+ALTER TABLE connector_event_index ADD COLUMN tenant_id TEXT;
+ALTER TABLE connector_event_index ADD COLUMN project_id TEXT;
+ALTER TABLE connector_event_index ADD COLUMN memory_scope_kind TEXT;
+ALTER TABLE connector_event_index ADD COLUMN memory_scope_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_connector_event_scope
+  ON connector_event_index(tenant_id, project_id, memory_scope_kind, memory_scope_id);
+
+CREATE INDEX IF NOT EXISTS idx_connector_event_source_cursor
+  ON connector_event_index(source_connector, source_cursor);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (34, 'Add connector event scope columns');

package/db/migrations/035-create-twin-edges.sql

@@ -0,0 +1,63 @@
+CREATE TABLE IF NOT EXISTS twin_edges (
+  edge_id TEXT PRIMARY KEY,
+  edge_type TEXT NOT NULL CHECK (
+    edge_type IN (
+      'supersedes',
+      'builds_on',
+      'debates',
+      'synthesizes',
+      'mentions',
+      'derived_from',
+      'case_member',
+      'alias_of',
+      'next_action_for',
+      'blocks'
+    )
+  ),
+  subject_kind TEXT NOT NULL CHECK (
+    subject_kind IN ('memory', 'case', 'entity', 'report', 'edge')
+  ),
+  subject_id TEXT NOT NULL,
+  object_kind TEXT NOT NULL CHECK (
+    object_kind IN ('memory', 'case', 'entity', 'report', 'edge', 'raw')
+  ),
+  object_id TEXT NOT NULL,
+  relation_attrs_json TEXT,
+  confidence REAL NOT NULL DEFAULT 1.0 CHECK (confidence >= 0.0 AND confidence <= 1.0),
+  source TEXT NOT NULL CHECK (source IN ('agent', 'human', 'code')),
+  agent_id TEXT,
+  model_run_id TEXT,
+  envelope_hash TEXT,
+  human_actor_id TEXT,
+  human_actor_role TEXT,
+  authority_scope_json TEXT,
+  reason_classification TEXT,
+  reason_text TEXT,
+  evidence_refs_json TEXT,
+  request_idempotency_key TEXT,
+  edge_idempotency_key TEXT,
+  content_hash BLOB NOT NULL CHECK(length(content_hash)=32),
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_subject
+  ON twin_edges(subject_kind, subject_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_object
+  ON twin_edges(object_kind, object_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_model_run_id
+  ON twin_edges(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_request_idempotency
+  ON twin_edges(model_run_id, request_idempotency_key, created_at DESC)
+  WHERE model_run_id IS NOT NULL
+    AND request_idempotency_key IS NOT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_twin_edges_model_run_edge_idempotency
+  ON twin_edges(model_run_id, edge_idempotency_key)
+  WHERE model_run_id IS NOT NULL
+    AND edge_idempotency_key IS NOT NULL;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (35, 'Create first-class twin edge ledger');

package/db/migrations/036-create-agent-situation-packets.sql

@@ -0,0 +1,61 @@
+CREATE TABLE IF NOT EXISTS agent_situation_packets (
+  packet_id TEXT PRIMARY KEY,
+  cache_key TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  scope_hash TEXT NOT NULL,
+  range_start_ms INTEGER NOT NULL CHECK (range_start_ms >= 0),
+  range_end_ms INTEGER NOT NULL CHECK (range_end_ms >= range_start_ms),
+  focus_json TEXT NOT NULL,
+  envelope_hash TEXT NOT NULL,
+  envelope_effective_filters_json TEXT NOT NULL,
+  envelope_effective_filters_hash TEXT NOT NULL,
+  ranking_policy_version TEXT NOT NULL,
+  generated_at INTEGER NOT NULL CHECK (generated_at >= 0),
+  expires_at INTEGER NOT NULL CHECK (expires_at >= generated_at),
+  ttl_seconds INTEGER NOT NULL CHECK (ttl_seconds > 0),
+  freshness_json TEXT NOT NULL,
+  source_coverage_json TEXT NOT NULL,
+  briefing_json TEXT NOT NULL,
+  ranked_items_json TEXT NOT NULL,
+  top_memory_refs_json TEXT NOT NULL,
+  pending_human_questions_json TEXT NOT NULL,
+  entity_clusters_json TEXT NOT NULL,
+  recommended_next_tools_json TEXT NOT NULL,
+  generated_from_slice_ids_json TEXT NOT NULL DEFAULT '[]',
+  caveats_json TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  model_run_id TEXT NOT NULL,
+  input_snapshot_ref TEXT NOT NULL,
+  source_refs_json TEXT NOT NULL DEFAULT '[]',
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  project_id TEXT NOT NULL,
+  memory_scope_kind TEXT NOT NULL,
+  memory_scope_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_cache_fresh
+  ON agent_situation_packets(cache_key, ranking_policy_version, expires_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_envelope
+  ON agent_situation_packets(envelope_hash, generated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_model_run
+  ON agent_situation_packets(model_run_id, generated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_scope
+  ON agent_situation_packets(tenant_id, project_id, memory_scope_kind, memory_scope_id, generated_at DESC);
+
+CREATE TABLE IF NOT EXISTS agent_situation_refresh_leases (
+  cache_key TEXT PRIMARY KEY,
+  ranking_policy_version TEXT NOT NULL,
+  lease_owner TEXT NOT NULL,
+  lease_expires_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_leases_expiry
+  ON agent_situation_refresh_leases(lease_expires_at);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (36, 'Create agent situation packet cache');

package/db/migrations/037-create-context-packets.sql

@@ -0,0 +1,32 @@
+CREATE TABLE IF NOT EXISTS context_packets (
+  packet_id TEXT PRIMARY KEY,
+  task TEXT NOT NULL,
+  packet_json TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  scope_hash TEXT NOT NULL,
+  envelope_hash TEXT NOT NULL,
+  model_run_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  input_snapshot_ref TEXT NOT NULL,
+  source_refs_json TEXT NOT NULL DEFAULT '[]',
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  project_id TEXT NOT NULL,
+  memory_scope_kind TEXT NOT NULL CHECK (memory_scope_kind IN ('global', 'user', 'channel', 'project')),
+  memory_scope_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL CHECK (created_at >= 0)
+);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_model_run
+  ON context_packets(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_envelope
+  ON context_packets(envelope_hash, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_scope
+  ON context_packets(tenant_id, project_id, memory_scope_kind, memory_scope_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_scope_hash
+  ON context_packets(scope_hash, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (37, 'Create context packet append-only store');

package/dist/agent-graph/alias-write.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGraphAdapter, AttachEntityAliasWithEdgeInput, AttachEntityAliasWithEdgeResult } from './types.js';
+export declare function attachEntityAliasWithEdge(adapter: AgentGraphAdapter, input: AttachEntityAliasWithEdgeInput): AttachEntityAliasWithEdgeResult;
+//# sourceMappingURL=alias-write.d.ts.map

package/dist/agent-graph/alias-write.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachEntityAliasWithEdge = attachEntityAliasWithEdge;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_js_1 = require("../canonicalize.js");
+const ref_validation_js_1 = require("../edges/ref-validation.js");
+const store_js_1 = require("../edges/store.js");
+const types_js_1 = require("../edges/types.js");
+const normalization_js_1 = require("../entities/normalization.js");
+const store_js_2 = require("../entities/store.js");
+const errors_js_1 = require("./errors.js");
+const TWIN_REF_KIND_SET = new Set(types_js_1.TWIN_REF_KINDS);
+function stableAliasId(input, normalizedLabel) {
+    const replayKey = replayIdempotencyKey(input);
+    if (replayKey) {
+        const hash = (0, node_crypto_1.createHash)('sha256')
+            .update(`${input.entity_id}\0${normalizedLabel}\0${replayKey}`, 'utf8')
+            .digest('hex')
+            .slice(0, 32);
+        return `alias_${hash}`;
+    }
+    return `alias_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
+}
+function replayIdempotencyKey(input) {
+    return input.edge_idempotency_key ?? input.request_idempotency_key;
+}
+function loadAlias(adapter, aliasId) {
+    const row = adapter.prepare('SELECT * FROM entity_aliases WHERE id = ?').get(aliasId);
+    if (!row) {
+        throw new Error(`Entity alias was not written: ${aliasId}`);
+    }
+    return {
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        label: String(row.label),
+        normalized_label: String(row.normalized_label),
+        lang: typeof row.lang === 'string' ? row.lang : null,
+        script: typeof row.script === 'string' ? row.script : null,
+        label_type: row.label_type,
+        source_type: String(row.source_type),
+        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
+        confidence: typeof row.confidence === 'number' ? row.confidence : null,
+        status: row.status,
+        created_at: Number(row.created_at),
+    };
+}
+function normalizeConfidence(value) {
+    if (value === undefined || value === null) {
+        return 1;
+    }
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1) {
+        return value;
+    }
+    throw new errors_js_1.AgentGraphValidationError(`confidence must be between 0 and 1: ${String(value)}`);
+}
+function selectExistingAliasEdge(adapter, modelRunId, edgeIdempotencyKey) {
+    if (!edgeIdempotencyKey) {
+        return null;
+    }
+    const row = adapter
+        .prepare(`
+        SELECT *
+        FROM twin_edges
+        WHERE model_run_id = ?
+          AND edge_idempotency_key = ?
+        LIMIT 1
+      `)
+        .get(modelRunId, edgeIdempotencyKey);
+    return row ? (0, store_js_1.mapTwinEdgeRow)(row) : null;
+}
+function normalizeSourceRefs(sourceRefs) {
+    if (!sourceRefs || sourceRefs.length === 0) {
+        return [];
+    }
+    const refs = [];
+    const seen = new Set();
+    for (const ref of sourceRefs) {
+        if (!ref ||
+            typeof ref !== 'object' ||
+            typeof ref.kind !== 'string' ||
+            typeof ref.id !== 'string' ||
+            ref.id.trim().length === 0 ||
+            !TWIN_REF_KIND_SET.has(ref.kind)) {
+            throw new errors_js_1.AgentGraphValidationError('source_refs must be TwinRef objects with kind and id.');
+        }
+        const normalized = { kind: ref.kind, id: ref.id.trim() };
+        const key = `${normalized.kind}:${normalized.id}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            refs.push(normalized);
+        }
+    }
+    return refs.sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+}
+function expectedRelationAttrs(alias, sourceRefs) {
+    const attrs = {
+        alias_id: alias.id,
+        label: alias.label,
+        normalized_label: alias.normalized_label,
+        lang: alias.lang,
+        script: alias.script,
+        label_type: alias.label_type,
+    };
+    if (sourceRefs.length > 0) {
+        attrs.source_refs = sourceRefs.map((ref) => ({ kind: ref.kind, id: ref.id }));
+    }
+    return attrs;
+}
+function assertAliasReplayMatches(alias, input, normalized, confidence) {
+    const expectedScript = input.script ?? normalized.script;
+    const expectedLabelType = input.label_type ?? 'alt';
+    const expectedSourceRef = input.source_ref ?? null;
+    const matches = alias.entity_id === input.entity_id &&
+        alias.label === input.label &&
+        alias.normalized_label === normalized.normalized &&
+        alias.lang === (input.lang ?? null) &&
+        alias.script === expectedScript &&
+        alias.label_type === expectedLabelType &&
+        alias.source_type === input.source_type &&
+        alias.source_ref === expectedSourceRef &&
+        alias.confidence === confidence &&
+        alias.status === 'active';
+    if (!matches) {
+        throw new errors_js_1.AgentGraphValidationError(`Conflicting entity alias replay for request idempotency key: ${replayIdempotencyKey(input)}`);
+    }
+}
+function assertAliasEdgeReplayMatches(edge, input, alias, confidence, edgeIdempotencyKey, sourceRefs) {
+    const matches = edge.edge_type === 'alias_of' &&
+        edge.subject_ref.kind === 'entity' &&
+        edge.subject_ref.id === input.entity_id &&
+        edge.object_ref.kind === 'entity' &&
+        edge.object_ref.id === input.entity_id &&
+        edge.relation_attrs_json === (0, canonicalize_js_1.canonicalizeJSON)(expectedRelationAttrs(alias, sourceRefs)) &&
+        edge.confidence === confidence &&
+        edge.source === 'agent' &&
+        edge.agent_id === input.agent_id &&
+        edge.model_run_id === input.model_run_id &&
+        edge.envelope_hash === input.envelope_hash &&
+        edge.request_idempotency_key === (input.request_idempotency_key ?? null) &&
+        edge.edge_idempotency_key === (edgeIdempotencyKey ?? null);
+    if (!matches) {
+        throw new errors_js_1.AgentGraphValidationError(`Conflicting alias edge replay for request idempotency key: ${replayIdempotencyKey(input)}`);
+    }
+}
+function insertAliasEdge(adapter, input, alias, confidence, sourceRefs) {
+    const edgeIdempotencyKey = replayIdempotencyKey(input);
+    const existing = selectExistingAliasEdge(adapter, input.model_run_id, edgeIdempotencyKey);
+    const edgeId = `edge_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
+    const relationAttrs = expectedRelationAttrs(alias, sourceRefs);
+    const relationAttrsJson = (0, canonicalize_js_1.canonicalizeJSON)(relationAttrs);
+    if (existing) {
+        assertAliasEdgeReplayMatches(existing, input, alias, confidence, edgeIdempotencyKey, sourceRefs);
+        return existing;
+    }
+    const contentHash = (0, node_crypto_1.createHash)('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({
+        edge_type: 'alias_of',
+        subject_ref: { kind: 'entity', id: input.entity_id },
+        object_ref: { kind: 'entity', id: input.entity_id },
+        relation_attrs_json: relationAttrsJson,
+        confidence,
+        source: 'agent',
+        agent_id: input.agent_id,
+        model_run_id: input.model_run_id,
+        envelope_hash: input.envelope_hash,
+    }), 'utf8')
+        .digest();
+    adapter
+        .prepare(`
+        INSERT INTO twin_edges (
+          edge_id, edge_type, subject_kind, subject_id, object_kind, object_id,
+          relation_attrs_json, confidence, source, agent_id, model_run_id, envelope_hash,
+          request_idempotency_key, edge_idempotency_key, content_hash, created_at
+        )
+        VALUES (?, 'alias_of', 'entity', ?, 'entity', ?, ?, ?, 'agent', ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(edgeId, input.entity_id, input.entity_id, relationAttrsJson, confidence, input.agent_id, input.model_run_id, input.envelope_hash, input.request_idempotency_key ?? null, edgeIdempotencyKey ?? null, contentHash, Date.now());
+    const row = adapter.prepare('SELECT * FROM twin_edges WHERE edge_id = ?').get(edgeId);
+    if (!row) {
+        throw new Error(`Entity alias edge was not written: ${edgeId}`);
+    }
+    return (0, store_js_1.mapTwinEdgeRow)(row);
+}
+function attachEntityAliasWithEdge(adapter, input) {
+    const entity = (0, store_js_2.getEntityNode)(input.entity_id, adapter);
+    if (!entity || entity.status !== 'active') {
+        throw new errors_js_1.AgentGraphValidationError(`Active entity not found: ${input.entity_id}`);
+    }
+    const visibility = {
+        scopes: input.scopes,
+        connectors: input.connectors,
+        projectRefs: input.project_refs,
+        tenantId: input.tenant_id,
+    };
+    const sourceRefs = normalizeSourceRefs(input.source_refs);
+    if (sourceRefs.length === 0) {
+        throw new errors_js_1.AgentGraphValidationError('source_refs must include at least one visible source.');
+    }
+    try {
+        (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, [{ kind: 'entity', id: input.entity_id }, ...sourceRefs], visibility);
+    }
+    catch (error) {
+        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
+    }
+    let normalized;
+    try {
+        normalized = (0, normalization_js_1.normalizeEntityLabel)(input.label);
+    }
+    catch (error) {
+        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
+    }
+    const confidence = normalizeConfidence(input.confidence);
+    const aliasId = stableAliasId(input, normalized.normalized);
+    const createdAt = Date.now();
+    return adapter.transaction(() => {
+        adapter
+            .prepare(`
+          INSERT OR IGNORE INTO entity_aliases (
+            id, entity_id, label, normalized_label, lang, script, label_type,
+            source_type, source_ref, confidence, status, created_at
+          )
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)
+        `)
+            .run(aliasId, input.entity_id, input.label, normalized.normalized, input.lang ?? null, input.script ?? normalized.script, input.label_type ?? 'alt', input.source_type, input.source_ref ?? null, confidence, createdAt);
+        const alias = loadAlias(adapter, aliasId);
+        assertAliasReplayMatches(alias, input, normalized, confidence);
+        const edge = insertAliasEdge(adapter, input, alias, confidence, sourceRefs);
+        return { alias, edge };
+    });
+}
+//# sourceMappingURL=alias-write.js.map

package/dist/agent-graph/entity-resolve.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGraphAdapter, ResolveEntityInput, ResolveEntityResult } from './types.js';
+export declare function resolveEntity(adapter: AgentGraphAdapter, input: ResolveEntityInput): ResolveEntityResult;
+//# sourceMappingURL=entity-resolve.d.ts.map