@m6d/cortex-cli 0.14.0 → 0.15.0

package/README.md

@@ -143,8 +143,16 @@ touched, and a name one of them holds fails the apply.
 cortex apply                             # ./cortex.manifest.ts
 cortex apply deploy/manifest.json --dry-run
 cortex apply -p prod
+cortex apply --prefer live               # keep every live edit the manifest also changed
 ```
 
+An entry's `overridable` lists the fields people may change in Cortex, such
+as an agent's `prompt`. An apply keeps those edits. When the manifest changes
+a field that was also edited live, `cortex apply` asks which to keep for
+each one. `--prefer live` or `--prefer manifest` answers them all. Without a
+terminal and without `--prefer`, the apply changes nothing and lists the
+conflicts; `--dry-run` marks each with `!`.
+
 The path defaults to exactly `./cortex.manifest.ts` in the directory you run
 in. TypeScript and JSON load the same way: the file's default export is the
 manifest. `defineManifest` from `@m6d/cortex` types one as you write it:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.14.0",
+    "version": "0.15.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",

package/src/commands/apply.ts

@@ -1,19 +1,38 @@
 import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 
+import { Option } from "@commander-js/extra-typings";
 import type { Command } from "@commander-js/extra-typings";
-import { appliedManifestSchema, manifestChangesSchema } from "@cortex/contracts/manifest";
+import { isRecord } from "@cortex/contracts/json";
+import {
+    appliedManifestSchema,
+    manifestApplyInputSchema,
+    manifestPreviewSchema,
+} from "@cortex/contracts/manifest";
 import { loadManifestFile } from "@cortex/contracts/manifest-file";
 import { z } from "zod";
 
-import { callManagement } from "@/management/client";
-import { callOrFail, requireProfile } from "@/commands/management";
+import { callManagement, ManagementError } from "@/management/client";
+import { failCall, requireProfile } from "@/commands/management";
+import { askChoice } from "@/ui/prompts";
 import * as report from "@/ui/report";
 
 // Discovery is this exact name in the cwd, with no upward walk, so the
 // argument's default is the discovery rule.
 export const DEFAULT_MANIFEST = "./cortex.manifest.ts";
 
+/** Which value a field both the manifest and a live write changed keeps. */
+const SIDES = manifestApplyInputSchema.shape.prefer.unwrap().options;
+type Side = (typeof SIDES)[number];
+type Resolution = z.input<typeof manifestApplyInputSchema>["resolutions"];
+type Conflict = z.infer<typeof manifestPreviewSchema>["conflicts"][number];
+
+/** A sync refused for fields both sides changed that nothing answered. */
+const unresolvedSchema = z.object({
+    error: z.literal("unresolved_conflicts"),
+    conflicts: manifestPreviewSchema.shape.conflicts,
+});
+
 const CHANGES = ["create", "update", "delete"] as const;
 const MARKS = { create: "+", update: "~", delete: "-" } satisfies Record<
     (typeof CHANGES)[number],
@@ -23,7 +42,9 @@ const MARKS = { create: "+", update: "~", delete: "-" } satisfies Record<
 /**
  * `cortex apply [path]`: makes Cortex match a manifest in one
  * transaction, through the management API with the profile's key.
- * `--dry-run` answers what would change and changes nothing.
+ * `--dry-run` answers what would change and changes nothing. A field both
+ * the manifest and a live edit in Cortex changed is asked about, unless
+ * `--prefer` answers every one.
  */
 export function registerApply(program: Command<[], { verbose?: true; profile?: string }>) {
     const command = program
@@ -31,7 +52,13 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
         .helpGroup("Cortex:")
         .description("Make Cortex match a manifest")
         .argument("[path]", "The manifest, TypeScript or JSON", DEFAULT_MANIFEST)
-        .option("--dry-run", "Show what would change, and change nothing");
+        .option("--dry-run", "Show what would change, and change nothing")
+        .addOption(
+            new Option(
+                "--prefer <side>",
+                "Keep the live or the manifest value of every field both changed, without asking",
+            ).choices(SIDES),
+        );
 
     command.action(async function (path, options) {
         const { verbose = false, profile: profileName } = program.opts();
@@ -43,15 +70,26 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
         report.input("Manifest", label(file));
         report.input("Cortex", profile.url);
 
-        const { changes, triggerSecrets } = await applyManifest({ profile, file, dryRun, verbose });
+        const { changes, triggerSecrets, conflicts } = await applyManifest({
+            profile,
+            file,
+            dryRun,
+            verbose,
+            prefer: options.prefer,
+            interactive: process.stdin.isTTY === true,
+        });
         const created = countNames(changes.create);
         const updated = countNames(changes.update);
         const deleted = countNames(changes.delete);
+        const conflicted =
+            conflicts.length > 0
+                ? `, ${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"}`
+                : "";
         report.footer(
-            created + updated + deleted === 0
+            created + updated + deleted + conflicts.length === 0
                 ? "no changes"
                 : dryRun
-                  ? `would create ${created}, update ${updated}, delete ${deleted}`
+                  ? `would create ${created}, update ${updated}, delete ${deleted}${conflicted}`
                   : `created ${created}, updated ${updated}, deleted ${deleted}`,
         );
         printTriggerSecrets(triggerSecrets);
@@ -60,33 +98,36 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
 
 /**
  * Loads the manifest at `file` and sends it, a preview under `dryRun`, then
- * prints its changes one row per entry. Ends the run on an invalid file, a
- * refusal, or a summary this CLI cannot read. `cortex apply` and `cortex
- * setup` both apply through it; each prints the trigger secrets it returns.
+ * prints its changes one row per entry, and a preview's conflicts. Ends the
+ * run on an invalid file, a refusal, or a summary this CLI cannot read.
+ * `cortex apply` and `cortex setup` both apply through it; each prints the
+ * trigger secrets it returns.
  */
 export async function applyManifest(options: {
     profile: ReturnType<typeof requireProfile>;
     file: string;
     dryRun: boolean;
     verbose: boolean;
+    prefer?: Side;
+    interactive: boolean;
 }) {
     const { profile, file, dryRun, verbose } = options;
-    const manifest = await loadManifest(file, verbose);
-    const answer = await callOrFail(profile, () =>
-        callManagement(
-            profile,
-            "post",
-            dryRun ? "/manifests/preview" : "/manifests/sync",
-            manifest,
+    const answer = await sendManifest({
+        ...options,
+        // What to run again: `cortex apply`, with the path unless it is the default.
+        command: ["cortex apply", ...(label(file) === DEFAULT_MANIFEST ? [] : [label(file)])].join(
+            " ",
         ),
-    );
+        manifest: await loadManifest(file, verbose),
+        path: dryRun ? "/manifests/preview" : "/manifests/sync",
+    });
     // The secrets are read apart from the changes: a sync has committed by
     // now, and a summary this CLI is too old to read must not lose them.
     const { triggerSecrets = {} } = appliedManifestSchema
         .pick({ triggerSecrets: true })
         .partial()
         .parse(answer);
-    const applied = manifestChangesSchema.safeParse(answer);
+    const applied = manifestPreviewSchema.partial({ conflicts: true }).safeParse(answer);
     if (!applied.success) {
         printTriggerSecrets(triggerSecrets);
         report.fail({
@@ -97,8 +138,68 @@ export async function applyManifest(options: {
             ],
         });
     }
-    printChanges(applied.data);
-    return { changes: applied.data, triggerSecrets };
+    const { conflicts = [], ...changes } = applied.data;
+    printChanges(changes, conflicts);
+    return { changes, triggerSecrets, conflicts };
+}
+
+/**
+ * Sends the manifest until nothing in it is left unanswered. A sync refused
+ * for fields both the manifest and a live edit changed asks about each one
+ * when it can, then goes again with the answers; one that cannot ask ends
+ * the run naming them. Any other refusal ends the run as well.
+ */
+async function sendManifest(options: {
+    profile: ReturnType<typeof requireProfile>;
+    path: string;
+    command: string;
+    manifest: Record<string, unknown>;
+    prefer?: Side;
+    interactive: boolean;
+}) {
+    const { profile, path, command, manifest, prefer, interactive } = options;
+    const resolutions: Resolution = [];
+    for (;;) {
+        try {
+            return await callManagement(profile, "post", path, {
+                ...manifest,
+                prefer,
+                resolutions,
+            });
+        } catch (error) {
+            const refused =
+                error instanceof ManagementError
+                    ? unresolvedSchema.safeParse(error.detail)
+                    : undefined;
+            if (!refused?.success) return failCall(profile, error);
+            if (!interactive) failUnresolved(refused.data.conflicts, command);
+            for (const conflict of refused.data.conflicts) {
+                const keep = await askChoice<Side>(`${conflictLabel(conflict)}. Keep which?`, [
+                    { value: "live", label: "Keep live" },
+                    { value: "manifest", label: "Use manifest" },
+                ]);
+                resolutions.push({ ...conflict, keep });
+            }
+        }
+    }
+}
+
+/** How a conflict reads: its entry and the field both sides changed. */
+function conflictLabel({ kind, name, field }: Conflict) {
+    return `${kind} ${name}: ${field} changed in both places`;
+}
+
+/** Ends a run that cannot ask, naming every conflict and how to run `command` again to answer them. */
+function failUnresolved(conflicts: ReadonlyArray<Conflict>, command: string): never {
+    const count = conflicts.length;
+    return report.fail({
+        what: `${count} field${count === 1 ? "" : "s"} changed both in Cortex and in the manifest`,
+        blocks: [
+            conflicts.map((conflict) => `  ${conflictLabel(conflict)}`).join("\n"),
+            "Keep one side for all of them, or run in a terminal to choose each:",
+            `  ${command} --prefer live\n  ${command} --prefer manifest`,
+        ],
+    });
 }
 
 /** How a manifest path prints: relative to the cwd, `./`-prefixed. */
@@ -140,17 +241,23 @@ async function loadManifest(path: string, verbose: boolean) {
             verbose,
         }),
     );
-    if (!parsed.success) {
+    if (!parsed.success || !isRecord(written)) {
         report.fail({
             what: `${label(path)} is not a valid manifest`,
-            blocks: [z.prettifyError(parsed.error)],
+            blocks: parsed.success ? [] : [z.prettifyError(parsed.error)],
         });
     }
     return written;
 }
 
-/** One row per changed entry under its kind: `+` created, `~` updated, `-` deleted. */
-function printChanges(changes: Record<(typeof CHANGES)[number], Record<string, string[]>>) {
+/**
+ * One row per changed entry under its kind: `+` created, `~` updated, `-`
+ * deleted, and `!` a field both the manifest and a live edit changed.
+ */
+function printChanges(
+    changes: Record<(typeof CHANGES)[number], Record<string, string[]>>,
+    conflicts: ReadonlyArray<Conflict>,
+) {
     const rows = new Map<string, string[]>();
     for (const change of CHANGES) {
         for (const [kind, names] of Object.entries(changes[change])) {
@@ -158,6 +265,9 @@ function printChanges(changes: Record<(typeof CHANGES)[number], Record<string, s
             rows.set(kind, [...(rows.get(kind) ?? []), ...marked]);
         }
     }
+    for (const { kind, name, field } of conflicts) {
+        rows.set(kind, [...(rows.get(kind) ?? []), `! ${name}  ${field} changed in both places`]);
+    }
     for (const [kind, lines] of rows) {
         for (const [index, line] of lines.entries()) {
             report.row(index === 0 ? kind : "", line, 14);

package/src/commands/management.ts

@@ -356,6 +356,13 @@ function declareCommand(
     return command;
 }
 
+/** What a publish went ahead despite, such as a prompt naming a tool without an @-mention. */
+function warningsOf(published: unknown) {
+    return isRecord(published) && Array.isArray(published.warnings)
+        ? published.warnings.filter((warning): warning is string => typeof warning === "string")
+        : [];
+}
+
 /**
  * A write to a publishable router is a draft: publish it now, or say how to.
  * Fields Cortex reads live are already in effect and are named as such,
@@ -378,10 +385,11 @@ async function publishAfterWrite(
         );
     }
     if (publish) {
-        await callOrFail(profile, () =>
+        const published = await callOrFail(profile, () =>
             callManagement(profile, publisher.method, publisher.path, { id }),
         );
         options.note(`Published ${id}.`);
+        for (const warning of warningsOf(published)) options.note(`Warning: ${warning}`);
     } else {
         options.note(
             `${live ? "The rest is" : "Saved as"} a draft. Add --publish, or run: ${command}`,

package/src/commands/setup.ts

@@ -135,6 +135,7 @@ export function registerSetup(program: Command<[], { verbose?: true; profile?: s
             file,
             dryRun: false,
             verbose,
+            interactive,
         });
         report.footer(`live · chat at ${profile.url}/playground`);
         printTriggerSecrets(triggerSecrets);

package/src/contracts/datasets/dataset-sql.ts

@@ -15,7 +15,13 @@ import type {
     DatasetQueryInput,
     DatasetRelation,
 } from "./datasets";
-import { DATASET_BUCKETS, DATASET_DATE_PARTS, describeOperand, groupKeyName } from "./datasets";
+import {
+    DATASET_BUCKETS,
+    DATASET_DATE_PARTS,
+    describeOperand,
+    groupKeyName,
+    unknownColumnError,
+} from "./datasets";
 
 /*
  * The SQL a model writes against a dataset, and how it becomes the wire
@@ -1658,6 +1664,11 @@ class Sources {
                 `"${qualifier}" is a link table; read its columns from the datasets it links.`,
             );
         }
+        // Checked here, where the query's own dataset name is known: the wire
+        // reference names the relation path instead.
+        if (!source.dataset.columns.some((c) => c.name === column)) {
+            throw new DatasetSqlError(unknownColumnError(source.dataset, column));
+        }
         return source.path ? `${source.path}.${column}` : column;
     }
 
@@ -1747,10 +1758,8 @@ class Sources {
                 `"${column}" is a column of ${owners.map((o) => o.dataset.name).join(" and ")}; qualify it as dataset.column.`,
             );
         }
-        const joined = this.paths.length ? " or of the joined datasets" : "";
-        throw new DatasetSqlError(
-            `"${column}" is not a column of ${this.root.dataset.name}${joined}.`,
-        );
+        const joined = this.paths.length ? " Nor does any joined dataset." : "";
+        throw new DatasetSqlError(unknownColumnError(this.root.dataset, column) + joined);
     }
 
     /** Every readable dataset once, whatever it is named as. */
@@ -2466,10 +2475,18 @@ function calendarDate(now: Date, timeZone: string | undefined) {
     }
 }
 
+/** The longest statement a query may be: room for any query a model writes, and a bound on the work one costs. */
+export const DATASET_SQL_MAX_LENGTH = 8_000;
+
 /** Parses one SELECT against the catalog into the wire query; throws {@link DatasetSqlError} with what to write instead. */
 export function parseDatasetSql(sql: string, catalog: DatasetCatalog, options: ParseOptions) {
     const trimmed = sql.trim();
     if (!trimmed) throw new DatasetSqlError("The query is empty.");
+    if (trimmed.length > DATASET_SQL_MAX_LENGTH) {
+        throw new DatasetSqlError(
+            `The query is longer than ${DATASET_SQL_MAX_LENGTH} characters; ask for less at once.`,
+        );
+    }
     const today = calendarDate(options.now, options.timeZone);
     return compile(catalog, new Parser(tokenize(trimmed), today).statement());
 }

package/src/contracts/datasets/datasets.ts

@@ -25,11 +25,22 @@ export const datasetColumnRefSchema = z.string().regex(DATASET_COLUMN_REF_PATTER
 export const DATASET_COLUMN_TYPES = ["string", "number", "boolean", "date"] as const;
 export type DatasetColumnType = (typeof DATASET_COLUMN_TYPES)[number];
 
-export const datasetColumnSchema = z.object({
-    name: datasetIdentifierSchema,
-    type: z.enum(DATASET_COLUMN_TYPES),
-    description: z.string().max(200).default(""),
-});
+/**
+ * One column. `values`, on a string column, lists every value it can hold:
+ * the agent reads them, and a query comparing the column to anything else is
+ * refused before it runs.
+ */
+export const datasetColumnSchema = z
+    .object({
+        name: datasetIdentifierSchema,
+        type: z.enum(DATASET_COLUMN_TYPES),
+        description: z.string().max(200).default(""),
+        values: z.array(z.string().min(1).max(200)).min(1).max(100).optional(),
+    })
+    .refine((column) => column.values === undefined || column.type === "string", {
+        message: "only a string column lists its values",
+        path: ["values"],
+    });
 export type DatasetColumn = z.infer<typeof datasetColumnSchema>;
 
 /**
@@ -396,10 +407,59 @@ export function resolveDatasetColumn(catalog: DatasetCatalog, from: string, ref:
         dataset = target;
     }
     const column = dataset.columns.find((candidate) => candidate.name === columnName);
-    if (!column) return missing(`"${dataset.name}" has no column "${columnName}"`);
+    if (!column) return missing(unknownColumnError(dataset, columnName));
     return { ok: true as const, column, path: segments.join(".") };
 }
 
+/**
+ * Why `dataset` has no column `name`, with the columns it has and up to
+ * three closest ones: names containing it or contained in it (ignoring
+ * case, and only for names longer than two characters), else names two
+ * edits or fewer away. A query that guessed `name` reads `departments has
+ * no column "name". Closest: nameAr, nameEn. Columns: id, nameAr, ...`
+ */
+export function unknownColumnError(dataset: DatasetDefinition, name: string) {
+    const columns = dataset.columns.map((column) => column.name);
+    const wanted = name.toLowerCase();
+    const containing = columns.filter((column) => {
+        const lower = column.toLowerCase();
+        return (
+            (wanted.length > 2 && lower.includes(wanted)) ||
+            (lower.length > 2 && wanted.includes(lower))
+        );
+    });
+    const closest = (
+        containing.length > 0
+            ? containing
+            : // Lengths more than two apart are more than two edits apart, so a
+              // name of any length costs only its own columns' comparisons.
+              columns.filter(
+                  (column) =>
+                      Math.abs(column.length - wanted.length) <= 2 &&
+                      editDistance(column.toLowerCase(), wanted) <= 2,
+              )
+    ).slice(0, 3);
+    const hint = closest.length > 0 ? ` Closest: ${closest.join(", ")}.` : "";
+    return `${dataset.name} has no column "${name}".${hint} Columns: ${columns.join(", ")}.`;
+}
+
+/** Levenshtein distance: the fewest single-character edits from `a` to `b`. */
+function editDistance(a: string, b: string) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(
+                previous[j]! + 1,
+                current[j - 1]! + 1,
+                previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+            );
+        }
+        previous = current;
+    }
+    return previous[b.length]!;
+}
+
 function refError(kind: string, ref: string, reason: string) {
     return `${kind} "${ref}": ${reason}`;
 }
@@ -654,6 +714,19 @@ export function validateDatasetQuery(catalog: DatasetCatalog, query: DatasetQuer
     } satisfies QueryCheck;
 
     for (const filter of query.filter) checkFilter(check, filter);
+    const row = checkAnsweredRow(check, catalog, query);
+    checkFinishedRow(check, query, row);
+    checkExpansion(check, query, catalog.get(query.from)?.columns.length ?? 0);
+    return issues;
+}
+
+/**
+ * The row a query answers, checked as it is built: on a grouped query its
+ * keys and aggregate aliases (never one name for both, and no select), on a
+ * plain one its select aliases; each with the names that are a column as it
+ * is, which keep what the column says.
+ */
+function checkAnsweredRow(check: QueryCheck, catalog: DatasetCatalog, query: DatasetQuery) {
     const groupKeys = checkGroupBy(check, query.groupBy);
     const aliases = checkAggregates(check, query.aggregate);
     for (const alias of aliases.keys()) {
@@ -671,12 +744,17 @@ export function validateDatasetQuery(catalog: DatasetCatalog, query: DatasetQuer
         );
     }
     const selectAliases = checkSelect(check, query.select ?? []);
-    const row = grouped
-        ? { names: new Map([...groupKeys, ...aliases]), kind: "grouped" as const }
-        : { names: selectAliases, kind: "plain" as const };
-    checkFinishedRow(check, query, row);
-    checkExpansion(check, query, catalog.get(query.from)?.columns.length ?? 0);
-    return issues;
+    return grouped
+        ? {
+              names: new Map([...groupKeys, ...aliases]),
+              kind: "grouped" as const,
+              columns: passedColumns(catalog, query, query.groupBy),
+          }
+        : {
+              names: selectAliases,
+              kind: "plain" as const,
+              columns: passedColumns(catalog, query, query.select ?? []),
+          };
 }
 
 /** How large any one expression a host translates may grow once every alias it names is written out in place. */
@@ -856,7 +934,7 @@ function filterCost(filter: DatasetFilter, expanded: ReadonlyMap<string, number>
 function checkFinishedRow(
     check: QueryCheck,
     query: DatasetQuery,
-    row: { names: Map<string, DatasetColumnType>; kind: "grouped" | "plain" },
+    row: RowNames & { names: Map<string, DatasetColumnType> },
 ) {
     const rowCheck = rowScope(check, row);
     // On a plain row a selected column is a name too; a window or calculation may not take it.
@@ -881,7 +959,7 @@ function rowScope(check: QueryCheck, row: RowNames) {
         issue: (message: string) => check.issue(message),
         columnOf(kind, ref) {
             const type = row.names.get(ref);
-            if (type) return { name: ref, type, description: "" };
+            if (type) return row.columns.get(ref) ?? { name: ref, type, description: "" };
             if (row.kind === "plain") return check.columnOf(kind, ref);
             check.issue(
                 refError(
@@ -1203,10 +1281,31 @@ function checkFilter(check: QueryCheck, filter: DatasetFilter, kind = "filter")
         ? columnValueIssue(check, kind, type, filter.op, filter.value.col)
         : (filterValueIssue(filter) ??
           filterValueTypeIssue(type, filter) ??
-          truncatedDateIssue(filter));
+          truncatedDateIssue(filter) ??
+          listedValueIssue(check, kind, filter));
     if (issue) check.issue(refError(kind, shown, issue));
 }
 
+const LISTED_VALUE_OPS = new Set<DatasetFilterOp>(["=", "!=", "in", "notIn"]);
+
+/**
+ * A column that lists its values is only compared with one of them: any
+ * other literal would match no row, or every row, and the host would answer
+ * as if the data said so.
+ */
+function listedValueIssue(check: QueryCheck, kind: string, filter: DatasetCondition) {
+    if (typeof filter.col !== "string" || !LISTED_VALUE_OPS.has(filter.op)) return undefined;
+    if (filter.value === undefined || isColumnValue(filter.value)) return undefined;
+    const listed = check.columnOf(kind, filter.col)?.values;
+    if (!listed) return undefined;
+    const values = Array.isArray(filter.value) ? filter.value : [filter.value];
+    // A number or a boolean is compared as the text the host turns it into.
+    const odd = values.find((value) => !listed.includes(String(value)));
+    return odd === undefined
+        ? undefined
+        : `${JSON.stringify(odd)} is not one of its values: ${listed.join(", ")}`;
+}
+
 /** A truncated date is a whole day, so a literal against it is one too ("2024-03-01"); a time or a bare month would never match. */
 function truncatedDateIssue(filter: DatasetCondition) {
     const truncated =
@@ -1314,7 +1413,31 @@ function aggregateType(
 }
 
 /** What sort and rank may name: on a grouped query a group key or an alias; on a plain one a select alias or any reachable column. */
-type RowNames = { names: ReadonlyMap<string, DatasetColumnType>; kind: "grouped" | "plain" };
+type RowNames = {
+    names: ReadonlyMap<string, DatasetColumnType>;
+    kind: "grouped" | "plain";
+    /** The names that are a column as it is (group keys, select entries), so what the column says (its values) still holds. */
+    columns: ReadonlyMap<string, DatasetColumn>;
+};
+
+/**
+ * The row names that are a column as it is, each with the column: a bare
+ * column (`status`), or one under an alias (`{ expr: "status", as: "state" }`).
+ */
+function passedColumns(
+    catalog: DatasetCatalog,
+    query: DatasetQuery,
+    entries: ReadonlyArray<string | { expr: DatasetOperand; as: string }>,
+) {
+    return new Map(
+        entries.flatMap((entry) => {
+            const [name, ref] = typeof entry === "string" ? [entry, entry] : [entry.as, entry.expr];
+            if (typeof ref !== "string") return [];
+            const resolved = resolveDatasetColumn(catalog, query.from, ref);
+            return resolved.ok ? [[name, resolved.column] as const] : [];
+        }),
+    );
+}
 
 function checkSort(check: QueryCheck, sort: DatasetQuery["sort"], kind: string, row: RowNames) {
     for (const { col } of sort) checkRowName(check, kind, col, row);

package/src/contracts/egress-policy/scrub.ts

@@ -7,19 +7,22 @@ const REDACTION_MARKER = "[REDACTED]";
  * itself and, after a leading scheme word (`Bearer xyz`, `Basic abc`), the
  * bare secret the scheme merely labels; each of those raw as in a header,
  * percent-encoded as in a path slot (`encodeURIComponent`) or a query value
- * (`URLSearchParams`, which spells a space as `+`), and JSON-escaped as inside
- * a request body. The scrubber replaces longer forms first.
+ * (`URLSearchParams`, which spells a space as `+`), JSON-escaped as inside
+ * a request body, and JSON-escaped then percent-encoded as a form field sent
+ * as JSON text is. The scrubber replaces longer forms first.
  */
 export function credentialForms(value: string) {
     const bare = /^[A-Za-z][\w.-]* +(\S.*)$/.exec(value)?.[1];
+    const percentEncoded = (form: string) => [
+        encodeURIComponent(form),
+        new URLSearchParams({ v: form }).toString().slice(2),
+    ];
     return [
         ...new Set(
-            (bare ? [value, bare] : [value]).flatMap((form) => [
-                form,
-                encodeURIComponent(form),
-                new URLSearchParams({ v: form }).toString().slice(2),
-                JSON.stringify(form).slice(1, -1),
-            ]),
+            (bare ? [value, bare] : [value]).flatMap((form) => {
+                const json = JSON.stringify(form).slice(1, -1);
+                return [form, ...percentEncoded(form), json, ...percentEncoded(json)];
+            }),
         ),
     ];
 }

package/src/contracts/json/index.ts

@@ -24,3 +24,24 @@ export function escapePointerToken(token: string) {
 export function unescapePointerToken(token: string) {
     return token.replaceAll("~1", "/").replaceAll("~0", "~");
 }
+
+/** An RFC 6901 array index: digits with no leading zero. */
+export const ARRAY_INDEX = /^(0|[1-9]\d*)$/;
+
+/** RFC 6901 lookup; `undefined` when the pointer names nothing (an inherited key, or an array index not written canonically, included). */
+export function readJsonPointer(value: unknown, pointer: string) {
+    if (pointer === "") return value;
+    let current: unknown = value;
+    for (const raw of pointer.slice(1).split("/")) {
+        const key = unescapePointerToken(raw);
+        if (Array.isArray(current)) {
+            if (!ARRAY_INDEX.test(key)) return undefined;
+            current = current[Number(key)];
+        } else if (isRecord(current) && Object.hasOwn(current, key)) {
+            current = current[key];
+        } else {
+            return undefined;
+        }
+    }
+    return current;
+}

package/src/contracts/manifest/index.ts

@@ -46,8 +46,16 @@ export const TOOL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
  */
 export const RESPONSE_WRAPS = ["items", "value"] as const;
 
+/** How OpenAPI serializes a query parameter: `form` (the default), `spaceDelimited`, `pipeDelimited` or `deepObject`. */
+export const QUERY_STYLES = ["form", "spaceDelimited", "pipeDelimited", "deepObject"] as const;
+/** How OpenAPI serializes a path parameter: `simple` (the default), `label` or `matrix`. */
+export const PATH_STYLES = ["simple", "label", "matrix"] as const;
+
 export const SOAP_VERSIONS = ["1.1", "1.2"] as const;
 
+/** An RFC 6901 pointer into a JSON document, naming a member: `/extra`, `/data/items`. */
+const jsonPointerSchema = z.string().regex(/^\//).max(256);
+
 type Bounds = { min: number; max: number; default: number };
 
 /**
@@ -91,6 +99,25 @@ function setting({ min, max, default: fallback }: Bounds) {
     return z.number().int().min(min).max(max).default(fallback);
 }
 
+/**
+ * The fields of an entry users may change in Cortex after an apply, each
+ * once, from the ones `fields` allows; none when left out. Every other field
+ * is the manifest's alone. An apply keeps a live change to a listed field
+ * unless the manifest changed that field too (a conflict, see
+ * `manifestApplyInputSchema`). Identity, what is fixed at creation, the
+ * audience, credentials, and whatever an apply checks against the
+ * manifest's own value are never offered.
+ */
+function overridable<const TField extends string>(fields: readonly [TField, ...TField[]]) {
+    return z
+        .array(z.enum(fields))
+        .refine(
+            uniqueBy((field: TField) => field),
+            "a field repeats",
+        )
+        .default([]);
+}
+
 /** Consumer-facing slugs: the manifest id, service keys, skill names and trigger names share it. */
 export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const slugSchema = z.string().regex(SLUG_PATTERN).max(64);
@@ -175,6 +202,16 @@ export const soapActionSchema = z.string().regex(/^[^"\\\u0000-\u001f\u007f]*$/)
 /** An envelope template: XML, so never only whitespace. */
 const envelopeTemplateSchema = z.string().refine((template) => template.trim().length > 0);
 
+/**
+ * The media types a request body may be sent in besides JSON, the default.
+ * Each body field is written as its target says.
+ */
+export const FORM_MEDIA_TYPES = [
+    "application/x-www-form-urlencoded",
+    "multipart/form-data",
+] as const;
+export type FormMediaType = (typeof FORM_MEDIA_TYPES)[number];
+
 /**
  * The per-type payload a tool stores and publishes. Soap: the envelope
  * template is the full request XML with `{{field}}` placeholders bound to
@@ -182,7 +219,12 @@ const envelopeTemplateSchema = z.string().refine((template) => template.trim().l
  * acquires once per request.
  */
 export const toolConfigByType = {
-    http: z.object({ responseWrap: z.enum(RESPONSE_WRAPS).optional() }),
+    http: z.object({
+        responseWrap: z.enum(RESPONSE_WRAPS).optional(),
+        requestMediaType: z.enum(FORM_MEDIA_TYPES).optional(),
+        /** Where a successful response keeps the result, for an API that wraps every answer (`{ success, extra }`); read before `responseWrap`. */
+        resultPath: jsonPointerSchema.optional(),
+    }),
     embedded: z.object({ embedOrigin: embedOriginSchema, surface: z.enum(TOOL_SURFACES) }),
     soap: z.object({
         soapVersion: z.enum(SOAP_VERSIONS),
@@ -343,17 +385,44 @@ export function sourceFits(
 }
 
 /**
- * Where a top-level scalar input field travels in the upstream request;
- * absent, path placeholders by name, then the query string on GET and the
- * body otherwise. `name` renames a query parameter, header or cookie on the
- * wire.
+ * Where a top-level input field travels in the upstream request; absent,
+ * path placeholders by name, then the query string on GET and the body
+ * otherwise. `name` renames a query parameter, header or cookie on the wire,
+ * and is the name `matrix` style writes into a path.
+ * `style` and `explode` write an array or object value as an OpenAPI
+ * parameter declares; left out, OpenAPI's defaults hold (`form` exploded for
+ * a query, `simple` unexploded for a path and a header). A cookie joins items
+ * with commas. In a form body (the tool's `requestMediaType`), a JSON
+ * `contentType` sends the value as JSON text, and `style` and `explode`
+ * write it as in a query; a multipart body repeats an array's items as
+ * parts, typing an object JSON unless `contentType` says text. A JSON body
+ * reads none of them.
  */
 export const fieldTargetSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("body") }),
-    z.object({ kind: z.literal("query"), name: z.string().trim().min(1).max(120).optional() }),
-    z.object({ kind: z.literal("path") }),
-    z.object({ kind: z.literal("header"), name: headerNameSchema.optional() }),
-    z.object({ kind: z.literal("cookie"), name: headerNameSchema.optional() }),
+    z.strictObject({
+        kind: z.literal("body"),
+        contentType: z.enum(["application/json", "text/plain"]).optional(),
+        style: z.enum(QUERY_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("query"),
+        name: z.string().trim().min(1).max(120).optional(),
+        style: z.enum(QUERY_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("path"),
+        name: z.string().trim().min(1).max(120).optional(),
+        style: z.enum(PATH_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("header"),
+        name: headerNameSchema.optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({ kind: z.literal("cookie"), name: headerNameSchema.optional() }),
 ]);
 export type FieldTarget = z.infer<typeof fieldTargetSchema>;
 
@@ -381,8 +450,8 @@ const itemsSchema = z.strictObject({
  * a type (with `"null"` beside it when the value may be null), an `enum` of
  * strings for a string, an object's `properties` and `required`, an
  * array's `items`, a `description`, and the extensions `x-sensitive`
- * (redacted from logs), `x-source` and `x-target` (top-level scalar fields
- * of a tool's input only).
+ * (redacted from logs), `x-source` (top-level scalar fields of a tool's
+ * input only) and `x-target` (top-level fields of a tool's input only).
  */
 const schemaPropertySchema = z.strictObject({
     type: z.union([schemaTypeSchema, z.tuple([schemaTypeSchema, z.literal("null")])]),
@@ -453,9 +522,9 @@ function enumIssueOf(property: SchemaProperty, type: string | undefined) {
 /**
  * What one property breaks of itself: an `enum` off a string, with no value,
  * or listing `null` when the type does not allow it or the other way round;
- * `items` off an array or an array without them; and `x-source` or
- * `x-target` off a scalar of a `bindable` node, or a source that does not
- * fit the field.
+ * `items` off an array or an array without them; `x-source` off a scalar
+ * of a `bindable` node, or a source that does not fit the field; and
+ * `x-target` off a `bindable` node.
  */
 function propertyIssues(property: SchemaProperty, bindable: boolean) {
     const issues = new Array<RowIssue>();
@@ -469,13 +538,17 @@ function propertyIssues(property: SchemaProperty, bindable: boolean) {
         });
     }
     const binds = bindable && SCALAR_TYPES.some((scalar) => scalar === type);
-    for (const binding of ["x-source", "x-target"] as const) {
-        if (property[binding] !== undefined && !binds) {
-            issues.push({
-                at: [binding],
-                message: "only a top-level scalar field of a tool's input has it",
-            });
-        }
+    if (property["x-source"] !== undefined && !binds) {
+        issues.push({
+            at: ["x-source"],
+            message: "only a top-level scalar field of a tool's input has it",
+        });
+    }
+    if (property["x-target"] !== undefined && !bindable) {
+        issues.push({
+            at: ["x-target"],
+            message: "only a top-level field of a tool's input has it",
+        });
     }
     const source = property["x-source"];
     if (binds && source && !sourceFits(source, { type, enum: property.enum })) {
@@ -487,8 +560,8 @@ function propertyIssues(property: SchemaProperty, bindable: boolean) {
 /**
  * Refuses, at every depth below `path`, what the console's field rows cannot
  * hold, since it stores a schema as rows and would drop or change it in
- * silence (`nodeIssues`, `propertyIssues`); `x-source` and `x-target` only
- * on a scalar directly under a node where `bindable`.
+ * silence (`nodeIssues`, `propertyIssues`); `x-source` only on a scalar,
+ * and `x-target` only on a field, directly under a node where `bindable`.
  */
 function heldByRows(
     node: {
@@ -516,8 +589,8 @@ function heldByRows(
 
 /**
  * An object's JSON Schema, the shape of a tool's or trigger's input and
- * output. `bindable` admits `x-source` and `x-target` on its top-level
- * scalar fields, as a tool's input has them.
+ * output. `bindable` admits `x-source` on its top-level scalar fields and
+ * `x-target` on its top-level fields, as a tool's input has them.
  */
 function objectSchemaOf(bindable: boolean) {
     return z
@@ -572,6 +645,15 @@ const toolBaseSchema = z.strictObject({
     pinned: z.boolean().default(false),
     tags: toolTagsSchema.default([]),
     audience: audienceSchema,
+    overridable: overridable([
+        "description",
+        "timeoutMs",
+        "maxResponseBytes",
+        "rateLimitRequests",
+        "rateLimitWindowSeconds",
+        "pinned",
+        "tags",
+    ]),
 });
 
 /** A tool that calls an endpoint; with `requiresApproval`, every call waits for the end user to approve it. */
@@ -629,6 +711,8 @@ const manifestOpenApiSchema = z.strictObject({
     /** Where the document is read, with no credentials: OpenAPI 3 or Swagger 2, JSON or YAML. */
     url: upstreamUrlSchema,
     credentials: credentialsSchema,
+    /** Where every operation's successful response keeps its result, when the API wraps each answer. */
+    resultPath: jsonPointerSchema.optional(),
     /** Tools listed in every turn of every agent they reach, whatever the question. */
     pinned: toolNamesSchema,
     approval: z
@@ -650,6 +734,7 @@ const manifestServiceSchema = z.strictObject({
     /** Rich text: it may mention tools and skills. */
     description: localizedTextSchema,
     audience: audienceSchema,
+    overridable: overridable(["description"]),
 });
 export type ManifestService = z.input<typeof manifestServiceSchema>;
 
@@ -661,6 +746,7 @@ const manifestSkillSchema = z.strictObject({
     /** The key of the service the skill renders inside; fixed once created. */
     service: slugSchema.optional(),
     audience: audienceSchema,
+    overridable: overridable(["description", "body"]),
 });
 export type ManifestSkill = z.input<typeof manifestSkillSchema>;
 
@@ -677,7 +763,7 @@ export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
     z.object({ policy: z.literal("single") }),
     z.object({ policy: z.literal("per-firing") }),
     z.object({ policy: z.literal("ephemeral") }),
-    z.object({ policy: z.literal("keyed"), key: z.string().regex(/^\//).max(256) }),
+    z.object({ policy: z.literal("keyed"), key: jsonPointerSchema }),
 ]);
 export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
 
@@ -708,6 +794,14 @@ const manifestTriggerSchema = z.strictObject({
     /** The model its runs talk to, over each agent's. */
     model: modelSchema.optional(),
     audience: audienceSchema,
+    overridable: overridable([
+        "description",
+        "instructions",
+        "threadPolicy",
+        "budgetPerDay",
+        "disableAfterFailures",
+        "model",
+    ]),
 });
 export type ManifestTrigger = z.input<typeof manifestTriggerSchema>;
 
@@ -731,6 +825,7 @@ const manifestDatasetHostSchema = z
         /** Among those, the ones listed in every turn, whatever the question. */
         pinned: z.array(datasetIdentifierSchema).max(50).default([]),
         audience: audienceSchema,
+        overridable: overridable(["timeoutMs"]),
     })
     .superRefine((host, context) => {
         const unexposed = unexposedPins(host);
@@ -771,6 +866,7 @@ const manifestMcpServerSchema = z.strictObject({
     include: mcpToolNamesSchema.default([]),
     exclude: mcpToolNamesSchema.default([]),
     audience: audienceSchema,
+    overridable: overridable(["include", "exclude"]),
 });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
@@ -793,6 +889,7 @@ const manifestWebhookSchema = z.strictObject({
     ),
     timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
     audience: audienceSchema,
+    overridable: overridable(["description", "timeoutMs"]),
 });
 export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
 
@@ -802,7 +899,10 @@ const manifestCollectionSchema = z.strictObject({
     description: z.string().trim().max(2_000).default(""),
     /** The key of the service every document in the collection belongs to. */
     service: slugSchema.optional(),
+    /** Whether answers may name its documents; false keeps their names, sections and pages from the model. */
+    citable: z.boolean().default(true),
     audience: audienceSchema,
+    overridable: overridable(["description"]),
 });
 export type ManifestCollection = z.input<typeof manifestCollectionSchema>;
 
@@ -840,10 +940,11 @@ const { agent: agentBounds, agentContext, agentLimits } = SETTING_BOUNDS;
 
 /** How the agent runs; every setting left out keeps its default. */
 const agentSettingsSchema = z.strictObject({
-    /** Offers `searchKnowledge` over the collections the agent sees. */
+    /** Lets `searchRegistries` search the knowledge in the collections the agent sees. */
     ragEnabled: z.boolean().default(false),
-    /** Offers `searchTools` over the tools the agent sees, beyond the pinned and mentioned ones. */
+    /** Lets `searchRegistries` search the tools the agent sees, beyond the pinned and mentioned ones. */
     toolRegistryEnabled: z.boolean().default(false),
+    /** Lets `searchRegistries` search the services the agent sees. */
     serviceRegistryEnabled: z.boolean().default(false),
     attachmentsEnabled: z.boolean().default(true),
     /** Hosts the built-in `fetchImage` tool may pull images from; none, no such tool. */
@@ -903,6 +1004,7 @@ const manifestAgentSchema = z.strictObject({
     settings: agentSettingsSchema.prefault({}),
     suggestions: suggestionsSchema.default({ en: [], ar: [] }),
     greeting: greetingSchema.default({ en: "", ar: "" }),
+    overridable: overridable(["name", "prompt", "models", "settings", "suggestions", "greeting"]),
 });
 export type ManifestAgent = z.input<typeof manifestAgentSchema>;
 
@@ -923,7 +1025,9 @@ export const CORTEX_MANIFEST_ID = "cortex";
 /**
  * A deployment's agents and components, owned by the manifest `id`: an apply
  * of it creates what is new, updates what changed, and deletes what it no
- * longer lists, touching nothing it did not create.
+ * longer lists, touching nothing it did not create. What an entry lists as
+ * `overridable` may then change in Cortex too, and an apply keeps that
+ * change unless the manifest changed the same field.
  */
 export const manifestSchema = z.strictObject({
     /** Fixed for the deployment it describes: the rows an apply owns carry it. */
@@ -942,14 +1046,11 @@ export const manifestSchema = z.strictObject({
 /** A manifest as written: every field with a default may be left out. */
 export type Manifest = z.input<typeof manifestSchema>;
 
-/**
- * Entry names per kind: agents by slug, services by key, everything else by
- * name. An OpenAPI source's operations are counted among `tools`.
- */
-const namesByKindSchema = z.record(
-    manifestSchema.keyof().exclude(["id", "openapi"]),
-    z.array(z.string()),
-);
+/** The kinds of row a manifest owns; an OpenAPI source's operations are `tools`. */
+const manifestKindSchema = manifestSchema.keyof().exclude(["id", "openapi"]);
+
+/** Entry names per kind: agents by slug, services by key, everything else by name. */
+const namesByKindSchema = z.record(manifestKindSchema, z.array(z.string()));
 
 /** What an apply creates, updates and deletes, kind by kind; a preview answers the same without doing it. */
 export const manifestChangesSchema = z.object({
@@ -958,6 +1059,32 @@ export const manifestChangesSchema = z.object({
     delete: namesByKindSchema,
 });
 
+/** A field of one entry that both the manifest and a live write changed since the last apply. */
+const manifestConflictSchema = z.strictObject({
+    kind: manifestKindSchema,
+    name: z.string(),
+    field: z.string(),
+});
+
+/** Which value a conflict keeps: the one changed live in Cortex, or the manifest's. */
+const conflictSideSchema = z.enum(["live", "manifest"]);
+
+/**
+ * What preview and sync take: the manifest, and how its conflicts resolve.
+ * A conflict takes its own entry in `resolutions`, else `prefer`; a sync
+ * left with one neither answers is refused as `unresolved_conflicts`,
+ * naming them. A resolution for a field that no longer conflicts is ignored.
+ */
+export const manifestApplyInputSchema = manifestSchema.extend({
+    prefer: conflictSideSchema.optional(),
+    resolutions: z.array(manifestConflictSchema.extend({ keep: conflictSideSchema })).default([]),
+});
+
+/** What a preview answers: the changes, and the conflicts nothing resolved. */
+export const manifestPreviewSchema = manifestChangesSchema.extend({
+    conflicts: z.array(manifestConflictSchema),
+});
+
 /**
  * An apply's changes, and a fire secret, shown this once, for each trigger
  * it left with none anyone holds: one it created, or one whose

package/src/contracts/server/index.ts

@@ -97,10 +97,8 @@ export const BUILT_IN_TOOL_NAMES = [
     "queryDataset",
     "readAttachment",
     "readReport",
-    "searchKnowledge",
-    "searchServices",
+    "searchRegistries",
     "searchThreadHistory",
-    "searchTools",
     REQUEST_LOCATION_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
 ] as const;

package/src/contracts/server/reserved-names.fixtures.json

@@ -7,10 +7,8 @@
         "queryDataset",
         "readAttachment",
         "readReport",
-        "searchKnowledge",
-        "searchServices",
+        "searchRegistries",
         "searchThreadHistory",
-        "searchTools",
         "requestLocation",
         "submitAnswer"
     ],

package/src/contracts/wire/index.ts

@@ -131,12 +131,23 @@ export type ClientToolBinding = {
  */
 export type AgentCapabilities = {
     attachments: boolean;
-    /** False when the agent's `message` trigger is off: the widget hides its composer. */
+    /**
+     * False when this caller may not send to the chat: the agent's `message`
+     * trigger is off, or the caller only reads (`readOnly`). The widget hides
+     * its composer and answers no tool call.
+     */
     messages: boolean;
+    /** True when the caller only reads, as an operator inspecting a user's thread does. */
+    readOnly: boolean;
     /** Prompt chips on the blank-chat landing per locale; clicking one sends its `prompt` as the first message. */
     suggestions: Suggestions;
     /** Headline of the blank-chat landing per locale; "" falls back to the widget's built-in copy. */
     greeting: Greeting;
+    /**
+     * Whether this caller gets the debug view: tool inputs and outputs, reasoning,
+     * model calls. Cortex sends anyone else only what the widget's normal UI draws.
+     */
+    debug: boolean;
 };
 
 export type MessageMetadata = {
@@ -178,6 +189,13 @@ export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"
  */
 export const APPROVAL_TITLE_FIELD = "approvalTitle";
 
+/** The title the model wrote into an approval call's input, or undefined while it has none. */
+export function approvalTitleOf(input: unknown) {
+    if (!input || typeof input !== "object" || !(APPROVAL_TITLE_FIELD in input)) return undefined;
+    const title: unknown = input[APPROVAL_TITLE_FIELD];
+    return typeof title === "string" && title.trim() ? title.trim() : undefined;
+}
+
 /**
  * What Cortex stamps on a tool call's `metadata.cortex` from its first chunk,
  * so the live part and the stored one agree.
@@ -331,3 +349,19 @@ export type WsEvent =
 
 /** The header the widget sends the browser's IANA time zone in; the turn reasons in that clock. */
 export const TIMEZONE_HEADER = "X-Cortex-Timezone";
+
+/**
+ * The console operator's short-lived token, sent by the playground and the
+ * thread inspector on every request to an agent and by the fire and answer
+ * calls Cortex makes to a trigger's route. A verified one makes the operator the caller unless the
+ * request also carries an end-user token to test as, and marks the threads it
+ * opens as test threads. A WebSocket upgrade carries it as `?operator=`.
+ */
+export const OPERATOR_HEADER = "X-Cortex-Operator";
+
+/**
+ * Beside the operator token, the id of a thread the operator inspects: the
+ * request then reads as that thread's owner, read-only, with the debug view.
+ * A WebSocket upgrade carries it as `?inspect=`.
+ */
+export const INSPECT_HEADER = "X-Cortex-Inspect";

package/src/scaffold/files.ts

@@ -27,7 +27,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.14.1";
+const CORTEX_VERSION = "0.15.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -150,7 +150,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.2.0",
+                "@m6d/cortex": "~0.3.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",

package/src/ui/prompts.ts

@@ -14,6 +14,7 @@ import {
     log,
     outro,
     password,
+    select,
     spinner,
     text,
 } from "@clack/prompts";
@@ -50,6 +51,14 @@ export function askName(check: (name: string) => string | undefined) {
     );
 }
 
+/** One of `options`, by its value; the first is the default. */
+export function askChoice<const TValue extends string>(
+    message: string,
+    options: Parameters<typeof select<TValue>>[0]["options"],
+) {
+    return orExit(select({ message, options }));
+}
+
 /** A yes-or-no question a flag left open, answered no unless the caller says otherwise. */
 export function askConfirm(message: string, initialValue = false) {
     return orExit(confirm({ message, initialValue }));