neotoma 0.4.5 → 0.5.0

package/README.md

@@ -79,7 +79,7 @@ Most AI memory systems optimize storage or retrieval. Neotoma enforces state int
 Ask your AI agent whether Neotoma fits your workflow. Paste this into Claude, Cursor, ChatGPT, or any MCP-capable tool:
 
 ```
-Read https://neotoma.io/evaluate. Before you answer, inspect any broader tool, workspace, and configuration context you can access so you assess my real workflow rather than just this chat. Then tell me whether Neotoma is a real fit for my workflow, what data would be highest value to persist first, and what I should do next.
+Read https://neotoma.io/evaluate. Use any tool, workspace, and chat context already available in this session to assess my real workflow. Avoid ad-hoc shell introspection just to profile me; if Neotoma is already installed, use `neotoma doctor --json` for status instead. Then tell me whether Neotoma is a real fit for my workflow, what data would be highest value to persist first, and what I should do next.
 ```
 
 The agent reads the evaluation page, checks your context, and gives you an honest assessment. If it's a fit, the agent carries you through install and activation.
@@ -89,7 +89,7 @@ The agent reads the evaluation page, checks your context, and gives you an hones
 Agents install Neotoma themselves. Paste this prompt into Claude, Cursor, ChatGPT, or Codex:
 
 ```
-Read https://neotoma.io/install and carry me through the install-first Neotoma flow. Install, activate it with my data, and configure my current tool for robust ongoing use.
+Read https://neotoma.io/install and carry me through the install-first Neotoma flow. Use `neotoma` commands for status and setup. If Neotoma is already installed, start with `neotoma doctor --json`; otherwise install it and run `neotoma setup --tool <my_tool> --yes`. Avoid ad-hoc shell introspection or arbitrary repo scripts. Then activate Neotoma with my data and configure my current tool for robust ongoing use.
 ```
 
 The agent handles npm install, initialization, and MCP configuration. **Manual install:**

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;AAoF9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAwL7B,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAK5D;AA2pJD,wBAAsB,eAAe;;;eAgCpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAsF9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AA2M7B,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAK5D;AA2gKD,wBAAsB,eAAe;;;eAgCpC"}

package/dist/actions.js

@@ -31,6 +31,8 @@ import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
 import { prepareEntitySnapshotWithEmbedding, upsertEntitySnapshotWithEmbedding, } from "./services/entity_snapshot_embedding.js";
 import { readOpenApiActionsFile, readOpenApiFile } from "./shared/openapi_file.js";
+import { buildSmitheryServerCard } from "./mcp_server_card.js";
+import { listRecentRecordActivity } from "./services/recent_record_activity.js";
 export const app = express();
 // Trust proxy headers (required for express-rate-limit when X-Forwarded-For is present)
 app.set("trust proxy", true);
@@ -100,6 +102,25 @@ const oauthRegisterLimit = rateLimit({
 });
 // Favicon (no-auth) to avoid 401 noise when not present on disk
 app.get("/favicon.ico", (_req, res) => res.status(204).end());
+// Smithery / MCP registry static metadata when automatic scan cannot finish (same host as /mcp)
+app.get("/.well-known/mcp/server-card.json", (_req, res) => {
+    const override = process.env.NEOTOMA_MCP_SERVER_CARD_JSON?.trim();
+    if (override) {
+        try {
+            const parsed = JSON.parse(override);
+            res.type("application/json");
+            return res.json(parsed);
+        }
+        catch {
+            return res.status(500).type("application/json").json({
+                error: "invalid_server_card_json",
+                error_description: "NEOTOMA_MCP_SERVER_CARD_JSON is not valid JSON",
+            });
+        }
+    }
+    res.type("application/json");
+    res.json(buildSmitheryServerCard());
+});
 // ============================================================================
 // OAuth discovery (RFC 8414 / MCP Authorization) for Cursor and other clients
 // ============================================================================
