@x12i/memorix-service 3.12.3 → 3.13.0

package/dist/routes/data.js

@@ -2,13 +2,31 @@ import { parseLiveDeclaration } from "@x12i/memorix-data";
 import { resolveScope } from "../request-scope.js";
 import { ServiceError } from "../errors.js";
 import { requireCallbackAccess, requireDeploymentAccess } from "../access-gate.js";
-import { normalizeWritePrecondition } from "../write-precondition.js";
-import { assertAddressMatchesEnvelope, resolveRecordIdAlias, } from "../identity-alias.js";
+import { runContentBatch, runContentWrite } from "../writes/content-write.js";
+import { commitWriteEffects } from "../writes/effects.js";
+import { patchGuardCheck } from "../patches/service.js";
+import { resolveRecordIdAlias } from "../identity-alias.js";
 import { maybeEnqueueNexumAnalysis } from "../nexum-analysis/enqueue.js";
+import { listKnowledgeGraphsForSource } from "../nexum-analysis/knowledge-read.js";
 import { memorixActivityRing, recordLooksLikeKnowledgeGraph, } from "../activity-ring.js";
 import { getRequestCaller, requireCaller } from "../caller-identity.js";
-import { runHookTrigger } from "../hooks/request-trigger.js";
 import { parseSafeFilters, parseSafeFiltersValue, parseSafeSort, parseSafeSortValue } from "../safe-query.js";
+import { declaredDiscriminatorValues } from "../catalog-bridge.js";
+import { singleReadDiscriminatorValue, withDiscriminatorHelp } from "../single-read-discriminator.js";
+function parseIncludeObject(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ServiceError("VALIDATION", "include must be an object", 400);
+    }
+    const markdown = raw.markdown;
+    if (markdown === undefined)
+        return {};
+    if (typeof markdown !== "boolean") {
+        throw new ServiceError("VALIDATION", "include.markdown must be a boolean", 400);
+    }
+    return { markdown };
+}
 function parseContentInclude(raw) {
     if (raw === undefined || raw === "")
         return undefined;
@@ -19,24 +37,39 @@ function parseContentInclude(raw) {
     catch {
         throw new ServiceError("VALIDATION", "include must be JSON", 400);
     }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new ServiceError("VALIDATION", "include must be an object", 400);
-    }
-    const markdown = parsed.markdown;
-    if (markdown === undefined)
-        return {};
-    if (typeof markdown !== "boolean") {
-        throw new ServiceError("VALIDATION", "include.markdown must be a boolean", 400);
-    }
-    return { markdown };
+    return parseIncludeObject(parsed);
 }
