neotoma 0.9.1 → 0.10.1

package/README.md

@@ -2,7 +2,7 @@
 
 Your agents forget. Neotoma makes them remember.
 
-Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
+Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
 
 **[neotoma.io](https://neotoma.io)** · **[Evaluate](https://neotoma.io/evaluate)** · **[Install](https://neotoma.io/install)** · **[Documentation](https://neotoma.io/docs)**
 
@@ -38,6 +38,7 @@ graph LR
   MCP --> ChatGPT
   MCP --> Cursor
   MCP --> OpenClaw
+  MCP --> IronClaw
 ```
 
 - **Deterministic.** Same observations always produce the same versioned entity snapshots. No ordering sensitivity.
@@ -51,7 +52,7 @@ graph LR
 | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
 | **Privacy-first**  | Your data stays local. Never used for training. User-controlled storage, optional encryption at rest. Full export and deletion control. |
 | **Deterministic**  | Same input always produces same output. Schema-first extraction, hash-based entity IDs, full provenance. No silent mutation.            |
-| **Cross-platform** | One memory graph across Claude, ChatGPT, Cursor, OpenClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
+| **Cross-platform** | One memory graph across Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
 
 ## State guarantees
 
@@ -100,6 +101,7 @@ The agent handles npm install, initialization, and MCP configuration. **Manual i
 npm install -g neotoma
 neotoma init
 neotoma mcp config
+neotoma mcp check --mcp-transport a
 ```
 
 More options: [Docker](docs/developer/docker.md) | [CLI reference](docs/developer/cli_reference.md) | [Getting started](docs/developer/getting_started.md)
@@ -121,14 +123,14 @@ Three interfaces. One state invariant. Every interface provides the same determi
 | Interface      | Description                                                                                                                    |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | **REST API**   | Full HTTP interface for application integration. Entities, relationships, observations, schema, timeline, and version history. |
-| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
+| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
 | **CLI**        | Command-line for scripting and direct access. Inspect entities, replay timelines, and manage state from the terminal.          |
 
 All three map to the same OpenAPI-backed operations. MCP tool calls log the equivalent CLI invocation.
 
 ## Who this is for
 
-People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
+People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
 
 | Mode | What you're doing | The tax you pay without Neotoma | What you get back |
 | ---- | ----------------- | ------------------------------- | ----------------- |
@@ -155,7 +157,7 @@ Schema is flexible — store any entity type with whatever fields the message im
 
 ## Current status
 
-**Version:** v0.4.2 · **Releases:** 13 · **License:** MIT
+**Version:** v0.9.1 · **Releases:** 26 · **License:** MIT
 
 ### What is guaranteed (even in preview)
 
@@ -217,9 +219,9 @@ npm test
 
 Neotoma exposes state via MCP. Local storage only in preview. Local built-in auth.
 
-**Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw)
+**Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenCode](docs/integrations/hooks/opencode.md) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw) · [IronClaw](https://neotoma.io/neotoma-with-ironclaw)
 
-For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh` or `npm run dev:mcp:dev-shim`) instead of pointing installed MCP clients at a `tsx watch` stdio process. The shim keeps the client-facing JSON-RPC stream stable and asks clients to refresh or reconnect when the tool interface changes.
+For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh`) or signed shim (`scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh`) instead of pointing installed MCP clients at a `tsx watch` stdio process. `neotoma mcp check` defaults to **`a`**: signed + AAuth with **neotoma-dev → dev** and **neotoma → prod** HTTP `/mcp` behind stdio; use `--mcp-transport c` for direct stdio, **`d`** if both MCP entries should target prod.
 
 **Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments, and attach bounded host context such as repository name/root scope when available. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
 

package/dist/actions.d.ts

@@ -1,4 +1,5 @@
 import express from "express";
