@x12i/memorix-client-api 0.17.0 → 0.19.0

package/HANDOVER.md

@@ -38,19 +38,20 @@ The listen port comes from `attachCoreFastify` (`MEMORIX_CLIENT_API_PORT`, defau
 | `MEMORIX_AUTH` | `header` | `header` takes the org from `x-memorix-org-id`. `authix` takes it from `Authorization: Bearer` via `@x12i/authix-sdk`. |
 | `MGC_MCP_URL` | | MGC MCP endpoint. Wins over the source service URL. |
 | `MGC_SOURCE_SERVICE_URL` or `MGC_URL` | | MGC source host. This process calls `{url}/mcp` when `MGC_MCP_URL` is unset. When both are unset, it reads `genericConnectors.mcpUrl` from Memorix. |
-| `SCOPER_REASONER` | scripted, or ai-dispatcher when `OPENROUTER_API_KEY` is set | Reasoner for the hosted `@x12i/memorix-scoper@2.3.0`. |
+| `SCOPER_REASONER` | scripted, or ai-dispatcher when `OPENROUTER_API_KEY` is set | Reasoner for the hosted `@x12i/memorix-scoper@3.0.0`. |
 | `SCOPER_AI_MODEL` | `openai/gpt-6-luna` | Model when the reasoner is `ai-dispatcher`. Runs on `@x12i/ai-dispatcher@3.2.0`. |
 | `SCOPER_FUNCTIONS_DIR` | | Pagx directory of saved query and scope functions, passed to `createScoper({ functions })`. |
 | `SCOPER_FUNCTIONS_PACKAGE` | | Parent package name for that directory. |
 | `SCOPER_FUNCTIONS_LEARN` | off | `true` asks the coder to write a function on a miss. Needs `@x12i/coder-dispatcher`. |
-| `SCOPER_MODE` | `auto` | `auto` hosts Scoper here unless `SCOPER_URL` is healthy and `2.3.x`. `external` requires that peer. `embedded` does not probe. |
+| `SCOPER_MODE` | `auto` | `auto` hosts Scoper here unless `SCOPER_URL` is healthy and `3.x`. `external` requires that peer and does not load the Scoper packages. `embedded` does not probe. See `docs/scoper-downstream.md`. |
 | `SCOPER_URL` | | Base URL of a Scoper peer. Proxied for the process lifetime when selected. |
 | `SKILLS_MODE` | `auto` | `auto` probes skill-api and hosts agent functions here when that probe fails. `external` requires the peer. `embedded` does not probe. |
 | `SKILL_API_URL` | `http://127.0.0.1:7180` in `auto` | Skill-api base. A selected peer answers list, run, save, and delete. |
 | `SKILLS_PACK_DIR` | | Pack directory with `functions/catalog.json` and `functions/run.mjs`. Used when functions are hosted here. |
 | `AGENTS_DIR` | | Agents root. A folder named for the agent, or the first pack with functions, is the catalog. |
 | `MEMORIX_AGENT_IDS` | | Content agents that use the process pack. `PROCESS_AGENT_ID` is the fallback. |
-| `ASSISTANT_MONGO_URI` or `MONGO_URI` | | Assistants database for function overrides. Unset: pack functions run, save returns `503`. Not opened when skill-api is the peer. |
+| `ASSISTANT_MONGO_URI` or `MONGO_URI` | | Assistants database `{orgId}-memorix-assistants`: function overrides (only while functions are hosted here) and planning items (collection `planning_items`). Unset: pack functions run, save returns `503`, and planning routes are `501 CAPABILITY_UNAVAILABLE`. |
+| `PLANNING_ASSIGNEES` | | JSON object of org id to `[{ "id", "name", "kind"? }]`. Planning assignee options. Unset: only unassigned. |
 | `AUTHIX_APP_ID` | | Required with `MEMORIX_AUTH=authix`. |
 | `AUTHIX_APP_SECRET_KEY` | | Required with `MEMORIX_AUTH=authix`. |
 | `AUTHIX_INTROSPECT_URL` | | Optional revocation check, for example `http://127.0.0.1:3100/v1/tokens/introspect`. |
@@ -63,6 +64,16 @@ npm run typecheck
 npm run build && npm start
 ```
 
+The `visualizer` contract (`docs/visualizer-api.md`) is served from `src/v1/`. Every `/api/v1` route checks the requested agents against `GET /api/metadata/agents?scope=org` (reused for 30 seconds): `*` is the org's deployed agents, and an agent the org has not deployed is `403 AGENT_NOT_DEPLOYED`. Against a Memorix without the org agent record, agent ids pass through unchanged.
+
+## Release
+
+1. Bump `package.json` and `package-lock.json` (`npm version <v> --no-git-tag-version`), `openapi/openapi.json` `info.version`, and the version lines in the root `README.md`. The read client also bumps `clientInfo.version` in `src/index.ts`. `memorix-client` adds a `CHANGELOG.md` entry.
+2. In each package: `npm test`, `npm run typecheck`, `npm run build`. Check that `npm view <package>@<version>` is a 404, then `npm pack --dry-run`.
+3. Publish `memorix-client` first, then this server (which depends on it), then the read client: `npm publish --access public`.
+4. Commit and push.
+5. On the host, stop the listener on 5120 and start `npm run dev` in this folder again. Check `/health`, `/ready`, `/api/openapi.json` (`info.version`), and `/api/v1/capabilities` (401 without a token).
+
 ## What must already be on the Memorix host
 
 These stay in the Memorix repo. This API calls them over HTTP.

package/dist/agent-directory.d.ts

@@ -0,0 +1,25 @@
+import { type Upstream } from "./upstream.js";
+export type AgentEntry = {
+    id: string;
+    ok: boolean;
+    error: string | null;
+    objectTypes: Array<{
+        id: string;
+        name?: string;
+        contentTypes: string[];
+    }>;
+};
+export type AgentDirectory = {
+    /**
+     * Agents recorded for the org (`GET /api/metadata/agents?scope=org`).
+     * `null` means Memorix has no org agent record (service older than 3.18.0).
+     */
+    deployed(orgId: string, caller: string): Promise<AgentEntry[] | null>;
+    /** Every pack installed on the platform. */
+    installed(orgId: string, caller: string): Promise<AgentEntry[]>;
+};
+export declare function agentsFromListing(body: unknown): AgentEntry[];
+/** A Memorix without an org agent record: agent ids are sent as requested and `*` is not expanded. */
+export declare const NO_ORG_AGENT_RECORD: AgentDirectory;
+export declare function createAgentDirectory(upstream: Upstream, ttlMs?: number): AgentDirectory;
+//# sourceMappingURL=agent-directory.d.ts.map

package/dist/agent-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-directory.d.ts","sourceRoot":"","sources":["../src/agent-directory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAExD,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3E,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC;IACtE,4CAA4C;IAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CACjE,CAAC;AAIF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,EAAE,CA2B7D;AAED,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,EAAE,cAGjC,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,SAAiB,GAAG,cAAc,CAoC/F"}

package/dist/agent-directory.js

@@ -0,0 +1,75 @@
+import { UpstreamError } from "./errors.js";
+import { asRecord } from "./upstream.js";
+const DEFAULT_TTL_MS = 30_000;
+export function agentsFromListing(body) {
+    const agents = asRecord(body)?.agents;
+    if (!Array.isArray(agents))
+        return [];
+    const out = [];
+    for (const item of agents) {
+        const row = asRecord(item);
+        if (!row || typeof row.id !== "string" || !row.id)
+            continue;
+        const objectTypes = Array.isArray(row.objectTypes)
+            ? row.objectTypes
+                .map((entry) => asRecord(entry))
+                .filter((entry) => entry !== null && typeof entry.id === "string")
+                .map((entry) => ({
+                id: entry.id,
+                ...(typeof entry.name === "string" ? { name: entry.name } : {}),
+                contentTypes: Array.isArray(entry.contentTypes)
+                    ? entry.contentTypes.filter((ct) => typeof ct === "string")
+                    : [],
+            }))
+            : [];
+        out.push({
+            id: row.id,
+            ok: row.ok !== false,
+            error: typeof row.error === "string" ? row.error : null,
+            objectTypes,
+        });
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** A Memorix without an org agent record: agent ids are sent as requested and `*` is not expanded. */
+export const NO_ORG_AGENT_RECORD = {
+    deployed: async () => null,
+    installed: async () => [],
+};
+export function createAgentDirectory(upstream, ttlMs = DEFAULT_TTL_MS) {
+    const cache = new Map();
+    function cached(key, load) {
+        const hit = cache.get(key);
+        if (hit && Date.now() - hit.at < ttlMs)
+            return hit.value;
+        const value = load();
+        cache.set(key, { at: Date.now(), value });
+        value.catch(() => cache.delete(key));
+        return value;
+    }
+    function listingScope(orgId, caller) {
+        return { orgId, agentIds: ["*"], caller };
+    }
+    return {
+        deployed(orgId, caller) {
+            return cached(`org:${orgId}`, async () => {
+                try {
+                    const body = await upstream.get("/api/metadata/agents?scope=org", listingScope(orgId, caller));
+                    if (!Array.isArray(asRecord(body)?.agents))
+                        return null;
+                    return agentsFromListing(body);
+                }
+                catch (err) {
+                    if (err instanceof UpstreamError && (err.statusCode === 404 || err.statusCode === 501))
+                        return null;
+                    throw err;
+                }
+            });
+        },
+        async installed(orgId, caller) {
+            const value = await cached("platform", async () => agentsFromListing(await upstream.get("/api/metadata/agents", listingScope(orgId, caller))));
+            return value ?? [];
+        },
+    };
+}
+//# sourceMappingURL=agent-directory.js.map

package/dist/agent-directory.js.map

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

package/dist/app.d.ts

@@ -1,21 +1,45 @@
 import { type FastifyInstance } from "fastify";
 import { type ScoperReasonerKind } from "./config.js";
 import type { PeerChoice } from "./peers.js";
-import { createScoperHost, type ScoperHost } from "./scoper.js";
+import { type ScoperHost } from "./scoper.js";
+import type { createScoperHost } from "./scoper-embedded.js";
 import { type EmbeddedSkillsOptions, type SkillsHost } from "./skills.js";
+import { type AgentDirectory } from "./agent-directory.js";
+import type { TokenClaims } from "./authix.js";
+import { type PlanningStore } from "./v1/planning-store.js";
 export type ClientApiAuth = {
     mode: "header";
 } | {
     mode: "authix";
-    verify: (token: string) => Promise<{
-        organizationIds: string[];
-    }>;
+    verify: (token: string) => Promise<TokenClaims>;
 };
 export type ClientApiOptions = {
     memorixUrl: string;
     fetchImpl?: typeof fetch;
     /** Default `header`: org comes from `x-memorix-org-id`. */
     auth?: ClientApiAuth;
+    /** Upstream timeout. Default 30000 ms. */
+    upstreamTimeoutMs?: number;
+    /** How long the org's deployed agent list is reused. Default 30000 ms. */
+    agentCacheMs?: number;
+    /** Deployed and installed agents. Default reads `GET /api/metadata/agents` on Memorix. */
+    agentDirectory?: AgentDirectory;
+    /** How long a census is reused per org and agent set. Default 60000 ms. */
+    censusCacheMs?: number;
+    /**
+     * Planning items. `store` is a test double. `mongoUri` keeps items in `{orgId}-memorix-assistants.planning_items`.
+     * Neither means planning routes are `501 CAPABILITY_UNAVAILABLE`.
+     */
+    planning?: {
+        store?: PlanningStore;
+        mongoUri?: string;
+        /** Assignee options per org. Absent means only unassigned is valid. */
+        assignees?: Record<string, Array<{
+            id: string;
+            name: string;
+            kind?: string;
+        }>>;
+    };
     /** Listen port. Default `MEMORIX_CLIENT_API_PORT` or 5120. */
     port?: number;
     /**
@@ -24,8 +48,9 @@ export type ClientApiOptions = {
      */
     mgcMcpUrl?: string | null;
     /**
-     * Scoper 2.3.0 hosted in this process. The library default is the scripted reasoner
-     * and no saved functions. The CLI passes the process env.
+     * Scoper 3.0.0 hosted in this process, or a peer chosen at startup. The library default is the
+     * scripted reasoner and no saved functions. The CLI passes the process env.
+     * The Scoper packages are loaded only when this process hosts Scoper.
      */
     scoper?: {
         reasoner?: ScoperReasonerKind;

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,eAAe,EAAuB,MAAM,SAAS,CAAC;AAW7E,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAStE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAkD,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChH,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAQrB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAE1F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,kBAAkB,CAAC;QAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;QACxB,2EAA2E;QAC3E,IAAI,CAAC,EAAE,UAAU,CAAC;QAClB,mEAAmE;QACnE,IAAI,CAAC,EAAE,UAAU,CAAC;QAClB,8CAA8C;QAC9C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;QACzB,0FAA0F;QAC1F,UAAU,CAAC,EAAE,OAAO,gBAAgB,CAAC;KACtC,CAAC;IACF;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,UAAU,CAAC;QAClB,IAAI,CAAC,EAAE,UAAU,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,qBAAqB,CAAC,cAAc,CAAC,CAAC;KACtD,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAsH3D,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAoUnF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import Fastify from "fastify";
 import { attachCoreFastify } from "@x12i/core-service/fastify";
-import { catalogFromKinds, findContentType, findObjectType, } from "./catalog.js";
+import { catalogFromKinds, findContentType, findObjectType, isConflicted, } from "./catalog.js";
 import { contentTypeIsDerived } from "./derived.js";
 import { resolveApiPort } from "./config.js";
 import { ApiError, UpstreamError } from "./errors.js";
@@ -12,14 +12,22 @@ import { clientApiLiveRing, memorixFetch } from "./live.js";
 import { withClientApiLiveNav } from "./live-ops-nav.js";
 import { registerProcessedRoutes } from "./processed.js";
 import { projectContents } from "./project.js";
-import { collectReferenceTargets, loadResolvedReferences, mergeReferenceTargets } from "./refs.js";
+import { collectReferenceTargets, loadResolvedReferences, mergeReferenceTargets, } from "./refs.js";
 import { registerReadsLive } from "./reads-live-routes.js";
-import { createScoperHost, createExternalScoperHost, registerScoperRoutes } from "./scoper.js";
+import { createExternalScoperHost, registerScoperRoutes } from "./scoper.js";
 import { createEmbeddedSkillsHost, createExternalSkillsHost, registerSkillRoutes, } from "./skills.js";
 import { attachRequestCountex, registerRequestStatsRoute } from "./request-countex.js";
 import { registerRefRoutes } from "./shaped-refs.js";
-import { orgFromToken, scopeBody, scopeFromHeaders } from "./scope.js";
+import { orgFromToken, resolveAgentSelection, scopeBody, scopeFromHeaders, } from "./scope.js";
 import { asRecord, createUpstream, subjectDirectoryPath } from "./upstream.js";
+import { createAgentDirectory } from "./agent-directory.js";
+import { defaultRetryable } from "./errors.js";
+import { createCensusService } from "./v1/census.js";
+import { stateOf } from "./v1/context.js";
+import { decodeSegments, rawPathAfter, requestIdFrom } from "./v1/http.js";
+import { createMongoPlanningStore } from "./v1/planning-store.js";
+import { registerV1Routes } from "./v1/routes.js";
+import { recordsListExtras, refsModeOf, wrapReferenceStatus } from "./v1/records.js";
 const openApiPath = resolve(dirname(fileURLToPath(import.meta.url)), "../openapi/openapi.json");
 function queryOf(req) {
     return (req.query ?? {});
@@ -62,6 +70,22 @@ function wildcard(req) {
     const params = req.params;
     return (params["*"] ?? params.path ?? "").trim();
 }
+function assertResolved(objectType) {
+    if (!isConflicted(objectType))
+        return;
+    const agents = (objectType.alternates ?? []).map((alt) => alt.definedByAgentId).join(", ");
+    throw new ApiError(409, "METADATA_CONFLICT", `Agents ${agents} define object type ${objectType.id} differently. Select one of them, or read the bodies on metadata/kinds/object-types.`);
+}
+function withReferenceStatus(contents, fieldMap, resolved, attempted) {
+    const out = {};
+    for (const [contentType, list] of Object.entries(contents)) {
+        const fields = fieldMap.get(contentType) ?? [];
+        out[contentType] = list.map((instance) => instance.json
+            ? { ...instance, json: { data: wrapReferenceStatus(instance.json.data, fields, resolved, attempted) } }
+            : instance);
+    }
+    return out;
+}
 function fieldsByType(objectType, contentTypes) {
     const map = new Map();
     for (const contentType of contentTypes) {
@@ -74,9 +98,19 @@ async function projectRead(upstream, scope, catalog, contents, fieldMap, represe
     const resolved = await loadResolvedReferences(upstream, scope, catalog, targets);
     return projectContents(contents, fieldMap, representation, shape, resolved);
 }
-async function loadCatalog(upstream, scope) {
+async function loadObjectTypeKinds(upstream, scope) {
     const body = await upstream.get("/api/metadata/kinds/object-types", scope);
-    return catalogFromKinds(body);
+    const items = asRecord(body)?.items;
+    return {
+        items: Array.isArray(items)
+            ? items.filter((item) => asRecord(item) !== null)
+            : [],
+        objectTypes: catalogFromKinds(body),
+        readAt: new Date().toISOString(),
+    };
+}
+async function loadCatalog(upstream, scope) {
+    return (await loadObjectTypeKinds(upstream, scope)).objectTypes;
 }
 async function loadSubject(upstream, scope, recordId) {
     const body = asRecord(await upstream.get(subjectDirectoryPath(recordId), scope));
@@ -114,14 +148,27 @@ function bearerToken(headerValue) {
     const match = /^Bearer\s+(\S+)\s*$/i.exec(raw.trim());
     return match?.[1] ?? "";
 }
+async function loadEmbeddedScoper() {
+    try {
+        return (await import("./scoper-embedded.js")).createScoperHost;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Scoper cannot be hosted in this process (${message}). Set SCOPER_URL to a Scoper peer and SCOPER_MODE=external, or install @x12i/memorix-scoper.`);
+    }
+}
 export async function createClientApi(options) {
-    const upstream = createUpstream(options.memorixUrl, options.fetchImpl ?? memorixFetch);
+    const upstream = createUpstream(options.memorixUrl, options.fetchImpl ?? memorixFetch, options.upstreamTimeoutMs);
     const auth = options.auth ?? { mode: "header" };
+    const directory = options.agentDirectory ?? createAgentDirectory(upstream, options.agentCacheMs);
+    const census = createCensusService(upstream, options.censusCacheMs);
+    const planning = options.planning?.store ??
+        (options.planning?.mongoUri ? createMongoPlanningStore(options.planning.mongoUri) : null);
     const scoperPeer = options.scoper?.peer;
     const scoperHost = options.scoper?.host ??
         (scoperPeer?.mode === "external"
             ? createExternalScoperHost(scoperPeer, options.scoper?.fetchImpl ?? fetch)
-            : await (options.scoper?.createHost ?? createScoperHost)({
+            : await (options.scoper?.createHost ?? (await loadEmbeddedScoper()))({
                 memorixUrl: options.memorixUrl,
                 reasoner: options.scoper?.reasoner ?? "scripted",
                 functionsDir: options.scoper?.functionsDir,
@@ -151,29 +198,35 @@ export async function createClientApi(options) {
         disableRequestLogging: true,
     });
     app.addHook("onRequest", async (req, reply) => {
+        const requestId = requestIdFrom(req.headers["x-request-id"]);
+        stateOf(req).requestId = requestId;
+        reply.header("x-request-id", requestId);
         const origin = req.headers.origin;
         if (typeof origin === "string" && origin) {
             reply.header("access-control-allow-origin", origin);
             reply.header("vary", "Origin");
-            reply.header("access-control-allow-headers", "content-type, authorization, x-memorix-org-id, x-memorix-agent-ids, x-memorix-caller, x-trace-id");
-            reply.header("access-control-allow-methods", "GET, POST, PUT, DELETE, OPTIONS");
+            reply.header("access-control-allow-headers", "content-type, authorization, x-memorix-org-id, x-memorix-agent-ids, x-memorix-caller, x-trace-id, x-request-id, if-match, if-none-match");
+            reply.header("access-control-allow-methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+            reply.header("access-control-expose-headers", "etag, x-request-id, retry-after");
         }
         if (req.method === "OPTIONS") {
             await reply.code(204).send();
         }
     });
-    async function scopeFor(req) {
+    async function verifiedClaims(req) {
+        const state = stateOf(req);
+        if (state.clientClaims !== undefined)
+            return state.clientClaims;
         if (auth.mode === "header") {
-            const scope = scopeFromHeaders(req.headers);
-            req.clientScope = scope;
-            return scope;
+            state.clientClaims = null;
+            return null;
         }
         const token = bearerToken(req.headers.authorization);
         if (!token)
             throw new ApiError(401, "UNAUTHORIZED", "Authorization bearer token is required");
-        let organizationIds;
+        let claims;
         try {
-            organizationIds = (await auth.verify(token)).organizationIds;
+            claims = await auth.verify(token);
         }
         catch (err) {
             if (err instanceof ApiError)
@@ -181,24 +234,91 @@ export async function createClientApi(options) {
             const message = err instanceof Error ? err.message : "invalid token";
             throw new ApiError(401, "UNAUTHORIZED", message);
         }
-        const requested = req.headers["x-memorix-org-id"];
-        const requestedOrg = (Array.isArray(requested) ? requested[0] : requested)?.trim() ?? "";
-        const scope = scopeFromHeaders(req.headers, orgFromToken(organizationIds, requestedOrg));
-        req.clientScope = scope;
+        state.clientClaims = claims;
+        return claims;
+    }
+    async function authenticate(req) {
+        const claims = await verifiedClaims(req);
+        const raw = req.headers["x-memorix-caller"];
+        const caller = (Array.isArray(raw) ? raw[0] : raw)?.trim() ?? "";
+        if (!caller)
+            throw new ApiError(400, "SCOPE_INVALID", "x-memorix-caller is required");
+        return { claims, caller };
+    }
+    async function scopeFor(req, scopeOptions = {}) {
+        const agents = scopeOptions.agents ?? "required";
+        const claims = await verifiedClaims(req);
+        let base;
+        if (!claims) {
+            base = scopeFromHeaders(req.headers, undefined, agents);
+        }
+        else {
+            const requested = req.headers["x-memorix-org-id"];
+            const requestedOrg = (Array.isArray(requested) ? requested[0] : requested)?.trim() ?? "";
+            base = scopeFromHeaders(req.headers, orgFromToken(claims.organizationIds, requestedOrg), agents);
+        }
+        const scope = await resolveAgentSelection(base, directory, agents);
+        stateOf(req).clientScope = scope;
         return scope;
     }
-    app.setErrorHandler((err, _req, reply) => {
+    app.setErrorHandler((err, req, reply) => {
+        const requestId = stateOf(req).requestId;
         if (err instanceof ApiError) {
+            for (const [name, value] of Object.entries(err.extra.headers ?? {}))
+                reply.header(name, value);
             return reply.status(err.statusCode).send({
-                error: { code: err.code, message: err.message },
+                error: {
+                    code: err.code,
+                    message: err.message,
+                    requestId,
+                    retryable: err.extra.retryable ?? defaultRetryable(err.statusCode),
+                    ...(err.extra.feature ? { feature: err.extra.feature } : {}),
+                    ...(err.extra.details ? { details: err.extra.details } : {}),
+                    ...(err.extra.current !== undefined ? { current: err.extra.current } : {}),
+                },
             });
         }
         if (err instanceof UpstreamError) {
-            return reply.status(err.statusCode).send(err.body ?? { error: { code: "UPSTREAM", message: err.message } });
+            if (err.statusCode === 429) {
+                if (err.retryAfter)
+                    reply.header("retry-after", err.retryAfter);
+                return reply.status(429).send({
+                    error: { code: "UPSTREAM_RATE_LIMITED", message: "Memorix limited the call", requestId, retryable: true },
+                });
+            }
+            const body = asRecord(err.body);
+            const error = asRecord(body?.error);
+            if (body && error) {
+                return reply.status(err.statusCode).send({
+                    ...body,
+                    error: {
+                        ...error,
+                        requestId,
+                        retryable: typeof error.retryable === "boolean" ? error.retryable : defaultRetryable(err.statusCode),
+                    },
+                });
+            }
+            return reply.status(err.statusCode).send(err.body ?? {
+                error: { code: "UPSTREAM", message: err.message, requestId, retryable: defaultRetryable(err.statusCode) },
+            });
         }
+        const statusCode = err.statusCode;
         const message = err instanceof Error ? err.message : String(err);
-        return reply.status(500).send({ error: { code: "INTERNAL", message } });
+        if (typeof statusCode === "number" && statusCode >= 400 && statusCode < 500) {
+            return reply.status(statusCode).send({
+                error: { code: statusCode === 404 ? "NOT_FOUND" : "VALIDATION", message, requestId, retryable: false },
+            });
+        }
+        return reply.status(500).send({ error: { code: "INTERNAL", message, requestId, retryable: false } });
     });
+    app.setNotFoundHandler((req, reply) => reply.status(404).send({
+        error: {
+            code: "NOT_FOUND",
+            message: `No route ${req.method} ${req.url.split("?")[0]}`,
+            requestId: stateOf(req).requestId,
+            retryable: false,
+        },
+    }));
     const core = await attachCoreFastify(app, {
         // 5120 is outside the memorix zone, so the published port is passed in.
         port: options.port ?? resolveApiPort(),
@@ -276,6 +396,7 @@ export async function createClientApi(options) {
         const objectType = findObjectType(await loadCatalog(upstream, scope), id);
         if (!objectType)
             throw new ApiError(404, "READ_NOT_FOUND", `Unknown object type ${id}`);
+        assertResolved(objectType);
         const view = findContentType(objectType, contentType);
         if (!view)
             throw new ApiError(404, "READ_NOT_FOUND", `Unknown content type ${contentType}`);
@@ -289,6 +410,7 @@ export async function createClientApi(options) {
         const objectType = findObjectType(catalog, id);
         if (!objectType)
             throw new ApiError(404, "READ_NOT_FOUND", `Unknown object type ${id}`);
+        assertResolved(objectType);
         const leadingContentType = typeof query.leadingContentType === "string" && query.leadingContentType.trim()
             ? query.leadingContentType.trim()
             : objectType.leadingContentType;
@@ -316,6 +438,7 @@ export async function createClientApi(options) {
         const pageInfo = asRecord(listed?.pageInfo);
         const shape = representation === "json" ? "data" : "envelope";
         const fieldMap = fieldsByType(objectType, contentTypes);
+        const refs = refsModeOf(query.refs, "expand");
         const rows = items.map((item) => {
             const row = asRecord(item);
             return {
@@ -326,7 +449,16 @@ export async function createClientApi(options) {
         const targets = new Map();
         for (const row of rows)
             mergeReferenceTargets(targets, collectReferenceTargets(row.contents, fieldMap, shape));
-        const resolved = await loadResolvedReferences(upstream, scope, catalog, targets);
+        const attempted = new Set();
+        const resolved = await loadResolvedReferences(upstream, scope, catalog, targets, attempted);
+        const nextCursor = typeof pageInfo?.nextCursor === "string" && pageInfo.nextCursor ? pageInfo.nextCursor : null;
+        const extras = recordsListExtras(id, nextCursor, census.peek(scope));
+        const projected = rows.map((row) => ({
+            recordId: row.recordId,
+            contents: refs === "status"
+                ? withReferenceStatus(projectContents(row.contents, fieldMap, representation, shape), fieldMap, resolved, attempted)
+                : projectContents(row.contents, fieldMap, representation, shape, resolved),
+        }));
         return {
             scope: scopeBody(scope),
             objectType: id,
@@ -334,21 +466,29 @@ export async function createClientApi(options) {
             leadingSource: query.leadingContentType && String(query.leadingContentType).trim()
                 ? "request"
                 : objectType.leadingSource,
-            items: rows.map((row) => ({
+            total: extras.total,
+            totalStatus: extras.totalStatus,
+            truncated: false,
+            records: projected.map((row) => ({
                 recordId: row.recordId,
-                contents: projectContents(row.contents, fieldMap, representation, shape, resolved),
+                objectType: id,
+                dataCategory: objectType.dataCategory,
+                contentTypes: Object.keys(row.contents),
+                instances: Object.entries(row.contents).flatMap(([contentType, list]) => list.map((instance) => ({ contentType, ...instance }))),
             })),
+            items: projected,
             pageInfo: {
-                nextCursor: typeof pageInfo?.nextCursor === "string" ? pageInfo.nextCursor : null,
+                complete: extras.complete,
+                nextCursor,
                 limit: typeof pageInfo?.limit === "number" ? pageInfo.limit : limit,
             },
         };
     });
     app.get("/api/v1/records/*", async (req) => {
         const scope = await scopeFor(req);
-        const raw = wildcard(req);
-        const catalogOnly = raw.endsWith("/content-types");
-        const recordId = (catalogOnly ? raw.slice(0, -"/content-types".length) : raw).replace(/\/$/, "");
+        const rawPath = rawPathAfter(req, "/api/v1/records/") ?? wildcard(req);
+        const catalogOnly = rawPath.endsWith("/content-types");
+        const recordId = decodeSegments((catalogOnly ? rawPath.slice(0, -"/content-types".length) : rawPath).replace(/\/$/, ""));
         if (!recordId)
             throw new ApiError(400, "VALIDATION", "recordId required");
         const subject = await loadSubject(upstream, scope, recordId);
@@ -358,20 +498,31 @@ export async function createClientApi(options) {
         }
         const catalog = await loadCatalog(upstream, scope);
         const objectType = findObjectType(catalog, subject.objectType);
+        const storedTypes = subject.contentTypes.filter((ct) => ct !== "relationships");
+        const status = storedTypes.length === 0 ? "directory-only" : "stored";
         if (catalogOnly) {
+            const stored = new Set(subject.contentTypes);
             return {
                 scope: scopeBody(scope),
                 recordId: subject.recordId,
                 objectType: subject.objectType,
                 dataCategory: subject.dataCategory,
+                status,
                 leadingContentType: objectType?.leadingContentType ?? null,
                 leadingSource: objectType?.leadingSource ?? "default",
-                contentTypes: contentTypeViews(objectType, subject.contentTypes),
+                contentTypes: contentTypeViews(objectType, subject.contentTypes).map((view) => ({
+                    ...view,
+                    presence: "stored",
+                })),
+                declaredAbsent: (objectType?.contentTypes ?? [])
+                    .filter((view) => !stored.has(view.id) && view.id !== "relationships")
+                    .map((view) => ({ ...view, presence: "declared-absent" })),
             };
         }
         const requested = csv(query.contentTypes);
         const contentTypes = (requested ?? subject.contentTypes).filter((ct) => ct !== "relationships");
         const representation = representationOf(query.representation);
+        const refs = refsModeOf(query.refs, "expand");
         let contents = {};
         let dataCategory = subject.dataCategory;
         if (contentTypes.length > 0) {
@@ -386,15 +537,51 @@ export async function createClientApi(options) {
             const composition = asRecord(composed?.composition);
             contents = asRecord(composition?.contents);
         }
+        const fieldMap = fieldsByType(objectType, contentTypes);
+        let projected;
+        if (refs === "status") {
+            const attempted = new Set();
+            const resolved = await loadResolvedReferences(upstream, scope, catalog, collectReferenceTargets(contents, fieldMap, "record"), attempted);
+            projected = withReferenceStatus(projectContents(contents, fieldMap, representation, "record"), fieldMap, resolved, attempted);
+        }
+        else {
+            projected = await projectRead(upstream, scope, catalog, contents, fieldMap, representation, "record");
+        }
         return {
             scope: scopeBody(scope),
             recordId: subject.recordId,
             objectType: subject.objectType,
+            ...(objectType && isConflicted(objectType) ? { objectTypeResolution: "conflict" } : {}),
             dataCategory,
+            status,
             contentTypes,
-            contents: await projectRead(upstream, scope, catalog, contents, fieldsByType(objectType, contentTypes), representation, "record"),
+            contents: projected,
+            ...(status === "directory-only" ? { instances: [] } : {}),
         };
     });
+    const memorixBase = options.memorixUrl.replace(/\/+$/, "");
+    const probeFetch = options.fetchImpl ?? memorixFetch;
+    registerV1Routes(app, {
+        upstream,
+        directory,
+        census,
+        planning,
+        authMode: auth.mode,
+        scopeFor,
+        authenticate,
+        loadCatalog,
+        loadObjectTypeKinds,
+        assignees: (orgId) => options.planning?.assignees?.[orgId] ?? null,
+        probeMemorix: async () => {
+            try {
+                const res = await probeFetch(`${memorixBase}/health`, { signal: AbortSignal.timeout(3000) });
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+    });
     registerProcessedRoutes(app, { upstream, scopeFor, loadCatalog });
     registerRefRoutes(app, { upstream, scopeFor, loadCatalog });
     registerFetchRoutes(app, {