@@ -1552,7 +1573,7 @@ app.post("/entities/query", async (req, res) => {
     try {
         // Get authenticated user_id (REQUIRED)
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { entity_type, search, limit, offset, sort_by, sort_order, published, published_after, published_before, include_snapshots, include_merged, } = parsed.data;
+        const { entity_type, search, limit, offset, sort_by, sort_order, published, published_after, published_before, include_snapshots, include_merged, updated_since, created_since, } = parsed.data;
         const { entities, total } = await queryEntitiesWithCount({
             userId,
             entityType: entity_type,
@@ -1566,6 +1587,8 @@ app.post("/entities/query", async (req, res) => {
             search,
             limit,
             offset,
+            updatedSince: updated_since,
+            createdSince: created_since,
         });
         return res.json({
             entities,
@@ -2304,6 +2327,20 @@ app.get("/timeline/:id", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", message, errorDetails);
     }
 });
+// GET /api/record_activity - Cross-table recent rows for inspector (ordered by latest timestamps)
+// REQUIRES AUTHENTICATION
+app.get("/record_activity", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const limit = parseInt(String(req.query.limit ?? "50"), 10) || 50;
+        const offset = parseInt(String(req.query.offset ?? "0"), 10) || 0;
+        const result = listRecentRecordActivity(userId, limit, offset);
+        return res.json(result);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to list recent record activity", "DB_QUERY_FAILED", "APIError:record_activity");
+    }
+});
 // GET /api/sources - Get source list (FU-301)
 app.get("/sources", async (req, res) => {
     try {
@@ -2620,8 +2657,10 @@ app.post("/observations/create", async (req, res) => {
     }
 });
 async function storeStructuredForApi(params) {
-    const { userId, entities, sourcePriority, idempotencyKey, originalFilename } = params;
-    const { resolveEntity } = await import("./services/entity_resolution.js");
+    const { userId, entities, sourcePriority, idempotencyKey, originalFilename, relationships, commit: commitInput, strict: strictInput, } = params;
+    const commit = commitInput !== false;
+    const strict = strictInput === true;
+    const { resolveEntityWithTrace, CanonicalNameUnresolvedError, MergeRefusedError, } = await import("./services/entity_resolution.js");
     const { detectFlatPackedRows, FlatPackedRowsError } = await import("./services/flat_packed_detection.js");
     // Reject flat-packed rows (whole tables smuggled into a single entity as
     // `<prefix>_<index>_<suffix>` keys). These cannot produce per-row snapshots
@@ -2678,12 +2717,23 @@ async function storeStructuredForApi(params) {
             source_priority: sourcePriority,
         },
     });
-    const createdEntities = [];
-    for (const entityData of entities) {
+    const resolved = [];
+    const issues = [];
+    for (let observation_index = 0; observation_index < entities.length; observation_index++) {
+        const entityData = entities[observation_index];
         let entity_type = entityData.entity_type;
         if (!entity_type) {
             throw new Error("entity_type is required for each entity");
         }
+        // Per-entity overrides: `intent: "create_new"` is shorthand for strict on
+        // this record; `target_id` forces extend mode (bypass derivation).
+        const intent = typeof entityData.intent === "string"
+            ? entityData.intent
+            : undefined;
+        const targetId = typeof entityData.target_id === "string"
+            ? entityData.target_id
+            : undefined;
+        const effectiveStrict = strict || intent === "create_new";
         // Schema-agnostic duplicate-type collapse (e.g. `places` -> `place`,
         // aliased-type -> canonical). Applied before storing so the resolved
         // entity_id hashes into the canonical type rather than a near-duplicate.
@@ -2703,66 +2753,182 @@ async function storeStructuredForApi(params) {
         catch (equivErr) {
             logger.warn(`Equivalence check failed for ${entity_type}: ${equivErr instanceof Error ? equivErr.message : String(equivErr)}`);
         }
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars -- intentional omit
-        const { entity_type: _removed, ...fields } = entityData;
-        const entity_id = await resolveEntity({
-            entityType: entity_type,
-            fields,
-            userId,
-        });
-        const obsData = await createObservation({
-            entity_id,
-            entity_type,
-            schema_version: "1.0",
-            source_id: storageResult.sourceId,
-            interpretation_id: null,
-            observed_at: new Date().toISOString(),
-            specificity_score: 1.0,
-            source_priority: sourcePriority,
-            fields,
-            user_id: userId,
-        });
+        const { entity_type: _removedType, intent: _removedIntent, target_id: _removedTargetId, ...fields } = entityData;
+        void _removedType;
+        void _removedIntent;
+        void _removedTargetId;
         try {
-            const { recomputeSnapshot } = await import("./services/snapshot_computation.js");
-            await recomputeSnapshot(entity_id, userId);
-        }
-        catch (snapshotErr) {
-            logger.warn(`Snapshot recompute failed for ${entity_id}: ${snapshotErr}`);
+            const result = await resolveEntityWithTrace({
+                entityType: entity_type,
+                fields,
+                userId,
+                commit,
+                strict: effectiveStrict,
+                targetId,
+            });
+            resolved.push({
+                observation_index,
+                entity_type,
+                entity_id: result.entityId,
+                fields,
+                trace: {
+                    canonical_name: result.trace.canonicalName,
+                    resolver_path: result.trace.path,
+                    identity_basis: result.trace.identityBasis,
+                    identity_rule: result.trace.identityRule,
+                    action: result.trace.action,
+                },
+                intent,
+                targetId,
+            });
         }
-        // Schema-driven auto-linking: if the entity's active schema declares
-        // reference_fields, create typed relationships to the referenced
-        // entities (REFERS_TO by default). Silent fallback when no schema or no
-        // match exists — never invent targets.
-        try {
-            const { schemaRegistry } = await import("./services/schema_registry.js");
-            const schemaEntry = await schemaRegistry.loadActiveSchema(entity_type, userId);
-            if (schemaEntry?.schema_definition?.reference_fields?.length) {
-                const { autoLinkReferenceFields } = await import("./services/schema_reference_linking.js");
-                await autoLinkReferenceFields({
-                    entityId: entity_id,
-                    entityType: entity_type,
-                    fields,
-                    schema: schemaEntry.schema_definition,
-                    userId,
-                    sourceId: storageResult.sourceId,
+        catch (err) {
+            if (err instanceof CanonicalNameUnresolvedError) {
+                issues.push({
+                    observation_index,
+                    entity_type,
+                    code: "ERR_CANONICAL_NAME_UNRESOLVED",
+                    message: err.message,
+                    details: {
+                        seen_fields: err.seenFields,
+                        attempted_value: err.attemptedValue,
+                    },
+                });
+            }
+            else if (err instanceof MergeRefusedError) {
+                issues.push({
+                    observation_index,
+                    entity_type,
+                    code: "ERR_MERGE_REFUSED",
+                    message: err.message,
+                    details: {
+                        entity_id: err.entityId,
+                        canonical_name: err.canonicalName,
+                        resolver_path: err.resolverPath,
+                    },
                 });
             }
+            else {
+                throw err;
+            }
         }
-        catch (linkErr) {
-            logger.warn(`Auto-link reference fields failed for ${entity_type}/${entity_id}: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`);
+    }
+    if (issues.length > 0) {
+        const aggregate = new Error(`Structured store refused: ${issues.length} observation(s) failed resolution.`);
+        aggregate.code = "ERR_STORE_RESOLUTION_FAILED";
+        aggregate.issues = issues;
+        throw aggregate;
+    }
+    const createdEntities = [];
+    for (const r of resolved) {
+        let observation_id = null;
+        let snapshotAfter = null;
+        if (commit) {
+            const obsData = await createObservation({
+                entity_id: r.entity_id,
+                entity_type: r.entity_type,
+                schema_version: "1.0",
+                source_id: storageResult.sourceId,
+                interpretation_id: null,
+                observed_at: new Date().toISOString(),
+                specificity_score: 1.0,
+                source_priority: sourcePriority,
+                fields: r.fields,
+                user_id: userId,
+                identity_basis: r.trace.identity_basis,
+                identity_rule: r.trace.identity_rule,
+            });
+            observation_id = obsData.id;
+            try {
+                const { recomputeSnapshot } = await import("./services/snapshot_computation.js");
+                const snap = await recomputeSnapshot(r.entity_id, userId);
+                snapshotAfter =
+                    snap
+                        ?.snapshot ?? null;
+            }
+            catch (snapshotErr) {
+                logger.warn(`Snapshot recompute failed for ${r.entity_id}: ${snapshotErr}`);
+            }
+            // Schema-driven auto-linking: if the entity's active schema declares
+            // reference_fields, create typed relationships to the referenced
+            // entities (REFERS_TO by default). Silent fallback when no schema or no
+            // match exists — never invent targets.
+            try {
+                const { schemaRegistry } = await import("./services/schema_registry.js");
+                const schemaEntry = await schemaRegistry.loadActiveSchema(r.entity_type, userId);
+                if (schemaEntry?.schema_definition?.reference_fields?.length) {
+                    const { autoLinkReferenceFields } = await import("./services/schema_reference_linking.js");
+                    await autoLinkReferenceFields({
+                        entityId: r.entity_id,
+                        entityType: r.entity_type,
+                        fields: r.fields,
+                        schema: schemaEntry.schema_definition,
+                        userId,
+                        sourceId: storageResult.sourceId,
+                    });
+                }
+            }
+            catch (linkErr) {
+                logger.warn(`Auto-link reference fields failed for ${r.entity_type}/${r.entity_id}: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`);
+            }
         }
         createdEntities.push({
-            entity_id,
-            entity_type,
-            observation_id: obsData.id,
+            entity_id: r.entity_id,
+            entity_type: r.entity_type,
+            observation_id,
+            observation_index: r.observation_index,
+            action: r.trace.action,
+            canonical_name: r.trace.canonical_name,
+            resolver_path: r.trace.resolver_path,
+            identity_basis: r.trace.identity_basis,
+            identity_rule: r.trace.identity_rule,
+            entity_snapshot_after: snapshotAfter,
         });
     }
+    // Relationships (parity with MCP store_structured). Indices are resolved
+    // against the observation order; commit=false skips creation.
+    const relationshipsCreated = [];
+    if (commit && relationships && relationships.length > 0) {
+        const { relationshipsService } = await import("./services/relationships.js");
+        for (const rel of relationships) {
+            const source = resolved[rel.source_index];
+            const target = resolved[rel.target_index];
+            if (!source || !target) {
+                logger.warn(`[STORE] Skipping relationship: invalid source_index=${rel.source_index} ` +
+                    `or target_index=${rel.target_index} (have ${resolved.length} entities).`);
+                continue;
+            }
+            try {
+                await relationshipsService.createRelationship({
+                    source_entity_id: source.entity_id,
+                    target_entity_id: target.entity_id,
+                    relationship_type: rel.relationship_type,
+                    source_id: storageResult.sourceId,
+                    user_id: userId,
+                });
+                relationshipsCreated.push({
+                    relationship_type: rel.relationship_type,
+                    source_entity_id: source.entity_id,
+                    target_entity_id: target.entity_id,
+                });
+            }
+            catch (relErr) {
+                logger.warn(`Failed to create relationship ${rel.relationship_type} ` +
+                    `${source.entity_id} -> ${target.entity_id}: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
+            }
+        }
+    }
     return {
         success: true,
-        source_id: storageResult.sourceId,
-        entities_created: createdEntities.length,
-        observations_created: createdEntities.length,
+        commit,
+        source_id: commit ? storageResult.sourceId : null,
+        entities_created: commit
+            ? createdEntities.filter((e) => e.action === "created" || e.action === "extended")
+                .length
+            : 0,
+        observations_created: commit ? createdEntities.length : 0,
         entities: createdEntities,
+        relationships_created: relationshipsCreated,
     };
 }
 async function storeUnstructuredForApi(params) {
@@ -2817,6 +2983,9 @@ app.post("/store", async (req, res) => {
                 sourcePriority: parsed.data.source_priority ?? 100,
                 idempotencyKey: parsed.data.idempotency_key,
                 originalFilename: parsed.data.original_filename,
+                relationships: parsed.data.relationships,
+                commit: parsed.data.commit,
+                strict: parsed.data.strict,
             });
         }
         if (hasUnstructured) {
@@ -2871,6 +3040,21 @@ app.post("/store", async (req, res) => {
             logWarn("EntityTypeGuardError:store", req, { code: errCode, message });
             return sendError(res, 400, errCode, message);
         }
+        if (error &&
+            typeof error === "object" &&
+            errCode === "ERR_STORE_RESOLUTION_FAILED") {
+            const err = error;
+            logWarn("StoreResolutionError:store", req, {
+                issue_count: err.issues?.length ?? 0,
+            });
+            return res.status(400).json({
+                error: {
+                    code: "ERR_STORE_RESOLUTION_FAILED",
+                    message: err.message,
+                    issues: err.issues ?? [],
+                },
+            });
+        }
         if (error &&
             typeof error === "object" &&
             errCode === "ERR_FLAT_PACKED_ROWS") {
@@ -2934,7 +3118,7 @@ app.post("/observations/query", async (req, res) => {
     try {
         // Get authenticated user_id (REQUIRED)
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { observation_id, entity_id, entity_type, source_id, limit, offset } = parsed.data;
+        const { observation_id, entity_id, entity_type, source_id, limit, offset, updated_since, created_since, } = parsed.data;
         // Build query - ALWAYS filter by authenticated user_id
         let query = db.from("observations").select("*", { count: "exact" }).eq("user_id", userId); // SECURITY: Always filter by authenticated user
         if (observation_id) {
@@ -2949,6 +3133,14 @@ app.post("/observations/query", async (req, res) => {
         if (source_id) {
             query = query.eq("source_id", source_id);
         }
+        if (updated_since) {
+            // Observations are immutable; treat updated_since as a synonym for
+            // observed_at >= updated_since so clients have a single "since" knob.
+            query = query.gte("observed_at", updated_since);
+        }
+        if (created_since) {
+            query = query.gte("observed_at", created_since);
+        }
         query = query.order("observed_at", { ascending: false }).range(offset, offset + limit - 1);
         const { data, error, count } = await query;
         if (error)
@@ -2969,6 +3161,49 @@ app.post("/observations/query", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", message);
     }
 });
+// GET /entities/duplicates - List candidate duplicate entity pairs (R5).
+// Read-only fuzzy post-hoc detector. Never auto-merges. Hands off to
+// /entities/merge once an operator or agent confirms a pair.
+app.get("/entities/duplicates", async (req, res) => {
+    try {
+        const entityType = typeof req.query.entity_type === "string" ? req.query.entity_type : undefined;
+        if (!entityType) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "entity_type query parameter is required");
+        }
+        const providedUserId = typeof req.query.user_id === "string" ? req.query.user_id : undefined;
+        const authenticatedUserId = await getAuthenticatedUserId(req, providedUserId);
+        if (providedUserId && providedUserId !== authenticatedUserId) {
+            return sendError(res, 403, "FORBIDDEN", "user_id does not match authenticated user.");
+        }
+        const thresholdRaw = typeof req.query.threshold === "string" ? req.query.threshold : undefined;
+        const limitRaw = typeof req.query.limit === "string" ? req.query.limit : undefined;
+        const threshold = thresholdRaw ? Number(thresholdRaw) : undefined;
+        if (threshold !== undefined && (Number.isNaN(threshold) || threshold <= 0 || threshold > 1)) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "threshold must be a number in (0, 1]");
+        }
+        const limit = limitRaw ? Number(limitRaw) : undefined;
+        if (limit !== undefined && (!Number.isFinite(limit) || limit < 1 || limit > 200)) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "limit must be an integer in [1, 200]");
+        }
+        const { findDuplicateCandidates } = await import("./services/duplicate_detection.js");
+        const candidates = await findDuplicateCandidates({
+            entityType,
+            userId: authenticatedUserId,
+            threshold,
+            limit,
+        });
+        return res.json({
+            candidates,
+            entity_type: entityType,
+            threshold: threshold ?? null,
+        });
+    }
+    catch (error) {
+        logError("APIError:entities_duplicates", req, error);
+        const message = error instanceof Error ? error.message : "Failed to list potential duplicates";
+        return sendError(res, 500, "DB_QUERY_FAILED", message);
+    }
+});
 // POST /api/entities/merge - Merge duplicate entities
 // REQUIRES AUTHENTICATION - validates user_id matches authenticated user and entities belong to user
 app.post("/entities/merge", async (req, res) => {
@@ -3044,14 +3279,20 @@ app.post("/list_observations", async (req, res) => {
         });
         return sendValidationError(res, parsed.error.issues);
     }
-    const { entity_id, limit = 100, offset = 0 } = parsed.data;
-    const query = db
+    const { entity_id, limit = 100, offset = 0, updated_since, created_since } = parsed.data;
+    let query = db
         .from("observations")
         .select("*")
-        .eq("entity_id", entity_id)
+        .eq("entity_id", entity_id);
+    if (updated_since) {
+        query = query.gte("observed_at", updated_since);
+    }
+    if (created_since) {
+        query = query.gte("observed_at", created_since);
+    }
+    const { data, error } = await query
         .order("observed_at", { ascending: false })
         .range(offset, offset + limit - 1);
-    const { data, error } = await query;
     if (error) {
         logError("DbError:list_observations", req, error);
         return sendError(res, 500, "DB_QUERY_FAILED", error.message);
@@ -3219,13 +3460,16 @@ app.post("/retrieve_entity_by_identifier", async (req, res) => {
         return sendValidationError(res, parsed.error.issues);
     }
     try {
-        const { identifier, entity_type } = parsed.data;
-        const userId = await getAuthenticatedUserId(req, undefined);
+        const { identifier, entity_type, by, limit, include_observations, observations_limit } = parsed.data;
+        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const result = await retrieveEntityByIdentifierWithFallback({
             identifier,
             entityType: entity_type,
             userId,
-            limit: 100,
+            limit: limit ?? 100,
+            by,
+            includeObservations: include_observations,
+            observationsLimit: observations_limit,
         });
         logDebug("Success:retrieve_entity_by_identifier", req, {
             identifier,
@@ -3686,12 +3930,28 @@ app.post("/register_schema", async (req, res) => {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const { entity_type, schema_definition, reducer_config, schema_version = "1.0", user_specific = false, activate = false, force = false, } = parsed.data;
         const { schemaRegistry } = await import("./services/schema_registry.js");
+        // R2 back-compat: existing HTTP/CLI callers may register schemas
+        // without declaring canonical_name_fields or identity_opt_out (e.g. the
+        // bootstrap path from `neotoma schemas register`). Default to an
+        // explicit identity_opt_out so registration still succeeds while
+        // surfacing the gap loudly via startup logs and stats. Clients that
+        // want strong identity should set `canonical_name_fields` on the
+        // request payload.
+        const definitionWithIdentity = (() => {
+            const def = schema_definition;
+            if (!def || typeof def !== "object")
+                return schema_definition;
+            if (def.canonical_name_fields || def.identity_opt_out)
+                return schema_definition;
+            logWarn("DefaultIdentityOptOut:register_schema", req, { entity_type });
+            return { ...def, identity_opt_out: "heuristic_canonical_name" };
+        })();
         let newSchema;
         try {
             newSchema = await schemaRegistry.register({
                 entity_type,
                 schema_version,
-                schema_definition: schema_definition,
+                schema_definition: definitionWithIdentity,
                 reducer_config: (reducer_config || { merge_policies: {} }),
                 user_id: userId,
                 user_specific,