+import { type StoreInterpretationInput } from "./shared/action_schemas.js";
 export declare const app: import("express-serve-static-core").Express;
 /**
  * True when the request arrived over a loopback socket.
@@ -38,6 +39,8 @@ export declare function storeStructuredForApi(params: {
     idempotencyKey: string;
     originalFilename?: string;
     relationships?: StoreRelationshipRef[];
+    interpretation?: StoreInterpretationInput;
+    interpretationSourceId?: string;
     commit?: boolean;
     strict?: boolean;
 }): Promise<{
@@ -61,10 +64,6 @@ export declare function storeStructuredForApi(params: {
         identity_basis: string;
         identity_rule: string;
     }[] | undefined;
-    success: boolean;
-    replayed: boolean;
-    commit: boolean;
-    source_id: string | null;
     entities_created: number;
     observations_created: number;
     entities: {
@@ -91,6 +90,12 @@ export declare function storeStructuredForApi(params: {
         source_entity_id: string;
         target_entity_id: string;
     }[];
+    interpretation_id?: string | undefined;
+    interpretation_source_id?: string | undefined;
+    success: boolean;
+    replayed: boolean;
+    commit: boolean;
+    source_id: string | null;
 }>;
 export declare function startHTTPServer(): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAmK9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAif7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAyrHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+fS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA2F3B;AAuhED,wBAAsB,eAAe;;;eA2FpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AA2G9B,OAAO,EAyBL,KAAK,wBAAwB,EAG9B,MAAM,4BAA4B,CAAC;AA+BpC,eAAO,MAAM,GAAG,6CAAY,CAAC;AAygB7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAiyHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAuDF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+gBS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;;;;;;;GAsG3B;AA+iED,wBAAsB,eAAe;;;eA2FpC"}

package/dist/actions.js

@@ -19,10 +19,10 @@ import { aauthVerify, getAAuthContextFromRequest, getAttributionDecisionFromRequ
 import { attributionContext } from "./middleware/attribution_context.js";
 import { aauthAdmission, getAAuthAdmissionFromRequest, } from "./middleware/aauth_admission.js";
 import { buildSessionInfo } from "./services/session_info.js";
-import { AttributionPolicyError } from "./services/attribution_policy.js";
+import { AttributionPolicyError, enforceAttributionPolicy } from "./services/attribution_policy.js";
 import { registerFeedbackAdminProxyRoutes } from "./services/feedback/admin_proxy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
-import { getCurrentAAuthAdmission, getCurrentAgentIdentity, runWithRequestContext, } from "./services/request_context.js";
+import { getCurrentAAuthAdmission, getCurrentAgentIdentity, getCurrentAttribution, runWithRequestContext, } from "./services/request_context.js";
 import { assertCanWriteProtectedBatch } from "./services/protected_entity_types.js";
 import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest, normaliseClientName, } from "./crypto/agent_identity.js";
 import { initServerKeys } from "./services/encryption_service.js";
@@ -43,7 +43,7 @@ import { resolveSandboxReportTransport } from "./services/sandbox/transport.js";
 import { getSqliteDb } from "./repositories/sqlite/sqlite_client.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.js";
 import { isOauthKeyCredentialValid, normalizeOauthNextPath, OAuthKeySessionStore, } from "./services/oauth_key_gate.js";
-import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
+import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
@@ -496,6 +496,24 @@ app.get("/server-info", (_req, res) => {
         neotoma_env: readNeotomaConfigEnvironment(),
     });
 });
+app.get("/mcp-interaction-instructions", (_req, res) => {
+    const instructionsPath = path.join(config.projectRoot, "docs", "developer", "mcp", "instructions.md");
+    try {
+        const raw = fs.readFileSync(instructionsPath, "utf-8");
+        const match = raw.match(/```\s*\n?([\s\S]*?)```/);
+        if (match && match[1]) {
+            const text = match[1].trim();
+            if (text) {
+                res.type("text/plain").send(text);
+                return;
+            }
+        }
+    }
+    catch {
+        // fall through to 404
+    }
+    res.status(404).json({ error: "instructions_not_found" });
+});
 // ============================================================================
 // MCP StreamableHTTP Endpoint (OAuth-enabled MCP transport)
 // ============================================================================
@@ -1689,20 +1707,37 @@ app.post("/mcp/oauth/token", oauthTokenLimit, express.urlencoded({ extended: tru
     try {
         const grant_type = req.body?.grant_type;
         const code = req.body?.code;
+        const refresh_token = req.body?.refresh_token;
         logger.info("[MCP OAuth] Token request received", {
             grant_type: grant_type ?? null,
             has_code: typeof code === "string" && code.length > 0,
             code_hint: typeof code === "string" ? code.slice(0, 8) : null,
+            has_refresh_token: typeof refresh_token === "string" && refresh_token.length > 0,
             host: req.header("host") ?? null,
         });
-        if (grant_type !== "authorization_code") {
+        if (grant_type !== "authorization_code" && grant_type !== "refresh_token") {
             logger.warn("[MCP OAuth] Token rejected: unsupported grant_type", {
                 grant_type: grant_type ?? null,
             });
             return res.status(400).json({
                 error: "unsupported_grant_type",
-                error_description: "Only authorization_code is supported",
+                error_description: "Only authorization_code and refresh_token are supported",
+            });
+        }
+        if (grant_type === "refresh_token") {
+            if (!refresh_token || typeof refresh_token !== "string") {
+                logger.warn("[MCP OAuth] Token refresh rejected: missing refresh_token");
+                return res
+                    .status(400)
+                    .json({ error: "invalid_request", error_description: "refresh_token is required" });
+            }
+            const { refreshAccessToken } = await import("./services/mcp_oauth.js");
+            const token = await refreshAccessToken(refresh_token);
+            logger.info("[MCP OAuth] Token refreshed", {
+                has_refresh_token: Boolean(token.refresh_token),
             });
+            res.setHeader("Content-Type", "application/json");
+            return res.json(token);
         }
         if (!code || typeof code !== "string") {
             logger.warn("[MCP OAuth] Token rejected: missing code");
@@ -3774,6 +3809,83 @@ app.get("/interpretations", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", message);
     }
 });
+app.post("/interpretations/create", async (req, res) => {
+    const parsed = CreateInterpretationRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+        logWarn("ValidationError:interpretations_create", req, { issues: parsed.error.issues });
+        return sendValidationError(res, parsed.error.issues);
+    }
+    try {
+        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        const { data: source, error: sourceError } = await db
+            .from("sources")
+            .select("id")
+            .eq("id", parsed.data.source_id)
+            .eq("user_id", userId)
+            .maybeSingle();
+        if (sourceError)
+            throw sourceError;
+        if (!source) {
+            return sendError(res, 404, "SOURCE_NOT_FOUND", "Source not found for authenticated user");
+        }
+        const { runInterpretation } = await import("./services/interpretation.js");
+        const interpretationResult = await runInterpretation({
+            userId,
+            sourceId: parsed.data.source_id,
+            extractedData: parsed.data.entities,
+            config: normalizeInterpretationConfig(parsed.data.interpretation_config),
+        });
+        const relationshipsCreated = [];
+        if (parsed.data.relationships?.length) {
+            const { relationshipsService } = await import("./services/relationships.js");
+            for (const rel of parsed.data.relationships) {
+                const sourceEntityId = typeof rel.source_entity_id === "string"
+                    ? rel.source_entity_id
+                    : typeof rel.source_index === "number"
+                        ? interpretationResult.entities[rel.source_index]?.entityId
+                        : undefined;
+                const targetEntityId = typeof rel.target_entity_id === "string"
+                    ? rel.target_entity_id
+                    : typeof rel.target_index === "number"
+                        ? interpretationResult.entities[rel.target_index]?.entityId
+                        : undefined;
+                if (!sourceEntityId || !targetEntityId)
+                    continue;
+                await relationshipsService.createRelationship({
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
+                    relationship_type: rel.relationship_type,
+                    source_id: parsed.data.source_id,
+                    metadata: rel.metadata ?? {},
+                    user_id: userId,
+                });
+                relationshipsCreated.push({
+                    relationship_type: rel.relationship_type,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
+                });
+            }
+        }
+        return res.json({
+            success: true,
+            interpretation_id: interpretationResult.interpretationId,
+            source_id: parsed.data.source_id,
+            entities: interpretationResult.entities.map((entity) => ({
+                entity_id: entity.entityId,
+                entity_type: entity.entityType,
+                observation_id: entity.observationId,
+            })),
+            observations_created: interpretationResult.observationsCreated,
+            unknown_fields_count: interpretationResult.unknownFieldsCount,
+            relationships_created: relationshipsCreated,
+        });
+    }
+    catch (error) {
+        logError("APIError:interpretations_create", req, error);
+        const message = error instanceof Error ? error.message : "Failed to create interpretation";
+        return sendError(res, 500, "INTERPRETATION_CREATE_FAILED", message);
+    }
+});
 // GET /api/observations - Get observations with filters (FU-302, FU-601)
 // REQUIRES AUTHENTICATION - all queries filtered by authenticated user_id
 app.get("/observations", async (req, res) => {
@@ -3889,8 +4001,47 @@ app.post("/observations/create", async (req, res) => {
         return res.status(500).json(buildErrorEnvelope("DB_QUERY_FAILED", message));
     }
 });
+function normalizeInterpretationConfig(configInput) {
+    return {
+        extractor_type: "agent",
+        extractor_version: "unknown",
+        schema_version: "1.0",
+        ...configInput,
+    };
+}
+async function createInterpretationRunForSource(params) {
+    enforceAttributionPolicy("interpretations", getCurrentAgentIdentity());
+    const attribution = getCurrentAttribution();
+    const { data, error } = await db
+        .from("interpretations")
+        .insert({
+        user_id: params.userId,
+        source_id: params.sourceId,
+        interpretation_config: normalizeInterpretationConfig(params.interpretationConfig),
+        status: "running",
+        started_at: new Date().toISOString(),
+        ...(Object.keys(attribution).length > 0 ? { provenance: attribution } : {}),
+    })
+        .select("id")
+        .single();
+    if (error) {
+        throw new Error(`Failed to create interpretation run: ${error.message}`);
+    }
+    return data.id;
+}
+async function completeInterpretationRun(params) {
+    await db
+        .from("interpretations")
+        .update({
+        status: "completed",
+        completed_at: new Date().toISOString(),
+        observations_created: params.observationsCreated,
+        unknown_fields_count: params.unknownFieldsCount ?? 0,
+    })
+        .eq("id", params.interpretationId);
+}
 export async function storeStructuredForApi(params) {
-    const { userId, entities, sourcePriority, observationSource, idempotencyKey, originalFilename, relationships, commit: commitInput, strict: strictInput, } = params;
+    const { userId, entities, sourcePriority, observationSource, idempotencyKey, originalFilename, relationships, interpretation, interpretationSourceId, commit: commitInput, strict: strictInput, } = params;
     const commit = commitInput !== false;
     const strict = strictInput === true;
     // Capability scoping: when the caller is an AAuth-verified agent covered
@@ -3989,6 +4140,17 @@ export async function storeStructuredForApi(params) {
             source_priority: sourcePriority,
         },
     });
+    const resolvedInterpretationSourceId = interpretation?.source_id ??
+        interpretationSourceId ??
+        (interpretation?.source_ref === "structured" ? storageResult.sourceId : undefined);
+    const interpretationId = commit && interpretation && resolvedInterpretationSourceId
+        ? await createInterpretationRunForSource({
+            userId,
+            sourceId: resolvedInterpretationSourceId,
+            interpretationConfig: interpretation.interpretation_config,
+        })
+        : null;
+    const observationSourceId = resolvedInterpretationSourceId ?? storageResult.sourceId;
     // v0.5.1: structured guidance for the v0.5.0 breaking change where callers
     // nested fields under `attributes`. If resolution failed and the only
     // observed top-level keys are `attributes` (plus optionally `entity_type`),
@@ -4163,8 +4325,8 @@ export async function storeStructuredForApi(params) {
                 entity_id: r.entity_id,
                 entity_type: r.entity_type,
                 schema_version: "1.0",
-                source_id: storageResult.sourceId,
-                interpretation_id: null,
+                source_id: observationSourceId,
+                interpretation_id: interpretationId,
                 observed_at: new Date().toISOString(),
                 specificity_score: 1.0,
                 source_priority: sourcePriority,
@@ -4199,7 +4361,7 @@ export async function storeStructuredForApi(params) {
                         fields: r.fields,
                         schema: schemaEntry.schema_definition,
                         userId,
-                        sourceId: storageResult.sourceId,
+                        sourceId: observationSourceId,
                     });
                 }
             }
@@ -4251,7 +4413,7 @@ export async function storeStructuredForApi(params) {
                     source_entity_id: sourceEntityId,
                     target_entity_id: targetEntityId,
                     relationship_type: rel.relationship_type,
-                    source_id: storageResult.sourceId,
+                    source_id: observationSourceId,
                     metadata: rel.metadata ?? {},
                     user_id: userId,
                 });
@@ -4286,11 +4448,21 @@ export async function storeStructuredForApi(params) {
             });
         }
     }
+    if (commit && interpretationId) {
+        await completeInterpretationRun({
+            interpretationId,
+            observationsCreated: createdEntities.filter((e) => e.observation_id).length,
+            unknownFieldsCount: 0,
+        });
+    }
     return {
         success: true,
         replayed: false,
         commit,
         source_id: commit ? storageResult.sourceId : null,
+        ...(interpretationId
+            ? { interpretation_id: interpretationId, interpretation_source_id: observationSourceId }
+            : {}),
         entities_created: commit
             ? createdEntities.filter((e) => e.action === "created" || e.action === "extended").length
             : 0,
@@ -4347,23 +4519,7 @@ async function handleStorePost(req, res) {
         const hasUnstructured = hasFileContent || hasFilePath;
         let structuredResult;
         let unstructuredResult;
-        if (hasEntities) {
-            if (!parsed.data.idempotency_key) {
-                return sendError(res, 400, "VALIDATION_ERROR", "idempotency_key is required when entities are provided");
-            }
-            structuredResult = await storeStructuredForApi({
-                userId,
-                entities: parsed.data.entities,
-                sourcePriority: parsed.data.source_priority ?? 100,
-                observationSource: parsed.data.observation_source,
-                idempotencyKey: parsed.data.idempotency_key,
-                originalFilename: parsed.data.original_filename,
-                relationships: parsed.data.relationships,
-                commit: parsed.data.commit,
-                strict: parsed.data.strict,
-            });
-        }
-        if (hasUnstructured) {
+        const storeUnstructuredFromRequest = async () => {
             const fileContent = parsed.data.file_content;
             let mimeType = parsed.data.mime_type;
             let originalFilename = parsed.data.original_filename;
@@ -4380,9 +4536,10 @@ async function handleStorePost(req, res) {
                 originalFilename = originalFilename || path.basename(resolvedPath);
             }
             if ((!fileContent && !resolvedFileBuffer) || !mimeType) {
-                return sendError(res, 400, "VALIDATION_ERROR", "Unstructured store requires file_content+mime_type or file_path");
+                sendError(res, 400, "VALIDATION_ERROR", "Unstructured store requires file_content+mime_type or file_path");
+                return null;
             }
-            unstructuredResult = await storeUnstructuredForApi({
+            return await storeUnstructuredForApi({
                 userId,
                 fileContent,
                 fileBuffer: resolvedFileBuffer,
@@ -4391,6 +4548,42 @@ async function handleStorePost(req, res) {
                     (!hasEntities ? parsed.data.idempotency_key : undefined),
                 originalFilename,
             });
+        };
+        if (hasUnstructured && parsed.data.interpretation?.source_ref === "unstructured") {
+            const result = await storeUnstructuredFromRequest();
+            if (!result) {
+                return;
+            }
+            unstructuredResult = result;
+        }
+        if (hasEntities) {
+            if (!parsed.data.idempotency_key) {
+                return sendError(res, 400, "VALIDATION_ERROR", "idempotency_key is required when entities are provided");
+            }
+            structuredResult = await storeStructuredForApi({
+                userId,
+                entities: parsed.data.entities,
+                sourcePriority: parsed.data.source_priority ?? 100,
+                observationSource: parsed.data.observation_source,
+                idempotencyKey: parsed.data.idempotency_key,
+                originalFilename: parsed.data.original_filename,
+                relationships: parsed.data.relationships,
+                interpretation: parsed.data.interpretation,
+                interpretationSourceId: parsed.data.interpretation?.source_ref === "unstructured" &&
+                    unstructuredResult &&
+                    typeof unstructuredResult.source_id === "string"
+                    ? unstructuredResult.source_id
+                    : undefined,
+                commit: parsed.data.commit,
+                strict: parsed.data.strict,
+            });
+        }
+        if (hasUnstructured && !unstructuredResult) {
+            const result = await storeUnstructuredFromRequest();
+            if (!result) {
+                return;
+            }
+            unstructuredResult = result;
         }
         if (structuredResult && unstructuredResult) {
             return res.json({