neotoma 0.21.5 → 0.22.0

package/README.md

@@ -1,11 +1,29 @@
 # Neotoma
 
-Neotoma is a deterministic, versioned state layer for AI agents. It ingests sources into immutable observations and computes reproducible entity snapshots with full provenance, exposed over an MCP server, a REST API, a CLI, and a bundled web Inspector.
+**Agents cannot own work they cannot verify.**
+
+You cannot delegate real work to agents you cannot hold to account. Accountability has two halves: what was true, and who was authorized. **Neotoma is the system of record for AI agents** — it answers what was true. Your agents can produce a value; they cannot tell you its version, its source, or whether it is still current. Neotoma versions every fact, attributes it to a source, and replays it.
+
+What ships today is the foundation: a deterministic, versioned state layer that ingests sources into immutable observations and computes reproducible entity snapshots with full provenance, exposed over an MCP server, a REST API, a CLI, and a bundled web Inspector. See [Vision and execution status](#vision-and-execution-status) for exactly where the implementation stands against the vision.
 
 It is built for developers building and operating AI agents who need a persistent, deterministic, auditable memory layer shared across tools. The same engine serves two further groups: individuals running a personal cross-assistant memory on a single-user install, and operators running a shared, multi-user instance with agent access control. Agents store structured records (contacts, tasks, transactions, decisions, events, and any other type) once and read them back across every tool and session, and the same observations always reduce to the same state.
 
 **[neotoma.io](https://neotoma.io)** · **[Install](https://neotoma.io/install)** · **[Documentation](https://neotoma.io/docs)** (also served in-app at `/docs`)
 
+## Vision and execution status
+
+As agent use expands, reality fragments across chat histories, agent memories, files, databases, tickets, and application state. The failure is not retrieval — it is that humans and agents can no longer answer: *which assertion is current? which source introduced it? was it observed, inferred, or decided? who had authority to correct it? which agents relied on the previous version? is there legitimate disagreement?* Neotoma's long-term role is **collective epistemic coherence**: not "better semantic memory," but deterministic, governed, multi-party state that humans and agents maintain together — attributed, correctable, disagreement-aware, portable, and independent of any one model or application.
+
+| Vision phase | What it means | Status |
+| --- | --- | --- |
+| **P0 — Deterministic single-writer state** | Append-only observations, hash-derived IDs, deterministic reduction, field-level provenance, corrections-win, replayable history | ✅ **Shipped and stable** — the core guarantee, in daily use |
+| **P1 — Multi-user state foundations** | Human and agent identities, attributed writes, tenant isolation, access controls, shared instances | 🟡 **Partially shipped**: hosted multi-user mode with `user_id` tenancy, per-agent identity (AAuth, optional hardware attestation), capability grants, guest tokens, peer federation. Not yet: organizations/workspaces, membership lifecycle, invitations, offboarding |
+| **P2 — Authority over state** | Domain ownership, correction rights, supersession, policy ownership, temporary grants, disclosure logs | 🟡 **Mechanisms exist** (corrections always win, `SUPERSEDES` relationships, per-operation access controls); authority *semantics* — who may correct what, scoped by domain — are future work |
+| **P3 — Multi-principal semantics** | Competing interpretations, disputed claims, official positions, consensus vs unresolved disagreement, field-level policies, historical validity | 🔜 Planned — interpretations are first-class today; dispute/official-position semantics are not |
+| **P4 — Organizational intelligence substrate** | Non-developer governance UI, "why does the system believe this?" explanations, impact analysis, authority-graph views, enterprise administration | 🔭 Vision — the Inspector's provenance and audit views are the seed |
+
+[Ateles](https://github.com/markmhendrickson/ateles) is the other half. Accountability has two halves: **Neotoma answers what was true** (truth, memory, provenance); **Ateles answers who was authorized** (initiative, delegation, approval) — against Neotoma state. Neither is sufficient alone. Memory without authority tells you what happened but not whether it was permitted; authority without memory tells you who may act but not against what state.
+
 ## What Neotoma is
 
 Neotoma is a state layer, not a chat memory or a vector cache. It records immutable observations from your sources, resolves them into entities, and computes a current snapshot for each entity by reducing its observations in a deterministic order. Nothing is overwritten. Corrections and reinterpretations add new observations; the prior history stays intact and replayable.
@@ -187,7 +205,7 @@ Full profile: [ICP from functionality](docs/icp/icp_from_functionality.md).
 
 **Version:** v0.17.0 · **License:** MIT · **Storage:** local-only (SQLite + local files).
 
-Neotoma is in developer preview and used daily in real agent workflows. The core guarantees (deterministic state, versioned history, append-only log, full provenance, same contract across CLI and MCP) are stable. Schemas, extraction across versions, long-term replay compatibility, and backward compatibility are not yet guaranteed. Expect breaking changes.
+Neotoma is in developer preview and used daily in real agent workflows. The core guarantees (deterministic state, versioned history, append-only log, full provenance, same contract across CLI and MCP) are stable — phase P0 of the [vision roadmap](#vision-and-execution-status), with P1 partially shipped in hosted mode. Schemas, extraction across versions, long-term replay compatibility, and backward compatibility are not yet guaranteed. Expect breaking changes.
 
 ## Development
 

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.js

@@ -23,6 +23,7 @@ import { buildSessionInfo, normalizeSessionOrigin } from "./services/session_inf
 import { AttributionPolicyError, enforceAttributionPolicy } from "./services/attribution_policy.js";
 import { OverridePolicyViolationError } from "./services/override_validation.js";
 import { CursorError } from "./services/entity_cursor.js";
+import { StorePolicyUnavailableError } from "./services/instance_policy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
 import { assertGuestWriteAllowed, AccessPolicyError, } from "./services/access_policy.js";
 import { hashGuestAccessToken } from "./services/guest_access_token.js";
@@ -748,23 +749,34 @@ app.get("/server-info", (req, res) => {
         endpoints: buildEndpointsMap(mode),
     });
 });
-app.get("/mcp-interaction-instructions", (_req, res) => {
-    const instructionsPath = path.join(config.projectRoot, "docs", "developer", "mcp", "instructions.md");
+app.get("/mcp-interaction-instructions", async (_req, res) => {
+    // Uses the shared extractor rather than an inlined fence regex, and appends
+    // the instance policy through the shared composer (#1974), so this surface
+    // cannot drift from the MCP handshake and the CLI.
+    const { readMcpInstructionsMarkdown, extractFirstFencedCodeBlock, resolveNeotomaPackageRoot, composeClientInstructions, } = await import("./mcp_instruction_doc.js");
+    let text = null;
+    for (const root of [config.projectRoot, resolveNeotomaPackageRoot()]) {
+        const raw = readMcpInstructionsMarkdown(root);
+        if (!raw)
+            continue;
+        text = extractFirstFencedCodeBlock(raw);
+        if (text)
+            break;
+    }
+    if (!text) {
+        res.status(404).json({ error: "instructions_not_found" });
+        return;
+    }
+    let policySection = "";
     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;
-            }
-        }
+        const { getInstancePolicy, renderInstancePolicyInstructions } = await import("./services/instance_policy.js");
+        policySection = renderInstancePolicyInstructions(await getInstancePolicy());
     }
     catch {
-        // fall through to 404
+        // An unreadable policy degrades to the global instructions rather than
+        // failing the request.
     }
-    res.status(404).json({ error: "instructions_not_found" });
+    res.type("text/plain").send(composeClientInstructions(text, policySection));
 });
 // ============================================================================
 // MCP StreamableHTTP Endpoint (OAuth-enabled MCP transport)
@@ -2419,7 +2431,17 @@ app.get("/mcp/oauth/google/callback", async (req, res) => {
         // their isolated per-email one — so the whole allowlisted team, plus the
         // bearer/MCP identity that owns the data, share one populated graph. Unset
         // → isolated per-email behavior (unchanged). See getSharedGraphUserId.
-        const resolvedUserId = getSharedGraphUserId() ?? perEmailUser.id;
+        const sharedGraphUserId = getSharedGraphUserId();
+        // A configured-but-rejected value means NEOTOMA_SHARED_GRAPH_USER_ID is set
+        // to something unusable (malformed, or the nil UUID). The signer silently
+        // falls back to their isolated per-email graph, which looks like an empty
+        // team graph rather than an error — so say so once per sign-in.
+        if (!sharedGraphUserId && (process.env.NEOTOMA_SHARED_GRAPH_USER_ID || "").trim()) {
+            logWarn("SharedGraphUserIdRejected", req, {
+                reason: "not a usable UUID (malformed or nil); falling back to isolated per-email graph",
+            });
+        }
+        const resolvedUserId = sharedGraphUserId ?? perEmailUser.id;
         // Mark this browser session as Google-verified and bound to the resolved
         // user_id, exactly the same OAuth key-session cookie the private-key/
         // mnemonic/bearer path sets. `/mcp/oauth/authorize` -> `/mcp/oauth/
@@ -3618,6 +3640,21 @@ function handleApiError(req, res, error, defaultMessage, errorCode = "DB_QUERY_F
             .status(error.statusCode)
             .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
     }
+    if (error instanceof StorePolicyUnavailableError) {
+        // 503, not 400: the write was refused because the instance could not read
+        // its own policy, which is a service-side fault the caller can retry — not
+        // a statement about the payload. A 400 here would tell an agent its data
+        // was wrong and invite it to narrow what it stores in response to an
+        // outage. Logged at error level because an enforcing instance that cannot
+        // read its policy is refusing every write.
+        logError(logContext || "StorePolicyUnavailable", req, error, {
+            code: error.code,
+            cause: error.cause_message,
+        });
+        return res
+            .status(503)
+            .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+    }
     if (error instanceof IssueValidationError) {
         logWarn(logContext || "IssueValidationError", req, {
             code: error.code,
@@ -4298,6 +4335,28 @@ app.get("/schemas", async (req, res) => {
     }
 });
 // GET /api/schemas/:entity_type - Get specific schema (FU-XXX)
+// GET /instance-policy — describe this instance's data policy (#1974/#1975).
+//
+// Deliberately takes no user_id or instance identifier: the policy is
+// instance-wide, so every authenticated caller sees the same record and there
+// is no parameter through which one caller could address another scope. Auth is
+// still required — the policy shape reveals what kind of data the instance
+// handles.
+app.get("/instance-policy", async (req, res) => {
+    try {
+        await getAuthenticatedUserId(req, undefined);
+        const { getInstancePolicyResult } = await import("./services/instance_policy.js");
+        const result = await getInstancePolicyResult();
+        // Explicit null, never 404 and never {} — "no policy configured" must not
+        // be mistakable for "denies everything". entity_id rides alongside so a
+        // remote client (CLI `instance-policy set`) can resolve the id needed to
+        // `correct` an existing policy without a local database connection.
+        return res.json({ policy: result.policy ?? null, entity_id: result.entity_id ?? null });
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to read instance policy", "DB_QUERY_FAILED", "APIError:instance-policy");
+    }
+});
 app.get("/schemas/:entity_type", async (req, res) => {
     try {
         const entityType = decodeURIComponent(req.params.entity_type);
@@ -5854,6 +5913,37 @@ export async function storeStructuredForApi(params) {
             entities: existingEntities,
         };
     }
+    // Instance store-policy enforcement (#1975).
+    //
+    // Placed before `storeRawContent` — not merely before the observation writes
+    // — because that call persists the `sources` row. A store call is not wrapped
+    // in a transaction, so a denial raised after it would leave an orphaned
+    // source row behind for a request that returned "rejected, 0 persisted".
+    // For a data-protection control, an error that says rejected while data sits
+    // in the database is the worst possible failure mode.
+    //
+    // Evaluates the raw request entities rather than the post-resolution
+    // `resolved` array (computed further down): the policy predicates read
+    // `entity_type` and field presence, both available here, and resolution runs
+    // after the source write.
+    {
+        const { assertStorePolicyAllows } = await import("./services/instance_policy.js");
+        const { schemaRegistry: policySchemaRegistry } = await import("./services/schema_registry.js");
+        const policyCandidates = entities.map((entityData) => {
+            const raw = (entityData ?? {});
+            const candidateFields = { ...raw };
+            delete candidateFields.entity_type;
+            delete candidateFields.type;
+            return {
+                entity_type: raw.entity_type || raw.type || "generic",
+                fields: candidateFields,
+            };
+        });
+        await assertStorePolicyAllows(policyCandidates, async (entityType) => {
+            const entry = await policySchemaRegistry.loadActiveSchema(entityType, userId);
+            return entry?.schema_definition ?? null;
+        });
+    }
     const { createObservation } = await import("./services/observation_storage.js");
     const jsonContent = incomingJsonContent;
     const filenameForStorage = originalFilename?.trim() || undefined;
@@ -6761,6 +6851,15 @@ export async function storeStructuredForApi(params) {
             : {}),
     };
 }
+// KNOWN SCOPE BOUNDARY (release-preparation finding, v0.22.0): this raw-file
+// path does NOT call assertStorePolicyAllows / the instance-policy gate.
+// Unlike storeStructuredForApi/storeStructuredInternal/createCorrection (see
+// tests/unit/instance_policy_write_path_coverage.test.ts), raw file uploads
+// never construct a typed entity with an entity_type, so the policy's
+// out_of_scope_entity_types / max_sensitivity_class gates have no evaluable
+// target here today. An instance with enforcement: "enforced" still accepts
+// arbitrary raw file content through this path. See the "Known scope
+// boundary" section in src/services/instance_policy.ts's docblock.
 async function storeUnstructuredForApi(params) {
     const { fileContent, fileBuffer, filePath, mimeType, idempotencyKey, originalFilename, sourceType, userId, storageMode = "inline", } = params;
     const resolvedFileBuffer = fileBuffer ?? (fileContent !== undefined ? Buffer.from(fileContent, "base64") : undefined);
@@ -6962,6 +7061,45 @@ async function handleStorePost(req, res) {
             logWarn("IdempotencyCollision:store", req, { message });
             return sendError(res, 409, "ERR_IDEMPOTENCY_COLLISION", message);
         }
+        if (error && typeof error === "object" && errCode === "ERR_STORE_POLICY_DENIED") {
+            const err = error;
+            // Log counts and reason codes only. The denied entities' field values are
+            // exactly the data the policy refused to hold, so they must not reach the
+            // log either (guardrails MUST NOT 11).
+            logWarn("StorePolicyDenied:store", req, {
+                denied_count: err.denied?.length ?? 0,
+                reason_codes: [...new Set((err.denied ?? []).map((d) => d.reason_code))].sort(),
+            });
+            return res.status(400).json({
+                error: {
+                    code: "ERR_STORE_POLICY_DENIED",
+                    message: err.message,
+                    denied: err.denied ?? [],
+                },
+            });
+        }
+        if (error instanceof StorePolicyUnavailableError) {
+            // MUST sit beside its DENIED sibling, not fall through to the generic
+            // 500 below. `/correct` gets 503 from the shared `handleApiError`, but
+            // this handler catches first and never reaches it — so without this
+            // branch REST `/store` answered 500 DB_QUERY_FAILED while MCP, /correct,
+            // the docs, and the declared envelope all promised 503 retryable:true.
+            //
+            // The status is the entire contract here. 500 reads as "this request
+            // broke the server" and a well-behaved agent responds by changing the
+            // payload; 503 + retryable:true reads as "ask again unchanged". Getting
+            // it wrong makes an agent narrow what it stores because the instance
+            // could not read its own policy — the failure this split exists to
+            // prevent, arriving through the surface it was built for.
+            logError("StorePolicyUnavailable:store", req, error, {
+                code: error.code,
+                cause: error.cause_message,
+            });
+            // Nested under `error` to match the DENIED sibling directly above, so a
+            // client reading `error.code` finds both policy outcomes in one place.
+            // `toErrorEnvelope()` already carries code + message + retryable + hint.
+            return res.status(503).json({ error: error.toErrorEnvelope() });
+        }
         if (error && typeof error === "object" && errCode === "ERR_STORE_RESOLUTION_FAILED") {
             const err = error;
             logWarn("StoreResolutionError:store", req, {
@@ -8873,6 +9011,16 @@ app.post("/correct", async (req, res) => {
                 .status(400)
                 .json(buildErrorEnvelope(error.code, error.message, { entity_type: error.entityType }));
         }
+        // Instance store-policy denial (#1975) — same envelope as /store, so a
+        // caller handling one handles both.
+        const { StorePolicyDeniedError } = await import("./services/instance_policy.js");
+        if (error instanceof StorePolicyDeniedError) {
+            logWarn("StorePolicyDenied:correct", req, {
+                denied_count: error.denied.length,
+                reason_codes: [...new Set(error.denied.map((d) => d.reason_code))].sort(),
+            });
+            return res.status(400).json({ error: error.toErrorEnvelope() });
+        }
         return handleApiError(req, res, error, "Failed to create correction", "DB_QUERY_FAILED", "APIError:correct");
     }
 });