-function readSuppressHooks(value) {
-    if (value === undefined)
-        return false;
-    if (typeof value !== "boolean") {
-        throw new ServiceError("VALIDATION", "suppressHooks must be a boolean", 400);
+/** Wildcard path so record ids that contain `/` stay intact. */
+function subjectRecordIdFromRequest(req) {
+    const params = (req.params ?? {});
+    const raw = params["*"] ?? params.path ?? "";
+    const recordId = raw.trim();
+    if (!recordId) {
+        throw new ServiceError("VALIDATION", "recordId required", 400);
     }
-    return value;
+    return recordId;
+}
+function publicWriteReceipt(row) {
+    return {
+        receiptId: row.receiptId,
+        status: row.status,
+        ...(row.writeId ? { writeId: row.writeId } : {}),
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        ...(row.receipt ? { receipt: row.receipt } : {}),
+        ...(row.error
+            ? {
+                error: {
+                    code: row.error.code,
+                    field: row.error.field,
+                    message: row.error.message,
+                    retryable: row.error.retryable,
+                    ...(row.error.retryAfterMs !== undefined ? { retryAfterMs: row.error.retryAfterMs } : {}),
+                },
+            }
+            : {}),
+        ...(row.status === "pending" ? { retryAfterMs: row.error?.retryAfterMs ?? 1_000 } : {}),
+    };
 }
 function contentDatasource(req, body) {
     const service = requireCaller(req);
@@ -60,7 +93,79 @@ function draftForDatasourceStamp(record) {
         ...(record.insights ? { insights: record.insights } : {}),
     };
 }
+/** One content instance by recordId; `filter` may only select the discriminator. */
+async function getSingleContent(platform, scope, q, recordId, include) {
+    const ports = platform.portsFor(scope);
+    const discriminatorPath = ports.catalog.getContentProfile?.(q.contentType)?.discriminator?.path;
+    const discriminatorValue = singleReadDiscriminatorValue({
+        discriminatorValue: q.discriminatorValue ?? q.discriminator,
+        filters: parseSafeFilters(q.filter),
+        discriminatorPath,
+    });
+    try {
+        const record = (await ports.reader.getContent(scope, {
+            objectType: q.objectType,
+            contentType: q.contentType,
+            recordId,
+            ...(discriminatorValue ? { discriminatorValue } : {}),
+        }, include ? { include } : undefined));
+        return { record, ...(discriminatorValue ? { discriminatorValue } : {}) };
+    }
+    catch (err) {
+        throw withDiscriminatorHelp(err, () => discriminatorPath
+            ? declaredDiscriminatorValues(platform.metadata, scope.agentIds, q.objectType, q.contentType, discriminatorPath)
+            : undefined);
+    }
+}
 export async function registerDataRoutes(app, platform) {
+    app.get("/api/data/knowledge-graphs", async (req) => {
+        requireCallbackAccess(req, "explore");
+        const scope = resolveScope(req);
+        const q = req.query;
+        const sourceRecordId = q.sourceRecordId?.trim() ?? "";
+        if (!sourceRecordId) {
+            throw new ServiceError("VALIDATION", "sourceRecordId required", 400);
+        }
+        const caller = getRequestCaller(req);
+        const ports = platform.portsFor(scope);
+        const listed = await listKnowledgeGraphsForSource({
+            reader: ports.reader,
+            scope,
+            sourceRecordId,
+            limit: Number(q.limit ?? 50) || 50,
+            cursor: q.cursor,
+        });
+        memorixActivityRing.recordFetch({
+            orgId: scope.orgId,
+            caller,
+            mode: "list",
+            objectType: listed.addressing.objectType,
+            contentType: listed.addressing.contentType,
+            recordId: sourceRecordId,
+            hit: listed.records.length > 0,
+            count: listed.records.length,
+            knowledgeGraph: listed.records.length > 0,
+        });
+        return { scope, ...listed };
+    });
+    app.get("/api/data/content/context", async (req) => {
+        requireCallbackAccess(req, "explore");
+        const scope = resolveScope(req);
+        const q = req.query;
+        if (!q.objectType || !q.contentType) {
+            throw new ServiceError("VALIDATION", "objectType and contentType required", 400);
+        }
+        const recordId = resolveRecordIdAlias(q.id, q.recordId);
+        if (!recordId) {
+            throw new ServiceError("VALIDATION", "recordId required", 400);
+        }
+        const { record } = await getSingleContent(platform, scope, { ...q, objectType: q.objectType, contentType: q.contentType }, recordId);
+        const context = record.context;
+        if (!context || typeof context !== "object" || Array.isArray(context) || Object.keys(context).length === 0) {
+            throw new ServiceError("NOT_FOUND", "context is not stored on this record", 404);
+        }
+        return context;
+    });
     app.get("/api/data/content", async (req) => {
         requireCallbackAccess(req, "explore");
         const scope = resolveScope(req);
@@ -75,12 +180,9 @@ export async function registerDataRoutes(app, platform) {
         const recordId = resolveRecordIdAlias(q.id, q.recordId);
         if (recordId) {
             let record;
+            let discriminatorValue;
             try {
-                record = (await ports.reader.getContent(scope, {
-                    objectType: q.objectType,
-                    contentType: q.contentType,
-                    recordId,
-                }, { include }));
+                ({ record, discriminatorValue } = await getSingleContent(platform, scope, { ...q, objectType: q.objectType, contentType: q.contentType }, recordId, include));
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -126,6 +228,7 @@ export async function registerDataRoutes(app, platform) {
                     contentType: q.contentType,
                     id: recordId,
                     recordId,
+                    ...(discriminatorValue ? { discriminatorValue } : {}),
                 },
                 record,
                 currentRevision: record.revision,
@@ -135,25 +238,32 @@ export async function registerDataRoutes(app, platform) {
         const limit = Math.min(Math.max(Number(q.limit ?? 50) || 50, 1), 200);
         const filters = parseSafeFilters(q.filter);
         const sort = parseSafeSort(q.sort);
-        if (q.count === "true" && platform.analytics) {
-            const count = await platform.analytics.countIndexed(scope, {
-                objectType: q.objectType,
-                contentType: q.contentType,
-                filters,
-            });
-            if (count !== null) {
-                return {
-                    scope,
-                    count,
-                    addressing: {
-                        orgId: scope.orgId,
-                        objectType: q.objectType,
-                        contentType: q.contentType,
-                        id: null,
-                        recordId: null,
-                    },
-                };
-            }
+        if (q.count === "true") {
+            const indexed = platform.analytics
+                ? await platform.analytics.countIndexed(scope, {
+                    objectType: q.objectType,
+                    contentType: q.contentType,
+                    filters,
+                })
+                : null;
+            const count = indexed !== null
+                ? indexed
+                : await ports.reader.countContent(scope, {
+                    objectType: q.objectType,
+                    contentType: q.contentType,
+                    filters,
+                });
+            return {
+                scope,
+                count,
+                addressing: {
+                    orgId: scope.orgId,
+                    objectType: q.objectType,
+                    contentType: q.contentType,
+                    id: null,
+                    recordId: null,
+                },
+            };
         }
         const listed = await ports.reader.listContent(scope, {
             objectType: q.objectType,
@@ -222,174 +332,71 @@ export async function registerDataRoutes(app, platform) {
             pageInfo: { nextCursor: listed.nextCursor ?? null, limit },
         };
     });
-    app.post("/api/data/content", async (req) => {
+    app.post("/api/data/content/batch", async (req) => {
         requireDeploymentAccess(req, "write");
         const scope = resolveScope(req);
-        const body = req.body;
-        if (!body.objectType || !body.contentType) {
-            throw new ServiceError("VALIDATION", "objectType, contentType required", 400);
-        }
         await platform.analytics?.prepare(scope.orgId);
-        assertAddressMatchesEnvelope({
-            objectType: body.objectType,
-            contentType: body.contentType,
-            record: body.record,
+        const caller = requireCaller(req);
+        return runContentBatch({
+            scope,
+            caller,
+            datasource: contentDatasource(req, {}),
+            ports: platform.portsFor(scope),
+            receipts: platform.writeReceiptsFor(scope.orgId),
+            onCommitted: (event) => commitWriteEffects({ platform, scope, caller, event }),
+            checkWrite: patchGuardCheck(platform, scope),
+        }, req.body, (item) => contentDatasource(req, item));
+    });
+    app.get("/api/data/receipts", async (req) => {
+        requireCallbackAccess(req, "explore");
+        const scope = resolveScope(req);
+        const caller = requireCaller(req);
+        const q = req.query;
+        const status = q.status === "pending" || q.status === "stored" || q.status === "rejected" || q.status === "all"
+            ? q.status
+            : "rejected";
+        const limit = Math.min(Math.max(Number(q.limit ?? 50) || 50, 1), 200);
+        const rows = await platform.writeReceiptsFor(scope.orgId).list({
+            orgId: scope.orgId,
+            caller,
+            ...(status === "all" ? {} : { status }),
+            limit,
         });
-        const precondition = normalizeWritePrecondition(body.precondition, body.expectedRevision);
-        const datasource = contentDatasource(req, body);
-        const suppressHooks = readSuppressHooks(body.suppressHooks);
-        const ports = platform.portsFor(scope);
-        const op = body.op ?? (precondition.form === "absent" ? "add" : "upsert");
-        const expectedRevision = precondition.form === "exact-revision" ? precondition.expectedRevision : undefined;
-        try {
-            if (op === "remove") {
-                if (!body.record?.recordId || expectedRevision === undefined) {
-                    throw new ServiceError("VALIDATION", "record.recordId and expectedRevision required for remove", 400);
-                }
-                const pinned = await ports.publications.list();
-                const blocking = pinned.filter((p) => (p.status === "committed" || p.status === "draft") &&
-                    p.members.some((m) => m.recordId === body.record.recordId &&
-                        m.objectType === body.objectType &&
-                        m.contentType === body.contentType));
-                if (blocking.length) {
-                    throw new ServiceError("PUBLICATION_PINNED", "cannot remove a content instance referenced by a draft or committed publication", 409, { publicationIds: blocking.map((p) => p.publicationId) });
-                }
-                const objectType = body.objectType;
-                const contentType = body.contentType;
-                const recordId = body.record.recordId;
-                const noted = await runHookTrigger(() => ports.writer.remove({
-                    scope,
-                    objectType,
-                    contentType,
-                    recordId,
-                    precondition: { kind: "revision", revision: expectedRevision },
-                    datasource,
-                    suppressHooks,
-                }));
-                const result = noted.value;
-                memorixActivityRing.recordLand({
-                    orgId: scope.orgId,
-                    caller: getRequestCaller(req),
-                    objectType: body.objectType,
-                    contentType: body.contentType,
-                    recordId: result.recordId,
-                    revision: result.previousRevision,
-                    outcome: "removed",
-                    hooks: noted.hooks,
-                });
-                return { scope, written: true, outcome: "updated", result, precondition: body.precondition };
-            }
-            if (!body.record) {
-                throw new ServiceError("VALIDATION", "record required", 400);
-            }
-            const record = {
-                ...body.record,
-                objectType: body.objectType,
-                contentType: body.contentType,
-            };
-            if (record._system && typeof record._system === "object") {
-                const system = { ...record._system };
-                delete system._datasource;
-                record._system = system;
-            }
-            let result;
-            let hooks;
-            const objectType = body.objectType;
-            const contentType = body.contentType;
-            const recordId = body.record.recordId;
-            if (op === "add" || precondition.form === "absent") {
-                const noted = await runHookTrigger(() => ports.writer.add({
-                    scope,
-                    precondition: { kind: "absent" },
-                    record,
-                    datasource,
-                    suppressHooks,
-                }));
-                result = noted.value;
-                hooks = noted.hooks;
-            }
-            else if (op === "patch") {
-                const noted = await runHookTrigger(() => ports.writer.patch({
-                    scope,
-                    precondition: { kind: "revision", revision: Number(expectedRevision) },
-                    objectType,
-                    contentType,
-                    recordId,
-                    ops: body.patch ?? [],
-                    datasource,
-                    suppressHooks,
-                }));
-                result = noted.value;
-                hooks = noted.hooks;
-            }
-            else if (op === "replace") {
-                const noted = await runHookTrigger(() => ports.writer.replace({
-                    scope,
-                    precondition: { kind: "revision", revision: Number(expectedRevision) },
-                    record,
-                    datasource,
-                    suppressHooks,
-                }));
-                result = noted.value;
-                hooks = noted.hooks;
-            }
-            else {
-                // exact-revision upsert — never silently treat as create
-                const noted = await runHookTrigger(() => ports.writer.upsert({
-                    scope,
-                    precondition: { kind: "revision", revision: Number(expectedRevision) },
-                    record,
-                    datasource,
-                    suppressHooks,
-                }));
-                result = noted.value;
-                hooks = noted.hooks;
-            }
-            const indexing = await maybeEnqueueNexumAnalysis({
-                platform,
-                scope,
-                objectType: body.objectType,
-                contentType: body.contentType,
-                recordId: result.record.recordId,
-                revision: result.record.revision,
-                data: result.record.data &&
-                    typeof result.record.data === "object" &&
-                    !Array.isArray(result.record.data)
-                    ? result.record.data
-                    : body.record?.data &&
-                        typeof body.record.data === "object" &&
-                        !Array.isArray(body.record.data)
-                        ? body.record.data
-                        : undefined,
-            });
-            memorixActivityRing.recordLand({
-                orgId: scope.orgId,
-                caller: getRequestCaller(req),
-                objectType: body.objectType,
-                contentType: body.contentType,
-                recordId: result.record.recordId,
-                revision: result.record.revision,
-                outcome: result.created ? "created" : "updated",
-                indexing,
-                hooks,
-            });
-            return {
-                scope,
-                written: true,
-                outcome: result.created ? "created" : "updated",
-                result,
-                currentRevision: result.record.revision,
-                precondition: body.precondition,
-                indexing,
-            };
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (/stale|revision|WRITE_STALE/i.test(msg)) {
-                throw new ServiceError("REVISION_CONFLICT", msg, 409);
-            }
-            throw err;
-        }
+        return { scope, receipts: rows.map(publicWriteReceipt) };
+    });
+    app.get("/api/data/receipts/:receiptId", async (req) => {
+        requireCallbackAccess(req, "explore");
+        const scope = resolveScope(req);
+        const caller = requireCaller(req);
+        const receiptId = req.params.receiptId?.trim() ?? "";
+        if (!receiptId)
+            throw new ServiceError("VALIDATION", "receiptId required", 400, { field: "receiptId" });
+        const row = await platform.writeReceiptsFor(scope.orgId).get(scope.orgId, receiptId);
+        if (!row || row.caller !== caller) {
+            throw new ServiceError("NOT_FOUND", "receipt not found", 404, { field: "receiptId", retryable: false });
+        }
+        return publicWriteReceipt(row);
+    });
+    app.post("/api/data/content", async (req, reply) => {
+        requireDeploymentAccess(req, "write");
+        const scope = resolveScope(req);
+        const body = (req.body ?? {});
+        await platform.analytics?.prepare(scope.orgId);
+        const caller = requireCaller(req);
+        const outcome = await runContentWrite({
+            scope,
+            caller,
+            datasource: contentDatasource(req, body),
+            ports: platform.portsFor(scope),
+            receipts: platform.writeReceiptsFor(scope.orgId),
+            onCommitted: (event) => commitWriteEffects({ platform, scope, caller, event }),
+            checkWrite: patchGuardCheck(platform, scope),
+        }, body);
+        if (outcome.kind === "rejected")
+            throw outcome.error;
+        if (outcome.kind === "pending")
+            return reply.code(202).send(outcome.body);
+        return outcome.body;
     });
     app.post("/api/data/content/move-fields", async (req) => {
         requireDeploymentAccess(req, "write");
@@ -540,15 +547,37 @@ export async function registerDataRoutes(app, platform) {
             pageInfo: recordId ? undefined : { nextCursor, limit },
         };
     });
+    app.get("/api/data/subjects/*", async (req) => {
+        requireCallbackAccess(req, "explore");
+        const scope = resolveScope(req);
+        const recordId = subjectRecordIdFromRequest(req);
+        const ports = platform.portsFor(scope);
+        const reader = ports.reader;
+        if (typeof reader.getSubject !== "function") {
+            throw new ServiceError("CANONICAL_PORT_MISSING", "Subject catalog requires @x12i/memorix-data with getSubject", 501);
+        }
+        const entry = await reader.getSubject(scope, recordId);
+        if (!entry) {
+            throw new ServiceError("READ_NOT_FOUND", `Subject ${recordId} is not reserved`, 404);
+        }
+        return {
+            scope,
+            recordId: entry.recordId,
+            objectType: entry.objectType,
+            dataCategory: entry.dataCategory,
+            contentTypes: entry.contentTypes,
+        };
+    });
     app.post("/api/data/compose", async (req) => {
         requireCallbackAccess(req, "explore");
         const scope = resolveScope(req);
         const body = parseComposeBody(req.body);
         const ports = platform.portsFor(scope);
-        const composition = await ports.reader.composeSubject(scope, {
+        const includeMarkdown = body.include?.markdown === true;
+        const composition = (await ports.reader.composeSubject(scope, {
             recordId: body.recordId,
             contentTypes: body.contentTypes,
-        });
+        }, includeMarkdown ? { include: { markdown: true } } : undefined));
         // Flatten sibling content instances for operator UI — every instance must match subject.
         const instances = [];
         for (const [contentType, list] of Object.entries(composition.contents ?? {})) {
@@ -561,6 +590,7 @@ export async function registerDataRoutes(app, platform) {
                     dataCategory: composition.dataCategory,
                     revision: rec.revision ?? null,
                     data: rec.data ?? null,
+                    ...(includeMarkdown && rec._markdown !== undefined ? { _markdown: rec._markdown } : {}),
                 });
             }
         }
@@ -727,6 +757,8 @@ export async function registerDataRoutes(app, platform) {
         if (!body.leadingContentType?.trim()) {
             throw new ServiceError("VALIDATION", "leadingContentType required", 400);
         }
+        const include = parseIncludeObject(body.include);
+        const includeMarkdown = include?.markdown === true;
         const limit = Math.min(Math.max(Number(body.limit ?? 50) || 50, 1), 200);
         const filters = parseSafeFiltersValue(body.filter);
         const sort = parseSafeSortValue(body.sort);
@@ -739,11 +771,20 @@ export async function registerDataRoutes(app, platform) {
             sort,
             limit,
             cursor: body.cursor,
+            ...(includeMarkdown ? { include: { markdown: true } } : {}),
         });
         const items = listed.items.map((composition) => {
             const contents = {};
             for (const [contentType, list] of Object.entries(composition.contents ?? {})) {
-                contents[contentType] = list.map((rec) => rec.data ?? null);
+                contents[contentType] = list.map((rec) => {
+                    if (!includeMarkdown)
+                        return rec.data ?? null;
+                    return {
+                        data: rec.data ?? null,
+                        revision: rec.revision ?? null,
+                        ...(rec._markdown !== undefined ? { _markdown: rec._markdown } : {}),
+                    };
+                });
             }
             return {
                 recordId: composition.recordId,
@@ -802,6 +843,7 @@ function parseComposeBody(raw) {
     return {
         recordId: body.recordId,
         contentTypes: body.contentTypes,
+        include: parseIncludeObject(body.include),
     };
 }
 function assertComposeInstanceRecordId(subjectId, rec) {