primitive-admin 1.1.0-alpha.83 → 1.1.0-alpha.85

package/dist/src/lib/generated-config-surfaces.js

@@ -365,13 +365,98 @@ export function handlerReferences(table) {
     }
     return [...refs].sort();
 }
-/** TOML keys this table accepts: the exposed fields plus the declared extras. */
+// ── TOML groups (#3626) ──────────────────────────────────────────────────
+//
+// A field may declare the sub-table it is authored under (`tomlGroup`), and the
+// table declares the closed set of names it admits (`tomlGroups`). These four
+// functions are the whole mechanism: everything else — the pull projection, the
+// push payload builder, the CLI's unknown-key and declared-type checks — reads
+// the declaration through them.
+/** The group names this table declares, sorted. Empty for an ungrouped table. */
+export function tomlGroupNames(table) {
+    return Object.keys(table.tomlGroups ?? {}).sort();
+}
+/** The TOML keys accepted INSIDE `group`: every field that declares it. */
+export function acceptedGroupTomlKeys(table, group) {
+    return new Set(table.fields.filter((f) => f.tomlGroup === group).map((f) => f.tomlKey));
+}
+/**
+ * TOML keys this table accepts AT ITS ROOT: the UNGROUPED fields, the declared
+ * group names, and the declared extras.
+ *
+ * A grouped leaf written at the root (`questions` directly under `[[configs]]`)
+ * is therefore an unknown key rather than one the payload builder silently
+ * ignores (SO3626-013) — the builder reads a grouped field only from
+ * `source[group][tomlKey]`, so accepting it here would drop the author's value
+ * without a word. The nine deprecated flat chat keys stay accepted through
+ * their `tomlOnlyKeys` declarations, which is what keeps old files pushing.
+ */
 export function acceptedTomlKeys(table) {
     return new Set([
-        ...table.fields.map((f) => f.tomlKey),
+        ...table.fields.filter((f) => !f.tomlGroup).map((f) => f.tomlKey),
+        ...tomlGroupNames(table),
         ...Object.keys(table.tomlOnlyKeys),
     ]);
 }
+/**
+ * Keys inside a group table that no field declares under it, as
+ * `"<group>.<key>"` — plus the bare `"<group>"` for a group value that is not a
+ * table at all (`chat = "yes"`), which has no keys to check and would otherwise
+ * be read as an empty block.
+ */
+export function findUnknownGroupedTomlKeys(tomlTable, table) {
+    if (!tomlTable || typeof tomlTable !== "object" || Array.isArray(tomlTable)) {
+        return [];
+    }
+    const entry = tomlTable;
+    const out = [];
+    for (const group of tomlGroupNames(table)) {
+        if (!(group in entry))
+            continue;
+        const value = entry[group];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== "object" || Array.isArray(value)) {
+            out.push(group);
+            continue;
+        }
+        const known = acceptedGroupTomlKeys(table, group);
+        for (const key of Object.keys(value)) {
+            if (!known.has(key))
+                out.push(`${group}.${key}`);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Group declarations that do not hold together: a field naming a group the
+ * table does not declare, a declared group no field is authored under, and a
+ * declaration with no reason. All three are failures, for the reason
+ * `notExposed` carries a note — a name in a list with nothing behind it reads
+ * as a decision and is not one.
+ */
+export function findBadTomlGroupDeclarations(table) {
+    const declared = new Set(tomlGroupNames(table));
+    const used = new Set(table.fields
+        .map((f) => f.tomlGroup)
+        .filter((g) => typeof g === "string"));
+    const bad = [];
+    for (const field of table.fields) {
+        if (field.tomlGroup && !declared.has(field.tomlGroup)) {
+            bad.push(`${field.field}: tomlGroup "${field.tomlGroup}" is not declared in tomlGroups`);
+        }
+    }
+    for (const [group, entry] of Object.entries(table.tomlGroups ?? {})) {
+        if (!entry || typeof entry.note !== "string" || !entry.note.trim()) {
+            bad.push(`${group}: tomlGroups entries need a note`);
+            continue;
+        }
+        if (!used.has(group)) {
+            bad.push(`${group}: declared in tomlGroups but no field is authored under it`);
+        }
+    }
+    return bad.sort();
+}
 // ── Document-level acceptance ────────────────────────────────────────────
 //
 // `acceptedTomlKeys` answers "is this key accepted inside this table". These
@@ -4770,6 +4855,260 @@ function geminiResolution(model, effort, budget) {
         },
     };
 }
