@x12i/memorix-service 3.0.2 → 3.0.4

package/dist/routes/memory.js

@@ -1,5 +1,71 @@
+import { cursorKeyFor, listCheckpointSummariesForSource, toCheckpointSummary, resolveCheckpointMethod, upsertMemorySchedule, pullWithSourceClaim, computeNextDueAt, computeInitialNextDueAt, createInMemoryPushEnvelopeStore, } from "@x12i/memorix-memory";
+import { credentialHandleFromDelegation, createCredentialHandle, } from "@x12i/memorix-connector-sdk";
 import { resolveScope } from "../request-scope.js";
 import { ServiceError } from "../errors.js";
+import { forbidCallbackGrant, requireCallbackAccess } from "../access-gate.js";
+const CONNECTION_PROBE_MS = 2000;
+/** Module-level replay ledger — lives for the process lifetime. */
+const pushEnvelopeStore = createInMemoryPushEnvelopeStore({ maxSize: 50_000 });
+/**
+ * Resolve credentials for validate/health/configureReceive.
+ * Uses a short-lived Credorix delegation when platform.credorix is configured.
+ */
+async function resolveRouteCredentials(platform, scope, source, connectorId, connectorVersion = "0.0.0") {
+    const authRef = source.credentialRef ?? null;
+    if (!platform.credorix || !authRef) {
+        return {
+            credentials: createCredentialHandle(authRef, async () => ({})),
+        };
+    }
+    const { provider } = platform.credorix;
+    const delegation = await provider.mintDelegation({
+        organizationId: scope.orgId,
+        sourceId: source.id,
+        connectorId,
+        connectorVersion,
+        authRef,
+        purposes: ["provider-http", "webhook-verification"],
+        allowedOrigins: ["*"],
+        ttlSeconds: 60,
+        correlation: { runId: "validate-or-health" },
+    });
+    return {
+        credentials: credentialHandleFromDelegation(provider, delegation.delegationId, authRef),
+        invalidate: async () => {
+            await provider.invalidate(delegation.delegationId, "validate-or-health-done");
+        },
+    };
+}
+function resolveSourceBaseUrl(source) {
+    const baseUrlEnv = typeof source.baseUrlEnv === "string" ? source.baseUrlEnv.trim() : "";
+    if (baseUrlEnv) {
+        const fromEnv = process.env[baseUrlEnv];
+        if (fromEnv?.trim())
+            return fromEnv.trim().replace(/\/+$/, "");
+    }
+    const defaultBaseUrl = typeof source.defaultBaseUrl === "string" ? source.defaultBaseUrl.trim() : "";
+    if (defaultBaseUrl)
+        return defaultBaseUrl.replace(/\/+$/, "");
+    return null;
+}
+async function probeSourceHealth(baseUrl) {
+    try {
+        const res = await fetch(`${baseUrl}/health`, {
+            signal: AbortSignal.timeout(CONNECTION_PROBE_MS),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveSourceDefinition(platform, agentIds, sourceId) {
+    const def = platform.metadata.getDefinition(agentIds, "sources", sourceId);
+    if (!def) {
+        throw new ServiceError("NOT_FOUND", `source not found: ${sourceId}`, 404);
+    }
+    return def.definition;
+}
 export async function registerMemoryRoutes(app, platform) {
     app.get("/api/memory/sources", async (req) => {
         const scope = resolveScope(req);
@@ -9,46 +75,427 @@ export async function registerMemoryRoutes(app, platform) {
             .map((e) => {
             const d = e.definition;
             const { credential: _c, credentials: _cs, secret: _s, ...safe } = d;
-            return { id: e.id, ...safe };
+            return {
+                id: e.id,
+                ...safe,
+                provenance: {
+                    definedByAgentId: e.provenance.definedByAgentId,
+                    inheritancePath: e.provenance.inheritancePath,
+                    selectedAgentId: e.provenance.selectedAgentId,
+                },
+            };
         });
         return { scope, sources, note: "credentialRef only" };
     });
+    app.get("/api/memory/sources/:sourceId/connection", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const effective = platform.metadata.resolveEffective(scope.agentIds);
+        const entry = (effective.effective ?? []).find((e) => e.kind === "sources" && e.id === sourceId);
+        if (!entry) {
+            throw new ServiceError("NOT_FOUND", `source not found: ${sourceId}`, 404);
+        }
+        const definition = entry.definition;
+        const baseUrl = resolveSourceBaseUrl(definition);
+        const checkedAt = new Date().toISOString();
+        if (!baseUrl) {
+            return {
+                scope,
+                sourceId,
+                status: "Missing URL",
+                configured: false,
+                reachable: false,
+                checkedAt,
+            };
+        }
+        const reachable = await probeSourceHealth(baseUrl);
+        return {
+            scope,
+            sourceId,
+            status: reachable ? "Connected" : "Unreachable",
+            configured: true,
+            reachable,
+            checkedAt,
+        };
+    });
+    app.get("/api/memory/sources/:sourceId/checkpoints", async (req) => {
+        requireCallbackAccess(req, "checkpoints");
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const ports = platform.portsFor(scope);
+        const cursors = await ports.memoryRunStore.listCursors({ sourceId });
+        const mode = req.query.mode === "context" || req.query.mode === "knowledge"
+            ? req.query.mode
+            : undefined;
+        const includeTechnical = req.query.technical === "1" || req.query.technical === "true";
+        const checkpoints = listCheckpointSummariesForSource({
+            source,
+            mode,
+            cursors,
+            includeTechnical,
+        });
+        return {
+            scope,
+            sourceId,
+            checkpoints,
+            note: "Memorix remembers the last successfully pulled position for every object type populated by this source.",
+        };
+    });
+    app.get("/api/memory/sources/:sourceId/checkpoints/:checkpointKey", async (req) => {
+        requireCallbackAccess(req, "checkpoints");
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        const checkpointKey = decodeURIComponent(String(req.params.checkpointKey ?? "").trim());
+        if (!sourceId || !checkpointKey) {
+            throw new ServiceError("VALIDATION", "sourceId and checkpointKey required", 400);
+        }
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const ports = platform.portsFor(scope);
+        const doc = await ports.memoryRunStore.getCursor(checkpointKey);
+        if (!doc || doc.sourceId !== sourceId) {
+            throw new ServiceError("NOT_FOUND", `checkpoint not found: ${checkpointKey}`, 404);
+        }
+        return {
+            scope,
+            sourceId,
+            checkpoint: toCheckpointSummary(doc, { includeTechnical: true }),
+        };
+    });
+    app.post("/api/memory/sources/:sourceId/checkpoints/reset", async (req) => {
+        requireCallbackAccess(req, "checkpoints");
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        const ports = platform.portsFor(scope);
+        const mode = body.mode ?? "knowledge";
+        let reset = [];
+        if (body.all) {
+            const cursors = await ports.memoryRunStore.listCursors({ sourceId });
+            for (const c of cursors) {
+                await ports.memoryRunStore.deleteCursor(c.cursorKey);
+                reset.push(c.cursorKey);
+            }
+        }
+        else {
+            if (!body.objectType) {
+                throw new ServiceError("VALIDATION", "objectType required (or all: true)", 400);
+            }
+            const route = (source.routes ?? []).find((r) => r.objectType === body.objectType &&
+                (body.routeEndpoint == null || r.endpoint === body.routeEndpoint));
+            const routeEndpoint = body.routeEndpoint ?? route?.endpoint ?? "";
+            const key = cursorKeyFor({
+                sourceId,
+                objectType: body.objectType,
+                mode,
+                routeEndpoint,
+                workRef: body.workRef,
+            });
+            const deleted = await ports.memoryRunStore.deleteCursor(key);
+            if (deleted)
+                reset.push(key);
+        }
+        return {
+            scope,
+            sourceId,
+            reset,
+            note: "Next pull starts from the beginning for the reset checkpoint(s).",
+        };
+    });
+    app.put("/api/memory/sources/:sourceId/checkpoints", async (req) => {
+        requireCallbackAccess(req, "checkpoints");
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        if (!body.objectType) {
+            throw new ServiceError("VALIDATION", "objectType required", 400);
+        }
+        const route = (source.routes ?? []).find((r) => r.objectType === body.objectType &&
+            (body.routeEndpoint == null || r.endpoint === body.routeEndpoint));
+        if (!route && !body.routeEndpoint) {
+            throw new ServiceError("VALIDATION", `route not found for objectType ${body.objectType}`, 400);
+        }
+        const routeEndpoint = body.routeEndpoint ?? route.endpoint;
+        const mode = body.mode ?? "knowledge";
+        const method = body.method ??
+            (route ? resolveCheckpointMethod(route, source) : "cursor");
+        const key = cursorKeyFor({
+            sourceId,
+            objectType: body.objectType,
+            mode,
+            routeEndpoint,
+            workRef: body.workRef,
+        });
+        const ports = platform.portsFor(scope);
+        const existing = await ports.memoryRunStore.getCursor(key);
+        const currentRev = existing?.revision ?? 0;
+        if (body.expectedRevision != null &&
+            body.expectedRevision !== currentRev) {
+            throw new ServiceError("CONFLICT", `checkpoint revision conflict: expected ${body.expectedRevision}, got ${currentRev}`, 409);
+        }
+        const now = new Date().toISOString();
+        const doc = {
+            cursorKey: key,
+            sourceId,
+            objectType: body.objectType,
+            mode,
+            routeEndpoint,
+            workRef: body.workRef,
+            method,
+            committedCursor: body.committedCursor ?? null,
+            watermarkValue: body.watermarkValue ?? null,
+            fingerprintsEstablished: body.fingerprintsEstablished === true,
+            revision: currentRev + 1,
+            updatedAt: now,
+            lastPullId: body.pullId ?? `svc_${Date.now()}`,
+            lastSuccessfulPullAt: now,
+        };
+        await ports.memoryRunStore.setCursor(doc);
+        return {
+            scope,
+            sourceId,
+            checkpoint: toCheckpointSummary(doc, { includeTechnical: true }),
+            note: "Administrative checkpoint put is not proof that raw data landed; prefer commit-page for service-controlled collection.",
+        };
+    });
     app.post("/api/memory/pull", async (req) => {
+        forbidCallbackGrant(req);
         const scope = resolveScope(req);
-        const body = req.body;
+        const body = (req.body ?? {});
         if (body.credential !== undefined) {
             throw new ServiceError("SECRETS_FORBIDDEN", "resolved credentials must not cross the API; use credentialRef only", 400);
         }
         if (!body.sourceId)
             throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const mode = body.mode ?? "knowledge";
         const ports = platform.portsFor(scope);
-        const result = await ports.memory.pull({
-            scope,
+        const ownerId = `pull:${scope.orgId}:${Date.now()}`;
+        const claimed = await pullWithSourceClaim({
+            scheduleStore: ports.memoryScheduleStore,
             sourceId: body.sourceId,
-            mode: body.mode ?? "knowledge",
-            trigger: "on-demand",
+            mode,
+            ownerId,
+            pull: () => ports.memory.pull({
+                scope,
+                sourceId: body.sourceId,
+                mode,
+                trigger: "on-demand",
+                cursor: body.cursor,
+                workRef: body.workRef,
+            }),
         });
+        if ("conflict" in claimed) {
+            throw new ServiceError("CONFLICT", `a pull is already in progress for source ${body.sourceId}`, 409);
+        }
+        const result = claimed.result;
         return {
             scope,
             runId: result.pullId,
+            pullId: result.pullId,
             sourceId: body.sourceId,
             mode: result.mode,
+            trigger: result.trigger,
             credentialRef: body.credentialRef ?? null,
             status: result.status,
             result: {
                 created: result.created,
                 updated: result.updated,
+                deduplicated: result.deduplicated,
+                quarantined: result.quarantined,
+                pagesReceived: result.pagesReceived,
+                itemsReceived: result.itemsReceived,
+                endingCursor: result.endingCursor,
+            },
+            ...(result.failureSummary ? { failureSummary: result.failureSummary } : {}),
+        };
+    });
+    app.get("/api/memory/sources/:sourceId/schedule", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const mode = req.query.mode === "context" ? "context" : "knowledge";
+        const ports = platform.portsFor(scope);
+        const schedule = await ports.memoryScheduleStore.getSchedule(sourceId, mode);
+        return { scope, sourceId, mode, schedule };
+    });
+    app.put("/api/memory/sources/:sourceId/schedule", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        if (!body.interval) {
+            throw new ServiceError("VALIDATION", "interval required", 400);
+        }
+        const ports = platform.portsFor(scope);
+        try {
+            const schedule = await upsertMemorySchedule(ports.memoryScheduleStore, {
+                scope,
+                sourceId,
+                mode: body.mode ?? "knowledge",
+                interval: body.interval,
+                firstPull: body.firstPull,
+                status: body.status,
+            });
+            return { scope, sourceId, schedule };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new ServiceError("VALIDATION", msg, 400);
+        }
+    });
+    app.post("/api/memory/sources/:sourceId/schedule/pause", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const mode = req.query.mode === "context" ? "context" : "knowledge";
+        const ports = platform.portsFor(scope);
+        const existing = await ports.memoryScheduleStore.getSchedule(sourceId, mode);
+        if (!existing) {
+            throw new ServiceError("NOT_FOUND", `schedule not found for ${sourceId}`, 404);
+        }
+        const schedule = {
+            ...existing,
+            status: "paused",
+            updatedAt: new Date().toISOString(),
+            revision: existing.revision + 1,
+        };
+        await ports.memoryScheduleStore.saveSchedule(schedule);
+        return { scope, sourceId, schedule };
+    });
+    app.post("/api/memory/sources/:sourceId/schedule/resume", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const mode = req.query.mode === "context" ? "context" : "knowledge";
+        const ports = platform.portsFor(scope);
+        const existing = await ports.memoryScheduleStore.getSchedule(sourceId, mode);
+        if (!existing) {
+            throw new ServiceError("NOT_FOUND", `schedule not found for ${sourceId}`, 404);
+        }
+        const now = new Date();
+        let nextDueAt = existing.nextDueAt;
+        if (nextDueAt <= now.toISOString()) {
+            nextDueAt = computeInitialNextDueAt(now, existing.interval, "immediate");
+        }
+        const schedule = {
+            ...existing,
+            status: "active",
+            nextDueAt,
+            updatedAt: now.toISOString(),
+            revision: existing.revision + 1,
+        };
+        await ports.memoryScheduleStore.saveSchedule(schedule);
+        return { scope, sourceId, schedule };
+    });
+    app.post("/api/memory/sources/:sourceId/schedule/run-now", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const mode = req.query.mode === "context" ? "context" : "knowledge";
+        const ports = platform.portsFor(scope);
+        const existing = await ports.memoryScheduleStore.getSchedule(sourceId, mode);
+        const ownerId = `run-now:${scope.orgId}:${Date.now()}`;
+        const claimed = await pullWithSourceClaim({
+            scheduleStore: ports.memoryScheduleStore,
+            sourceId,
+            mode,
+            ownerId,
+            pull: () => ports.memory.pull({
+                scope,
+                sourceId,
+                mode,
+                trigger: "scheduled",
+            }),
+        });
+        if ("conflict" in claimed) {
+            throw new ServiceError("CONFLICT", `a pull is already in progress for source ${sourceId}`, 409);
+        }
+        const result = claimed.result;
+        const now = new Date();
+        if (existing) {
+            await ports.memoryScheduleStore.saveSchedule({
+                ...existing,
+                lastFiredAt: now.toISOString(),
+                lastPullId: result.pullId,
+                lastStatus: result.status,
+                nextDueAt: computeNextDueAt(now, existing.interval),
+                updatedAt: now.toISOString(),
+                revision: existing.revision + 1,
+            });
+        }
+        return {
+            scope,
+            sourceId,
+            mode,
+            pullId: result.pullId,
+            status: result.status,
+            result: {
+                created: result.created,
+                updated: result.updated,
+                deduplicated: result.deduplicated,
                 quarantined: result.quarantined,
                 pagesReceived: result.pagesReceived,
+                itemsReceived: result.itemsReceived,
                 endingCursor: result.endingCursor,
             },
+            schedule: existing
+                ? await ports.memoryScheduleStore.getSchedule(sourceId, mode)
+                : null,
         };
     });
+    app.delete("/api/memory/sources/:sourceId/schedule", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const mode = req.query.mode === "context" ? "context" : "knowledge";
+        const ports = platform.portsFor(scope);
+        const removed = await ports.memoryScheduleStore.deleteSchedule(sourceId, mode);
+        return { scope, sourceId, mode, removed };
+    });
     app.get("/api/memory/runs", async (req) => {
         const scope = resolveScope(req);
-        return { scope, runs: [], quarantine: [], checkpoints: [] };
+        const q = req.query;
+        const ports = platform.portsFor(scope);
+        const limit = q.limit ? Number(q.limit) : 50;
+        const runs = await ports.memoryRunStore.listRuns({
+            sourceId: q.sourceId,
+            mode: q.mode,
+            limit: Number.isFinite(limit) ? limit : 50,
+        });
+        let quarantine = await ports.memoryRunStore.listQuarantine();
+        if (q.sourceId) {
+            quarantine = quarantine.filter((item) => item.sourceId === q.sourceId);
+        }
+        const cursors = await ports.memoryRunStore.listCursors({
+            sourceId: q.sourceId,
+        });
+        const checkpoints = cursors.map((c) => toCheckpointSummary(c));
+        return { scope, runs, quarantine, checkpoints };
     });
     app.get("/api/memory/raw", async (req) => {
+        requireCallbackAccess(req, "raw");
         const scope = resolveScope(req);
         const q = req.query;
         if (!q.objectType || !q.id) {
@@ -76,5 +523,270 @@ export async function registerMemoryRoutes(app, platform) {
             note: "exact raw .data landing; no secrets; associated* must not be copied to root",
         };
     });
+    app.post("/api/memory/sources/:sourceId/commit-page", async (req) => {
+        requireCallbackAccess(req, "checkpoints");
+        requireCallbackAccess(req, "raw");
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        if (!body.objectType) {
+            throw new ServiceError("VALIDATION", "objectType required", 400);
+        }
+        if (!Array.isArray(body.items)) {
+            throw new ServiceError("VALIDATION", "items array required", 400);
+        }
+        if (body.expectedCheckpointRevision == null) {
+            throw new ServiceError("VALIDATION", "expectedCheckpointRevision required", 400);
+        }
+        const route = (source.routes ?? []).find((r) => r.objectType === body.objectType &&
+            (body.routeEndpoint == null || r.endpoint === body.routeEndpoint));
+        const streamMatch = typeof body.streamId === "string" && body.streamId.trim()
+            ? (source.streams ?? []).find((s) => s.streamId === body.streamId)
+            : undefined;
+        if (!route && !streamMatch) {
+            throw new ServiceError("VALIDATION", `route not found for objectType ${body.objectType}`, 400);
+        }
+        const ports = platform.portsFor(scope);
+        let receipt;
+        try {
+            receipt = await ports.memory.commitPage({
+                scope,
+                sourceId,
+                objectType: body.objectType,
+                routeEndpoint: body.routeEndpoint ??
+                    route?.endpoint ??
+                    streamMatch?.endpoint ??
+                    "",
+                mode: body.mode ?? "knowledge",
+                workRef: body.workRef,
+                items: body.items,
+                nextCheckpoint: body.nextCheckpoint ?? {},
+                expectedCheckpointRevision: body.expectedCheckpointRevision,
+                pullId: body.pullId,
+                streamId: body.streamId,
+                connectorId: body.connectorId,
+                connectorVersion: body.connectorVersion,
+                trigger: body.trigger,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/CHECKPOINT_REVISION_CONFLICT/i.test(msg)) {
+                throw new ServiceError("CONFLICT", msg, 409);
+            }
+            throw new ServiceError("MEMORY_COMMIT_FAILED", msg, 400);
+        }
+        return { scope, sourceId, ...receipt };
+    });
+    /** Provider-originated push ingress — same land/quarantine/run path as pulls (FR-024). */
+    app.post("/api/memory/sources/:sourceId/receive", async (req) => {
+        forbidCallbackGrant(req);
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        // Delivery replay guard — short-circuit duplicate provider deliveries.
+        const deliveryId = body.deliveryId?.trim() || null;
+        if (deliveryId) {
+            const prior = await pushEnvelopeStore.getByDeliveryId(deliveryId, sourceId);
+            if (prior?.result) {
+                return {
+                    scope,
+                    sourceId,
+                    result: prior.result,
+                    replayed: true,
+                    deliveryId,
+                    note: "Duplicate delivery detected; returning cached result.",
+                };
+            }
+        }
+        const ports = platform.portsFor(scope);
+        const result = await ports.memory.receive({
+            scope,
+            sourceId,
+            mode: body.mode ?? "knowledge",
+            trigger: "provider_push",
+            workRef: body.workRef,
+            receivePayload: body.payload ?? req.body,
+            receiveHeaders: {
+                ...(body.headers ?? {}),
+                ...(deliveryId ? { "x-delivery-id": deliveryId } : {}),
+            },
+        });
+        // Persist delivery so future duplicates can be short-circuited.
+        if (deliveryId) {
+            await pushEnvelopeStore.save({
+                deliveryId,
+                receivedAt: new Date().toISOString(),
+                sourceId,
+                method: req.method,
+                path: req.url,
+                result: {
+                    status: result.status,
+                    created: result.created ?? 0,
+                    updated: result.updated ?? 0,
+                    deduplicated: result.deduplicated ?? 0,
+                    quarantined: result.quarantined ?? 0,
+                },
+            });
+        }
+        return { scope, sourceId, result, ...(deliveryId ? { deliveryId } : {}) };
+    });
+    app.post("/api/memory/sources/:sourceId/validate", async (req) => {
+        forbidCallbackGrant(req);
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const connectorRef = source.connectorRef
+            ?? source.kind;
+        const connector = connectorRef
+            ? platform.connectorRegistry.resolveRuntime(connectorRef)
+            : null;
+        if (connector?.validate) {
+            const { credentials, invalidate } = await resolveRouteCredentials(platform, scope, source, connectorRef ?? "unknown", connector.manifest?.version ?? "0.0.0");
+            try {
+                const result = await connector.validate({
+                    source,
+                    credentials,
+                });
+                return { scope, sourceId, ...result };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { scope, sourceId, ok: false, checks: [], error: msg };
+            }
+            finally {
+                await invalidate?.();
+            }
+        }
+        return {
+            scope,
+            sourceId,
+            ok: true,
+            checks: [
+                {
+                    code: "SOURCE_RESOLVED",
+                    status: "pass",
+                    message: `source ${source.id} resolved for connector ${connectorRef ?? source.kind}`,
+                },
+                {
+                    code: "CREDENTIAL_REF",
+                    status: source.credentialRef ? "pass" : "warning",
+                    message: source.credentialRef
+                        ? `credentialRef ${source.credentialRef} present`
+                        : "no credentialRef configured",
+                },
+            ],
+            note: "Connector.validate hooks are invoked when a framework connector declares validation capability.",
+        };
+    });
+    app.get("/api/memory/sources/:sourceId/health", async (req) => {
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const connectorRef = source.connectorRef
+            ?? source.kind;
+        const connector = connectorRef
+            ? platform.connectorRegistry.resolveRuntime(connectorRef)
+            : null;
+        if (connector?.health) {
+            const { credentials, invalidate } = await resolveRouteCredentials(platform, scope, source, connectorRef ?? "unknown", connector.manifest?.version ?? "0.0.0");
+            try {
+                const result = await connector.health({
+                    source,
+                    credentials,
+                });
+                return {
+                    scope, sourceId,
+                    ...result,
+                    checks: result.checks ?? [],
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { scope, sourceId, ok: false, checks: [], error: msg };
+            }
+            finally {
+                await invalidate?.();
+            }
+        }
+        return {
+            scope,
+            sourceId,
+            ok: true,
+            checks: [],
+            detail: "connector host reachable (framework health hook optional)",
+        };
+    });
+    app.get("/api/connectors", async (req) => {
+        const scope = resolveScope(req);
+        const frameworkConnectors = platform.connectorRegistry.list().map((doc) => ({
+            id: doc.connectorId,
+            version: doc.version,
+            protocol: doc.protocol,
+            enabled: doc.enabled,
+            workflowHash: doc.workflowHash,
+        }));
+        const legacyConnectors = [
+            { id: "rest-fixture", version: "0.0.0-legacy", protocol: "memorix-connector/1", enabled: true },
+            { id: "opx-fixture", version: "0.0.0-legacy", protocol: "memorix-connector/1", enabled: true },
+            { id: "knowx-fixture", version: "0.0.0-legacy", protocol: "memorix-connector/1", enabled: true },
+        ];
+        // Deduplicate: framework connectors take precedence over legacy stubs.
+        const frameworkIds = new Set(frameworkConnectors.map((c) => c.id));
+        const connectors = [
+            ...frameworkConnectors,
+            ...legacyConnectors.filter((c) => !frameworkIds.has(c.id)),
+        ];
+        return { scope, connectors };
+    });
+    /** Admin-only subscription management — never mixed into Pull (FR-028). */
+    app.post("/api/memory/sources/:sourceId/receive:configure", async (req) => {
+        forbidCallbackGrant(req);
+        const scope = resolveScope(req);
+        const sourceId = String(req.params.sourceId ?? "").trim();
+        if (!sourceId)
+            throw new ServiceError("VALIDATION", "sourceId required", 400);
+        const source = resolveSourceDefinition(platform, scope.agentIds, sourceId);
+        const body = (req.body ?? {});
+        const action = body.action ?? "create";
+        const connectorRef = source.connectorRef ??
+            source.kind;
+        const connector = connectorRef
+            ? platform.connectorRegistry.resolveRuntime(connectorRef)
+            : null;
+        if (!connector?.configureReceive) {
+            return {
+                scope,
+                sourceId,
+                ok: false,
+                audited: true,
+                action,
+                note: "connector does not declare configureReceive",
+            };
+        }
+        const { credentials, invalidate } = await resolveRouteCredentials(platform, scope, source, connectorRef ?? "unknown", connector.manifest?.version ?? "0.0.0");
+        try {
+            const result = await connector.configureReceive({
+                source,
+                action,
+                subscription: body.subscription,
+                credentials,
+            });
+            return { scope, sourceId, ok: true, audited: true, action, result };
+        }
+        finally {
+            await invalidate?.();
+        }
+    });
 }
 //# sourceMappingURL=memory.js.map