@m6d/cortex-cli 0.2.0 → 0.4.0

package/src/contracts/wire/index.ts

@@ -32,9 +32,11 @@ export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
 export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
 
 export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
 
 /** Who put the file in the thread: the user through the composer, or a tool mid-turn. */
 export const ATTACHMENT_ORIGINS = ["upload", "tool"] as const;
+export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
 
 export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
     if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
@@ -42,10 +44,6 @@ export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
     return "ok";
 }
 
-export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
-
-export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
-
 export type AttachmentSummary = {
     id: string;
     filename: string;
@@ -190,7 +188,7 @@ export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
  * parked client tool calls on a continuation request. The server owns the
  * transcript (a continuation sends `messages: []`), so the answered assistant
  * message itself never crosses the wire — the SDK's park-boundary snapshot
- * does not preserve its id, and round-tripping it duplicated the stored
+ * does not preserve its id, and round-tripping it would duplicate the stored
  * message.
  */
 export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
@@ -206,6 +204,15 @@ export type ClientToolAnswer = {
     state: "complete" | "error" | "approved" | "denied";
 };
 
+/**
+ * The id a parked tool call's decision is filed under: the one on its
+ * approval record, or `approval_<toolCallId>`, which is how the SDK names
+ * every approval it requests, for a part that carries no record.
+ */
+export function approvalIdOf(part: { id: string; approval?: { id: string } }) {
+    return part.approval?.id ?? `approval_${part.id}`;
+}
+
 /**
  * Response of `POST /chat/:threadId/tools/:toolCallId/initiate`. `embed:
  * false` means the pending call is not a CC client tool — the widget

package/src/graph/expand-domains.ts

@@ -84,12 +84,12 @@ export function expandDomains(domains: Record<string, DomainDef>) {
 }
 
 function createOwnershipMaps(domains: Record<string, DomainDef>) {
-    const ownership: OwnershipMaps = {
+    const ownership = {
         concepts: new WeakMap<ConceptDef, string>(),
         endpoints: new WeakMap<EndpointDef, string>(),
         services: new WeakMap<ServiceDef, string>(),
         rules: new WeakMap<RuleDef, string>(),
-    };
+    } satisfies OwnershipMaps;
 
     for (const [domainKey, domain] of Object.entries(domains)) {
         for (const concept of domain.concepts ?? []) {
@@ -138,7 +138,7 @@ function includeConcept(options: {
     const { domainKey, concept, ownership, collections, pendingConcepts, pendingEndpoints } =
         options;
 
-    includeRule(domainKey, concept.governedBy ?? [], ownership, collections);
+    includeRules(domainKey, concept.governedBy ?? [], ownership, collections);
 
     if (shouldAttach(ownership.concepts, concept, domainKey)) {
         pushUnique(collections.concepts, concept);
@@ -182,7 +182,7 @@ function includeEndpoint(options: {
         pushUnique(collections.endpoints, endpoint);
     }
 
-    includeRule(domainKey, endpoint.governedBy ?? [], ownership, collections);
+    includeRules(domainKey, endpoint.governedBy ?? [], ownership, collections);
 
     // An endpoint reaches concepts three ways and other endpoints one way, but the
     // handling is identical: take what this domain owns, and queue whatever is new.
@@ -240,7 +240,7 @@ function includeService(options: {
         pushUnique(collections.services, service);
     }
 
-    includeRule(domainKey, service.governedBy ?? [], ownership, collections);
+    includeRules(domainKey, service.governedBy ?? [], ownership, collections);
 
     if (
         shouldAttach(ownership.concepts, service.belongsTo, domainKey) &&
@@ -250,7 +250,7 @@ function includeService(options: {
     }
 }
 
-function includeRule(
+function includeRules(
     domainKey: string,
     rules: readonly RuleDef[],
     ownership: OwnershipMaps,
@@ -281,8 +281,6 @@ function referencesConcept(endpoint: EndpointDef, concept: ConceptDef) {
     return (
         endpoint.queries?.includes(concept) ||
         endpoint.mutates?.includes(concept) ||
-        endpoint.returns?.some(function (returned) {
-            return returned.concept === concept;
-        })
+        endpoint.returns?.some((returned) => returned.concept === concept)
     );
 }

package/src/graph/generate-cypher.ts

@@ -24,7 +24,7 @@ import type {
     ServiceDef,
 } from "@cortex/contracts/graph";
 
-export type GeneratedCypher = {
+type GeneratedCypher = {
     nodes: string[];
     edges: string[];
 };

package/src/graph/seed.ts

@@ -12,7 +12,7 @@ import {
 } from "@cortex/contracts/graph";
 
 import { expandDomains } from "./expand-domains";
-import { generateCypher, type GeneratedCypher } from "./generate-cypher";
+import { generateCypher } from "./generate-cypher";
 import { validateDomain } from "./validate";
 
 type SeedEmbedding = {
@@ -95,7 +95,6 @@ async function generateEmbeddings(
     embeddingConfig: SeedEmbedding,
     s: GraphSchema,
 ) {
-    // 1. Create the vector index (idempotent)
     await client.query(
         `CREATE VECTOR INDEX ${s.conceptEmbeddingsIndex} IF NOT EXISTS
          FOR (c:${s.label.concept}) ON (c.${s.prop.embedding})
@@ -105,7 +104,6 @@ async function generateEmbeddings(
          }}`,
     );
 
-    // 2. Fetch all concepts
     const concepts = (await client.query(
         `MATCH (c:${s.label.concept}) RETURN c.${s.prop.name} AS name, c.${s.prop.description} AS description`,
     )) as { name: string; description: string }[];
@@ -114,10 +112,8 @@ async function generateEmbeddings(
         return { concepts: 0, dimension: embeddingConfig.dimension };
     }
 
-    // 3. Generate embeddings for every concept in one request
     const embeddings = await embeddingConfig.embed(concepts.map((c) => c.description));
 
-    // 4. Store the embeddings in the graph
     await Promise.all(
         concepts.map((concept, idx) =>
             client.query(
@@ -134,7 +130,6 @@ async function generateEmbeddings(
 export async function seedGraph(config: SeedGraphConfig, domains: Record<string, DomainDef>) {
     const expandedDomains = expandDomains(domains);
 
-    // Validate all domains
     const validationErrors = Object.entries(expandedDomains).flatMap(([name, domain]) =>
         validateDomain(domain).map((err) => `[${name}] ${err}`),
     );
@@ -148,11 +143,9 @@ export async function seedGraph(config: SeedGraphConfig, domains: Record<string,
     const client = config.neo4j;
     const targets = Object.entries(expandedDomains);
 
-    // Generate Cypher for all target domains
-    const allCypher: [string, GeneratedCypher][] = targets.map(([name, data]) => [
-        name,
-        generateCypher(data, config.schema),
-    ]);
+    const allCypher = targets.map(
+        ([name, data]) => [name, generateCypher(data, config.schema)] as const,
+    );
 
     // Stamped before anything else is written, so an interrupted seed still
     // leaves the graph labelled with the schema it was written against.
@@ -169,10 +162,9 @@ export async function seedGraph(config: SeedGraphConfig, domains: Record<string,
     const allEdges = allCypher.flatMap(([domain, c]) => tag(domain, c.edges));
     const edges = await runPhase(client, allEdges);
 
-    // Embeddings for every concept.
     const embeddings = await generateEmbeddings(client, config.embedding, config.schema);
 
-    const domainResults: Record<string, DomainSeedResult> = Object.fromEntries(
+    const domainResults = Object.fromEntries(
         targets.map(([name]) => {
             const failures = [
                 ...(nodes.failures.get(name) ?? []),
@@ -185,7 +177,7 @@ export async function seedGraph(config: SeedGraphConfig, domains: Record<string,
                     edges: edges.succeeded.get(name) ?? 0,
                     failed: failures.length,
                     failures,
-                },
+                } satisfies DomainSeedResult,
             ];
         }),
     );

package/src/scaffold/files.ts

@@ -27,7 +27,7 @@ export type Database = "postgres" | "mssql";
 // sync (scripts/sync-package-versions.ts) restamps it and files.test.ts holds
 // them to that.
 export const DEPENDENCIES = {
-    "@m6d/cortex-server": "~0.2.0",
+    "@m6d/cortex-server": "~0.4.0",
     "@tanstack/ai": "^0.55.0",
     "@tanstack/ai-openai": "^0.22.8",
     hono: "^4.12.3",
@@ -50,10 +50,10 @@ const DEV_DEPENDENCIES = {
 
 // Postgres is the one we run, so it gets a scaffolded port. MSSQL is normally an
 // existing instance nobody moved, which is why it keeps 1433 and has no service.
-const CONNECTION_STRING: Record<Database, string> = {
+const CONNECTION_STRING = {
     postgres: "postgres://postgres:postgres@localhost:{{port.postgres}}/cortex",
     mssql: "Server=localhost,1433;Database=cortex;User Id=sa;Password=your-password;Encrypt=false",
-};
+} satisfies Record<Database, string>;
 
 function packageJson(name: string) {
     return `${JSON.stringify(
@@ -89,7 +89,7 @@ function packageJson(name: string) {
  * defaulted, and the other two are what you reach for once a real problem shows
  * up — noisy graph retrieval, a cheap-model path — not on day one.
  */
-const NEVER_SCAFFOLDED: [note: string, config: string][] = [
+const NEVER_SCAFFOLDED = [
     [
         "A cheaper, faster model for auxiliary passes. Same shape as `model`.",
         `fastModel: {
@@ -112,7 +112,7 @@ const NEVER_SCAFFOLDED: [note: string, config: string][] = [
     recentMessagesToKeep: 6,
 },`,
     ],
-];
+] satisfies [note: string, config: string][];
 
 /** Fragments are authored at zero indentation and placed by these two. */
 function indented(block: string) {
@@ -132,9 +132,7 @@ function cortexConfig(database: Database, features: Feature[]) {
     const fragment = (feature: Feature) =>
         block(FEATURES[feature].note, FEATURES[feature].config, features.includes(feature));
 
-    const on = FEATURE_NAMES.filter((feature) => features.includes(feature))
-        .map(fragment)
-        .join("");
+    const on = features.map(fragment).join("");
     const off = FEATURE_NAMES.filter((feature) => !features.includes(feature))
         .map(fragment)
         .join("");
@@ -167,9 +165,10 @@ ${on === "" ? "" : `${on}\n`}    agents: {
         assistant: defineAgent({
             systemPrompt: "You are a helpful assistant.",
             // Applications that serve datasets for grouped questions (see the
-            // README's "Dataset hosts"): the host applies its own access rules,
-            // the agent only picks which datasets to expose and pin.
-            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", pinned: ["orders"] }],
+            // README's "Dataset hosts"): the host applies its own access rules
+            // under the run's token the list below forwards, the agent only
+            // picks which datasets to expose and pin.
+            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", credentials: [{ header: "X-End-User-Token", credential: { kind: "run-token" } }], pinned: ["orders"] }],
         }),
     },
 
@@ -191,9 +190,7 @@ function hasServices(database: Database, features: Feature[]) {
 }
 
 function env(database: Database, features: Feature[]) {
-    const blocks = FEATURE_NAMES.filter((feature) => features.includes(feature)).map(
-        (feature) => `\n${FEATURES[feature].env}\n`,
-    );
+    const blocks = features.map((feature) => `\n${FEATURES[feature].env}\n`);
 
     // Only the URLs pointing at scaffolded services carry a chosen port, and those
     // are exactly the ones docker-compose.yml publishes.
@@ -247,7 +244,7 @@ function dockerCompose(name: string, database: Database, features: Feature[]) {
         volumes.push("postgres-data");
     }
 
-    for (const feature of FEATURE_NAMES.filter((feature) => features.includes(feature))) {
+    for (const feature of features) {
         const { compose, volume } = FEATURES[feature];
         if (compose === undefined) continue;
         services.push(compose);
@@ -278,12 +275,6 @@ ${services.join("\n\n")}
 ${volumeBlock}`;
 }
 
-/**
- * `--knowledge` scaffolds the directory `domainsDir` defaults to, which is what
- * makes the convention true by construction: `cortex swagger sync` finds it with
- * no config key.
- */
-
 function cspellConfig() {
     return `${JSON.stringify(
         {
@@ -336,12 +327,10 @@ function cspellConfig() {
 }
 
 function readme(name: string, database: Database, features: Feature[], compose: boolean) {
-    const enabled = FEATURE_NAMES.filter((feature) => features.includes(feature));
-
     return `# ${name}
 
 A Cortex server: one agent, a ${database} database, and an OpenAI-compatible model.${
-        enabled.length === 0 ? "" : ` Also on: ${enabled.join(", ")}.`
+        features.length === 0 ? "" : ` Also on: ${features.join(", ")}.`
     }
 
 ## Getting started
@@ -381,12 +370,16 @@ pre-commit hook or CI job should run. Each is also available on its own: \`forma
 `;
 }
 
-/** Relative path → contents. Nothing here touches the filesystem. */
-export function scaffoldFiles(name: string, database: Database, features: Feature[], ports: Ports) {
+/**
+ * Relative path → contents. Nothing here touches the filesystem. Every
+ * generator lists features in catalogue order, whatever order they came in.
+ */
+export function scaffoldFiles(name: string, database: Database, selected: Feature[], ports: Ports) {
+    const features = FEATURE_NAMES.filter((feature) => selected.includes(feature));
     const envFile = env(database, features);
     const compose = dockerCompose(name, database, features);
 
-    const files: Record<string, string> = {
+    const files = {
         "cortex.config.ts": cortexConfig(database, features),
         "index.ts": indexTs,
         "package.json": packageJson(name),
@@ -400,8 +393,10 @@ export function scaffoldFiles(name: string, database: Database, features: Featur
         "cspell.json": cspellConfig(),
         ".fallowrc.jsonc": fallowrc,
         ...(compose === undefined ? {} : { "docker-compose.yml": compose }),
+        // The directory `domainsDir` defaults to, which makes the convention true
+        // by construction: `cortex swagger sync` finds it with no config key.
         ...(features.includes("knowledge") ? { "src/domains/README.md": domainsReadme } : {}),
-    };
+    } satisfies Record<string, string>;
 
     // One pass at the end, over everything: no generator holds a port number of
     // its own, so compose, .env and the README cannot disagree about one.

package/src/swagger/extract-endpoints.ts

@@ -1,31 +1,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Endpoint, HttpMethod, Prop } from "./types";
-import {
-    dedupe,
-    deref,
-    isObj,
-    obj,
-    pickContent,
-    schemaType,
-    toProp,
-    toProps,
-} from "./openapi-schema";
+import { isRecord } from "@cortex/contracts/json";
+import type { Endpoint, HttpMethod, Obj } from "./types";
+import { dedupe, deref, obj, pickContent, schemaType, toProp, toProps } from "./openapi-schema";
 import { parseResponse } from "./parse-response";
 import { withGeneratedBlock } from "./generated-block";
 
 type ExtractEndpointsOptions = {
     swaggerUrls: string[];
     domainsDir: string;
-    write?: boolean;
+    write: boolean;
 };
 
-const METHODS: Array<[string, HttpMethod]> = [
-    ["get", "GET"],
-    ["post", "POST"],
-    ["put", "PUT"],
-    ["delete", "DELETE"],
-];
+const METHODS = ["GET", "POST", "PUT", "DELETE"] as const satisfies readonly HttpMethod[];
 
 /**
  * ASP.NET conventions the extractor normalizes away so an `.endpoint.ts` path
@@ -44,78 +31,89 @@ function toCamelCase(s: string) {
         .join(".");
 }
 
+/** `Root` for a dotted parameter like `Root.Options`; undefined for a plain one. */
+function dottedRoot(name: string) {
+    const dot = name.indexOf(".");
+    return dot < 0 ? undefined : name.slice(0, dot);
+}
+
 function normalizePath(raw: string) {
     let p = raw.startsWith("/") ? raw : `/${raw}`;
     p = p.replace(/\{([^}:?]+)(?::[^}]+)?\??\}/g, "{$1}").replace(API_PREFIX, "") || "/";
     return p.length > 1 ? p.replace(/\/+$/, "") : p;
 }
 
-function walkFiles(dir: string, accept: (filePath: string) => boolean) {
+function walkFiles(dir: string) {
     if (!fs.existsSync(dir)) return [];
     const out: string[] = [];
     function walk(d: string) {
         for (const e of fs.readdirSync(d, { withFileTypes: true })) {
             const p = path.join(d, e.name);
             if (e.isDirectory()) walk(p);
-            else if (accept(p)) out.push(p);
+            else out.push(p);
         }
     }
     walk(dir);
     return out;
 }
 
+/**
+ * The `method` and `path` an endpoint file declares, read the way the server's
+ * own file walk reads them.
+ */
+export function declaredRoute(source: string) {
+    return {
+        method: source.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2],
+        path: source.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2],
+    };
+}
+
 function endpointFiles(root: string) {
     const out = new Map<string, string>();
-    for (const filePath of walkFiles(root, (p) => p.endsWith(".endpoint.ts"))) {
-        const c = fs.readFileSync(filePath, "utf8");
-        const method = c.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2];
-        const route = c.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2];
+    for (const filePath of walkFiles(root).filter((p) => p.endsWith(".endpoint.ts"))) {
+        const { method, path: route } = declaredRoute(fs.readFileSync(filePath, "utf8"));
         if (method && route) out.set(`${method}:${normalizePath(route)}`, filePath);
     }
     return out;
 }
 
-function extractEndpoint(
-    doc: unknown,
-    route: string,
-    method: HttpMethod,
-    pathItemIn: unknown,
-    operationIn: unknown,
-) {
-    const pathItem = obj(pathItemIn);
-    const operation = obj(operationIn);
-
+/**
+ * Path and query parameters, path-level first, with each `JsonNode` parameter
+ * collapsed back to one object.
+ */
+function extractParams(doc: unknown, pathItem: Obj, operation: Obj) {
     const rawParams = [
         ...(Array.isArray(pathItem.parameters) ? (pathItem.parameters as unknown[]) : []),
         ...(Array.isArray(operation.parameters) ? (operation.parameters as unknown[]) : []),
     ]
-        .map((x) => deref(doc, x))
-        .filter((x) => typeof x.in === "string" && ["path", "query"].includes(x.in))
-        .filter((x) => typeof x.name === "string");
+        .map((param) => deref(doc, param))
+        .filter(
+            (param): param is Obj & { name: string; in: string } =>
+                typeof param.name === "string" &&
+                typeof param.in === "string" &&
+                ["path", "query"].includes(param.in),
+        );
 
     const jsonNodeRoots = new Set<string>();
-    for (const x of rawParams) {
-        const name = String(x.name);
-        if (!name.includes(".")) continue;
-        const root = name.split(".")[0]!;
-        const rest = name.slice(root.length + 1);
-        if (JSON_NODE_MEMBER.test(rest)) jsonNodeRoots.add(root);
+    for (const { name } of rawParams) {
+        const root = dottedRoot(name);
+        if (root !== undefined && JSON_NODE_MEMBER.test(name.slice(root.length + 1))) {
+            jsonNodeRoots.add(root);
+        }
     }
 
-    const params = dedupe(
+    return dedupe(
         rawParams
-            .filter((x) => {
-                const name = String(x.name);
-                if (!name.includes(".")) return true;
-                const root = name.split(".")[0]!;
-                return !jsonNodeRoots.has(root);
+            .filter((param) => {
+                const root = dottedRoot(param.name);
+                return root === undefined || !jsonNodeRoots.has(root);
             })
-            .map((x) =>
+            .map((param) =>
                 toProp(
                     doc,
-                    toCamelCase(String(x.name)),
-                    x.schema,
-                    String(x.in) === "path" || x.required === true,
+                    toCamelCase(param.name),
+                    param.schema,
+                    param.in === "path" || param.required === true,
                 ),
             )
             .concat(
@@ -126,41 +124,46 @@ function extractEndpoint(
                 })),
             ),
     );
+}
 
-    const body: Prop[] = [];
+/** An object body contributes its own fields; anything else is one `items` or `body` field. */
+function extractBody(doc: unknown, operation: Obj) {
     const requestBody = deref(doc, operation.requestBody);
-    const requestContent = pickContent(requestBody.content);
-    if (requestContent) {
-        const s = deref(doc, requestContent.schema);
-        const t = schemaType(s);
-        if (t === "object") body.push(...toProps(doc, s));
-        else if (t === "array") body.push(toProp(doc, "items", s, requestBody.required === true));
-        else body.push(toProp(doc, "body", s, requestBody.required === true));
-    }
+    const content = pickContent(requestBody.content);
+    if (!content) return [];
+    const schema = deref(doc, content.schema);
+    const type = schemaType(schema);
+    if (type === "object") return toProps(doc, schema);
+    const name = type === "array" ? "items" : "body";
+    return [toProp(doc, name, schema, requestBody.required === true)];
+}
 
-    const parsed = parseResponse(doc, operation.responses);
+function extractEndpoint(
+    doc: unknown,
+    route: string,
+    method: HttpMethod,
+    pathItem: Obj,
+    operation: Obj,
+) {
     const normalizedPath = normalizePath(route);
-
     return {
         key: `${method}:${normalizedPath}`,
         method,
         path: normalizedPath,
-        params,
-        body: dedupe(body),
-        response: dedupe(parsed.response),
-        responseKind: parsed.responseKind,
-        successStatus: parsed.successStatus,
-        errorStatuses: parsed.errorStatuses,
+        params: extractParams(doc, pathItem, operation),
+        body: extractBody(doc, operation),
+        ...parseResponse(doc, operation.responses),
     } satisfies Endpoint;
 }
 
 function parseSwaggerEndpoints(swagger: unknown) {
     const out = new Map<string, Endpoint>();
     const doc = obj(swagger);
-    for (const [route, pathItem] of Object.entries(obj(doc.paths))) {
-        for (const [openApiMethod, method] of METHODS) {
-            const operation = obj(pathItem)[openApiMethod];
-            if (!isObj(operation)) continue;
+    for (const [route, pathItemIn] of Object.entries(obj(doc.paths))) {
+        const pathItem = obj(pathItemIn);
+        for (const method of METHODS) {
+            const operation = pathItem[method.toLowerCase()];
+            if (!isRecord(operation)) continue;
             const endpoint = extractEndpoint(doc, route, method, pathItem, operation);
             out.set(endpoint.key, endpoint);
         }
@@ -217,11 +220,11 @@ function sameModuloFormatting(a: string, b: string) {
 }
 
 export async function extractEndpoints(options: ExtractEndpointsOptions) {
-    const { swaggerUrls, domainsDir, write = false } = options;
+    const { swaggerUrls, domainsDir, write } = options;
 
     // Merge every document first: a file missing from one swagger doc may be
     // matched by another. Last write wins on duplicate keys, so per-agent docs
-    // deliberately override the server-level one (collectSwaggerUrls order).
+    // deliberately override the server-level one (`swaggerUrls` lists it first).
     const extracted = new Map<string, Endpoint>();
     for (const swaggerUrl of swaggerUrls) {
         for (const [key, endpoint] of parseSwaggerEndpoints(await fetchJson(swaggerUrl))) {

package/src/swagger/openapi-schema.ts

@@ -3,25 +3,27 @@
  * a schema into the flat property list the generator emits. Nothing here knows what
  * the properties are for.
  */
+import { isRecord } from "@cortex/contracts/json";
 import type { Obj, Prop } from "./types";
 
 const MAX_DEPTH = 8;
 
-export function isObj(v: unknown): v is Obj {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 export function obj(v: unknown) {
-    return isObj(v) ? v : {};
+    return isRecord(v) ? v : {};
 }
 
 function strings(v: unknown) {
     return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
 }
 
+/** The first prop of each name. */
 export function dedupe(items: Prop[]) {
     const seen = new Set<string>();
-    return items.filter((x) => (seen.has(x.name) ? false : (seen.add(x.name), true)));
+    return items.filter((prop) => {
+        if (seen.has(prop.name)) return false;
+        seen.add(prop.name);
+        return true;
+    });
 }
 
 function resolvePointer(doc: unknown, ref: string) {
@@ -29,14 +31,14 @@ function resolvePointer(doc: unknown, ref: string) {
     let cur: unknown = doc;
     for (const part of ref.slice(2).split("/")) {
         const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
-        if (!isObj(cur) || !(key in cur)) return null;
+        if (!isRecord(cur) || !(key in cur)) return null;
         cur = cur[key];
     }
     return cur;
 }
 
 export function deref(doc: unknown, v: unknown) {
-    if (!isObj(v)) return {};
+    if (!isRecord(v)) return {};
     let x = v;
     const seen = new Set<string>();
     while (typeof x.$ref === "string") {
@@ -52,14 +54,14 @@ export function schemaType(s: Obj) {
         ? (s.type as unknown[]).find((x) => typeof x === "string" && x !== "null")
         : s.type;
     if (typeof t === "string") return t;
-    if (isObj(s.properties)) return "object";
-    if (isObj(s.items)) return "array";
+    if (isRecord(s.properties)) return "object";
+    if (isRecord(s.items)) return "array";
     return "";
 }
 
 function isJsonNodeRef(v: unknown) {
     return (
-        isObj(v) &&
+        isRecord(v) &&
         typeof v.$ref === "string" &&
         /\/System\.Text\.Json\.Nodes\.JsonNode$/.test(v.$ref)
     );
@@ -149,13 +151,18 @@ export function toProp(
     return { name, required: req, type: scalarType(s) };
 }
 
+/**
+ * The schema under `application/json`, else any JSON type, else the first
+ * type, along with every type offered.
+ */
 export function pickContent(contentIn: unknown) {
     const content = obj(contentIn);
     const mimes = Object.keys(content);
-    if (!mimes.length) return null;
+    const [first] = mimes;
+    if (first === undefined) return null;
     const mime =
         mimes.find((x) => x.toLowerCase() === "application/json") ??
         mimes.find((x) => x.toLowerCase().includes("json")) ??
-        mimes[0];
-    return { schema: obj(content[mime!]).schema, mimes };
+        first;
+    return { schema: obj(content[mime]).schema, mimes };
 }