+// ── src/config-surface/prompt-kinds.ts ───────────────────────────────────
+/**
+ * What a prompt's KIND admits — issue #3626.
+ *
+ * A prompt declares `[prompt] kind = "chat" | "decisions"`. The kind decides
+ * the input envelope (`variables` rendered into templates for chat, a `state`
+ * value for decisions), the provider endpoint the executor posts to, and which
+ * `[configs.<kind>]` block a `[[configs]]` entry may carry. Adding a kind is a
+ * group declaration plus its fields, not another round of implicit
+ * discrimination: the earlier design inferred "this is a decisions config" from
+ * the presence of `questions` on a table otherwise shaped for chat, and refused
+ * the nine chat keys one by one.
+ *
+ * This module is the whole rule. `resolvePromptKind` is called by the CLI's
+ * push preflight through the vendored artifact, by `createAppPrompt`,
+ * `createPromptConfig` and `updatePromptConfig`, so a refusal at push and a
+ * refusal at the admin route cannot disagree — the `resolvePromptReasoning`
+ * posture of #3358, for the same reason.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/** The kinds a prompt may declare. An omitted `kind` is `chat`. */
+export const PROMPT_KINDS = ["chat", "decisions"];
+/**
+ * The nine settings that describe a CHAT COMPLETION and nothing else. They are
+ * authored under `[configs.chat]`; the flat spelling is deprecated (#3642).
+ */
+export const CHAT_CONFIG_KEYS = [
+    "systemPrompt",
+    "userPromptTemplate",
+    "temperature",
+    "topP",
+    "maxTokens",
+    "outputFormat",
+    "outputSchema",
+    "reasoningEffort",
+    "reasoningBudget",
+];
+/** The settings that describe a DECISIONS request. */
+export const DECISIONS_CONFIG_KEYS = ["questions"];
+/**
+ * The WIRE field names each kind's block holds. The config surface declares the
+ * same grouping through `ConfigField.tomlGroup`, and the drift guard asserts
+ * the two agree — so a chat key added to the surface without a home here (or
+ * the reverse) fails `cli-unit-tests` rather than being accepted under a
+ * decisions prompt.
+ */
+export const PROMPT_KIND_BLOCKS = {
+    chat: CHAT_CONFIG_KEYS,
+    decisions: DECISIONS_CONFIG_KEYS,
+};
+/** The question types TypeSafe's System One models answer. */
+export const DECISIONS_QUESTION_TYPES = ["choice", "score", "noul"];
+/** A question name the endpoint accepts, and that reads as a JSON key. */
+const QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * The prompt's kind, normalized.
+ *
+ * Every reader goes through this: rows created before #3626 carry no `kind`
+ * attribute at all, and an absent one is `chat` everywhere — the detail route,
+ * pull, diff, execution and codegen.
+ */
+export function promptKindOf(prompt) {
+    const raw = prompt?.kind;
+    if (typeof raw !== "string")
+        return "chat";
+    const text = raw.trim();
+    return PROMPT_KINDS.includes(text)
+        ? text
+        : "chat";
+}
+/** `null`, `undefined` and `""` are absence; `false` and `0` are values. */
+function isUnset(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+function isPlainObject(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value));
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/**
+ * `questions` as a value: a TOML table arrives as an object, a JSON-string
+ * spelling as text (a `json` field takes either transport, #2880 criterion 5).
+ * `undefined` for anything that is not a JSON object.
+ */
+function parseQuestions(value) {
+    if (isPlainObject(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        try {
+            const parsed = JSON.parse(value);
+            return isPlainObject(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** The chat keys this config actually sets, in declaration order. */
+function chatKeysSet(config) {
+    return CHAT_CONFIG_KEYS.filter((key) => !isUnset(config[key]));
+}
+/**
+ * One rule replaces the nine per-key refusals: a `[[configs]]` entry may carry
+ * only the block named by its prompt's kind.
+ */
+function wrongBlockError(kind, offending) {
+    const wrongKind = kind === "chat" ? "decisions" : "chat";
+    return (`prompt kind is "${kind}", so a [[configs]] entry may carry only a ` +
+        `[configs.${kind}] block; this one sets ${offending.join(", ")} ` +
+        `([configs.${wrongKind}] in TOML). Move them to a ${wrongKind} prompt or ` +
+        "remove them.");
+}
+function questionError(name, detail) {
+    return `questions.${name} ${detail}`;
+}
+/** Every refusal a single decisions question can earn, or `null`. */
+function decisionsQuestionError(name, question) {
+    if (!QUESTION_NAME.test(name)) {
+        return (`questions.${name} is not a usable question name; names match ` +
+            "[A-Za-z_][A-Za-z0-9_-]* (the endpoint keys its answers by them)");
+    }
+    if (!isPlainObject(question)) {
+        return questionError(name, "must be a table declaring the question");
+    }
+    const type = question.type;
+    if (typeof type !== "string" ||
+        !DECISIONS_QUESTION_TYPES.includes(type)) {
+        return questionError(name, `needs type = one of ${DECISIONS_QUESTION_TYPES.join(" | ")}`);
+    }
+    if (!isNonEmptyString(question.instructions)) {
+        return questionError(name, "needs instructions — the sentence the model answers");
+    }
+    if (type === "choice") {
+        const criteria = question.criteria;
+        if (!isPlainObject(criteria)) {
+            return questionError(name, "is a choice question, so it needs a criteria table of option key = " +
+                "description");
+        }
+        const entries = Object.entries(criteria);
+        if (entries.length < 2) {
+            return questionError(name, "needs at least two criteria entries; a choice between one option is " +
+                "not a choice");
+        }
+        const blank = entries.find(([, value]) => !isNonEmptyString(value));
+        if (blank) {
+            return questionError(name, `criteria.${blank[0]} needs a non-empty description`);
+        }
+    }
+    // Every other key on a question — `score`'s array `criteria`, anything
+    // TypeSafe adds next — passes through; the provider validates it.
+    return null;
+}
+/**
+ * The one rule: does this (kind, provider, config) triple describe something
+ * the platform can run?
+ *
+ * `{ ok: true, kind: "chat" }` is today's behavior byte for byte. The decisions
+ * arm returns the NORMALIZED questions so the caller stores one spelling
+ * whichever transport the author used.
+ */
+export function resolvePromptKind(input) {
+    const rawKind = input.kind;
+    let kind = "chat";
+    if (!isUnset(rawKind)) {
+        const text = typeof rawKind === "string" ? rawKind.trim() : String(rawKind);
+        if (!PROMPT_KINDS.includes(text)) {
+            return {
+                ok: false,
+                error: `kind must be one of ${PROMPT_KINDS.join(" | ")}; found ` +
+                    `"${text}"`,
+            };
+        }
+        kind = text;
+    }
+    const config = input.config || {};
+    if (kind === "chat") {
+        if (!isUnset(config.questions)) {
+            return { ok: false, error: wrongBlockError("chat", ["questions"]) };
+        }
+        if (isUnset(config.userPromptTemplate)) {
+            return { ok: false, error: "userPromptTemplate is required" };
+        }
+        return { ok: true, kind: "chat" };
+    }
+    // ── decisions ──────────────────────────────────────────────────────────
+    const strayChatKeys = chatKeysSet(config);
+    if (strayChatKeys.length > 0) {
+        return { ok: false, error: wrongBlockError("decisions", strayChatKeys) };
+    }
+    const provider = typeof input.provider === "string" ? input.provider.trim().toLowerCase() : "";
+    if (provider !== "openrouter") {
+        return {
+            ok: false,
+            error: "a decisions config runs on the openrouter provider (OpenRouter's " +
+                `/api/alpha/decisions endpoint); found "${provider || "none"}"`,
+        };
+    }
+    const questions = parseQuestions(config.questions);
+    if (!questions || Object.keys(questions).length === 0) {
+        return {
+            ok: false,
+            error: "a decisions config needs questions — declare at least one under " +
+                "[configs.decisions.questions.<name>]",
+        };
+    }
+    for (const [name, question] of Object.entries(questions)) {
+        const error = decisionsQuestionError(name, question);
+        if (error)
+            return { ok: false, error };
+    }
+    return { ok: true, kind: "decisions", questions };
+}
+/**
+ * Move the deprecated flat chat keys of one `[[configs]]` entry under `chat`
+ * — #3626 §4, the blob-bucket `accessPolicy` precedent made reusable.
+ *
+ * Push keeps accepting the nine keys flat so no existing file breaks, and pull
+ * rewrites them, so one pull-then-push migrates a file. A key present in BOTH
+ * spellings is not merged: the grouped value is left standing and the key is
+ * reported in `conflicts`, which the caller turns into a refusal naming the
+ * entry. Nothing else in the entry is touched — `providerConfig` is
+ * provider-keyed rather than chat-keyed (D3626-002) and `questions` has no flat
+ * spelling at all (SO3626-013).
+ */
+export function hoistDeprecatedChatKeys(entry) {
+    if (!isPlainObject(entry)) {
+        return { entry: {}, moved: [], conflicts: [] };
+    }
+    const out = { ...entry };
+    const existingGroup = isPlainObject(out.chat) ? { ...out.chat } : undefined;
+    const group = existingGroup ?? {};
+    const moved = [];
+    const conflicts = [];
+    for (const key of CHAT_CONFIG_KEYS) {
+        if (!(key in out))
+            continue;
+        if (existingGroup && key in existingGroup) {
+            conflicts.push(key);
+            delete out[key];
+            continue;
+        }
+        group[key] = out[key];
+        delete out[key];
+        moved.push(key);
+    }
+    if (existingGroup || moved.length > 0)
+        out.chat = group;
+    return { entry: out, moved: moved.sort(), conflicts: conflicts.sort() };
+}
 // ── src/config-surface/prompt.ts ─────────────────────────────────────────
 /**
  * The `prompt` configuration object's definition (issue #2644, phase 2).
@@ -4784,6 +5123,27 @@ function geminiResolution(model, effort, budget) {
  * (`createPromptConfig` / `updatePromptConfig`) and pulls, not an opaque blob.
  */
 const PROMPT_HANDLER = "src/admin-api.ts";
+/**
+ * #3626 §4 — the nine chat keys, still accepted FLAT under `[[configs]]`.
+ *
+ * The blob-bucket `accessPolicy` precedent: declared `deprecated`, so
+ * `config push` keeps taking a file written before the `[configs.chat]` block
+ * existed, while `config pull` never writes the spelling again. One
+ * pull-then-push migrates a file. `hoistDeprecatedChatKeys` moves them into the
+ * group before the payload is built; rejecting the flat spelling outright is
+ * #3642.
+ */
+const DEPRECATED_FLAT_CHAT_KEYS = Object.fromEntries(CHAT_CONFIG_KEYS.map((key) => [
+    key,
+    {
+        kind: "deprecated",
+        note: `#3626 — the pre-kind spelling of \`[configs.chat].${key}\`. Still ` +
+            "accepted flat so no existing prompt file breaks (push hoists it " +
+            "into the block and warns); `config pull` writes only the grouped " +
+            "spelling, so one pull-then-push migrates the file. Rejecting the " +
+            "flat spelling is #3642.",
+    },
+]));
 export const PROMPT_SURFACE = {
     label: "prompt",
     tables: [
@@ -4793,6 +5153,34 @@ export const PROMPT_SURFACE = {
             model: "AppPrompt",
             // Declaration order reproduces the pre-#2644 serializer's key order.
             fields: [
+                // #3626 — WHAT this prompt runs. `chat` is today's prompt (a chat
+                // completion rendered from templates); `decisions` names OpenRouter's
+                // `/api/alpha/decisions` endpoint, which takes a `state` value plus
+                // named typed questions. It lives on the PROMPT because it decides the
+                // input envelope, the output type, the meaning of `inputSchema` /
+                // `outputSchema` and the shape of every test case's `inputVariables` —
+                // all of which are asserted per prompt KEY.
+                //
+                // `emit: "always"` so a pulled file says which kind it is; an omitted
+                // key is `chat`, so no file written before this changes meaning, and
+                // `serverDefault` is what lets push send `chat` for an absent key and
+                // `config diff` read both spellings as one value.
+                //
+                // CREATE_ONLY, and immutable in the strong sense (D3626-008): changing
+                // a prompt's kind under its key would change the contract of every
+                // caller compiled against it, so the update handler never reads it and
+                // the push gate declines the change as `immutable` — the `ttlTier`
+                // precedent. The prompt comparator projects `[prompt]` in CREATE mode
+                // for exactly that reason (SO3626-008).
+                {
+                    field: "kind",
+                    tomlKey: "kind",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    serverDefault: "chat",
+                    validation: handledBy("src/config-surface/prompt-kinds.ts", "resolvePromptKind", "apply"),
+                },
                 {
                     field: "displayName",
                     tomlKey: "displayName",
@@ -4935,6 +5323,26 @@ export const PROMPT_SURFACE = {
             tomlPath: ["configs"],
             repeated: true,
             model: "AppPromptConfig",
+            // #3626 — one block per prompt kind. A `[[configs]]` entry carries the
+            // SHARED keys flat (name, status, description, provider, model,
+            // providerConfig, plus the `active` marker) and then exactly one block,
+            // named after the prompt's kind. The rule that a config may carry only
+            // its kind's block is `resolvePromptKind`; this declaration is what makes
+            // the two blocks a property of the surface rather than of prompt-specific
+            // code, so the next kind is a group plus its fields.
+            tomlGroups: {
+                chat: {
+                    note: "#3626 — the chat-completion settings of a `kind = \"chat\"` " +
+                        "prompt: the nine keys that describe a chat call and nothing " +
+                        "else. Authored under `[configs.chat]`; the flat spelling is " +
+                        "accepted as deprecated (#3642) and rewritten by `config pull`.",
+                },
+                decisions: {
+                    note: "#3626 — the settings of a `kind = \"decisions\"` prompt: the " +
+                        "named typed questions OpenRouter's /api/alpha/decisions endpoint " +
+                        "answers. Authored under `[configs.decisions.questions.<name>]`.",
+                },
+            },
             fields: [
                 {
                     field: "configName",
@@ -4997,6 +5405,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "systemPrompt",
                     tomlKey: "systemPrompt",
+                    tomlGroup: "chat",
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5007,6 +5416,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "userPromptTemplate",
                     tomlKey: "userPromptTemplate",
+                    tomlGroup: "chat",
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5015,6 +5425,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "temperature",
                     tomlKey: "temperature",
+                    tomlGroup: "chat",
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5032,6 +5443,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "topP",
                     tomlKey: "topP",
+                    tomlGroup: "chat",
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5043,6 +5455,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "maxTokens",
                     tomlKey: "maxTokens",
+                    tomlGroup: "chat",
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5051,6 +5464,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "outputFormat",
                     tomlKey: "outputFormat",
+                    tomlGroup: "chat",
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5061,6 +5475,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "outputSchema",
                     tomlKey: "outputSchema",
+                    tomlGroup: "chat",
                     type: "json",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5089,6 +5504,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "reasoningEffort",
                     tomlKey: "reasoningEffort",
+                    tomlGroup: "chat",
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5097,11 +5513,30 @@ export const PROMPT_SURFACE = {
                 {
                     field: "reasoningBudget",
                     tomlKey: "reasoningBudget",
+                    tomlGroup: "chat",
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
                     validation: handledBy("src/config-surface/prompt-reasoning.ts", "resolvePromptReasoning", "apply"),
                 },
+                // #3626 — the named typed questions a DECISIONS config asks. A `json`
+                // field like `outputSchema`: stored as a JSON string, returned parsed,
+                // and authored either as nested tables
+                // (`[configs.decisions.questions.category]`) or as a JSON string.
+                //
+                // It has no flat spelling at all — `acceptedTomlKeys` refuses it at the
+                // `[[configs]]` root and names the block it belongs under (SO3626-013),
+                // because the payload builder reads a grouped field only from its
+                // group and a flat value would otherwise be dropped in silence.
+                {
+                    field: "questions",
+                    tomlKey: "questions",
+                    tomlGroup: "decisions",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy("src/config-surface/prompt-kinds.ts", "resolvePromptKind", "apply"),
+                },
             ],
             notExposed: {
                 configId: {
@@ -5162,6 +5597,8 @@ export const PROMPT_SURFACE = {
                         "rejection does not fail a file that has always used it; pull " +
                         "never writes it.",
                 },
+                // #3626 §4 — the nine chat keys in their pre-kind FLAT spelling.
+                ...DEPRECATED_FLAT_CHAT_KEYS,
             },
             responseOnlyKeys: {},
         },
@@ -8138,6 +8575,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "promptId",
         "appId",
         "promptKey",
+        "kind",
         "displayName",
         "description",
         "copiedFromCatalogId",
@@ -8170,6 +8608,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "outputFormat",
         "outputSchema",
         "providerConfig",
+        "questions",
         "reasoningEffort",
         "reasoningBudget",
         "status",