primitive-admin 1.1.0-alpha.64 → 1.1.0-alpha.65

package/dist/src/lib/generated-config-surfaces.d.ts

@@ -494,6 +494,12 @@ export declare function requestSchemaKeys(table: ConfigTable, mode: "create" | "
  * is no place to write one.
  */
 export declare function configRequestSchema(table: ConfigTable, mode: "create" | "update"): ConfigRequestSchema;
+/**
+ * The retired-key guidance for a generated schema, keyed by body key — or
+ * `undefined` when the schema's object has none. Consumed by the app API's
+ * request validator (`src/app-api/request-validation.ts`).
+ */
+export declare function retiredRequestKeys(schema: object | undefined): Readonly<Record<string, string>> | undefined;
 /**
  * One schema for an endpoint whose body spans MORE than one table.
  *
@@ -512,6 +518,33 @@ export declare function mergeRequestSchemas(...schemas: readonly ConfigRequestSc
 export declare function unknownRequestKeys(body: unknown, table: ConfigTable, mode: "create" | "update"): string[];
 /** The 400 message naming the unknown key(s), shared by both APIs. */
 export declare function unknownRequestKeysMessage(keys: readonly string[]): string;
+/**
+ * Keys deliberately RETIRED from a configuration object's write surface.
+ *
+ * A retired key is not an unknown key. The generic hint for an unrecognized
+ * TOML key — "check the spelling, or upgrade the CLI" — is exactly backwards
+ * for one this CLI removed on purpose, and the generic 400 for an unaccepted
+ * request key says only that the key is not allowed, not where the value moved
+ * to. Both surfaces need the same sentence, and neither should invent it.
+ *
+ * So the guidance lives here, next to the definitions, with one entry per
+ * retired key: the TOML wording for `config push` (which can tell the author to
+ * delete a line) and the request wording for the API handlers (which cannot).
+ *
+ * Keyed by the table's TOML path prefix (`workflow`, `cronTrigger`, …), because
+ * that is the identifier both consumers already have in hand.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ */
+export interface RetiredConfigKey {
+    /** What `config push` says about a file that still carries the key. */
+    toml: string;
+    /** What a create/update handler says about a body that still sends it. */
+    request: string;
+}
+export declare const RETIRED_CONFIG_KEYS: Record<string, Record<string, RetiredConfigKey>>;
+/** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
+export declare function retiredConfigKey(prefix: string, key: string): RetiredConfigKey | null;
 export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;

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

@@ -508,7 +508,55 @@ export function configRequestSchema(table, mode) {
     for (const key of requestSchemaKeys(table, mode)) {
         properties[key] = {};
     }
-    return { type: "object", properties, additionalProperties: false };
+    const schema = {
+        type: "object",
+        properties,
+        additionalProperties: false,
+    };
+    rememberRetiredKeys(schema, RETIRED_CONFIG_KEYS[table.tomlPath[0]]);
+    return schema;
+}
+/**
+ * Retired-key guidance carried BESIDE a generated schema, not inside it
+ * (issue #2803, second opinion).
+ *
+ * A route that opts into runtime validation is validated before its handler
+ * runs, so a handler's targeted "`status` is server-owned, use
+ * `<noun> enable|disable`" refusal never fired for the app-API webhook and cron
+ * routes: `additionalProperties: false` answered first, with the generic
+ * "Request body validation failed". The guidance has to reach the validator.
+ *
+ * It travels in a side table rather than as a schema keyword because the schema
+ * object IS the OpenAPI `meta.request` and is held to a fail-closed keyword
+ * allowlist (`RUNTIME_SUPPORTED_SCHEMA_KEYWORDS`) — an invented keyword would
+ * be published in the spec and would fail that guard. Keying on the schema's
+ * identity also means the guidance cannot drift: it is attached by the same
+ * call that builds the key set, so a route cannot opt into one without the
+ * other.
+ */
+const retiredKeyGuidance = new WeakMap();
+function rememberRetiredKeys(schema, retired) {
+    if (!retired)
+        return;
+    const entries = {};
+    for (const [key, entry] of Object.entries(retired)) {
+        // A key the schema ACCEPTS is not retired on this surface, whatever the
+        // TOML surface says about it. The accepted key set wins, so the guidance
+        // can never shadow a live field.
+        if (key in schema.properties)
+            continue;
+        entries[key] = entry.request;
+    }
+    if (Object.keys(entries).length > 0)
+        retiredKeyGuidance.set(schema, entries);
+}
+/**
+ * The retired-key guidance for a generated schema, keyed by body key — or
+ * `undefined` when the schema's object has none. Consumed by the app API's
+ * request validator (`src/app-api/request-validation.ts`).
+ */
+export function retiredRequestKeys(schema) {
+    return schema ? retiredKeyGuidance.get(schema) : undefined;
 }
 /**
  * One schema for an endpoint whose body spans MORE than one table.
@@ -524,7 +572,22 @@ export function mergeRequestSchemas(...schemas) {
         for (const key of Object.keys(schema.properties))
             properties[key] = {};
     }
-    return { type: "object", properties, additionalProperties: false };
+    // The union's guidance is the union of its halves'. A key one table retired
+    // and another accepts is admitted by the merged key set, so `rememberRetiredKeys`
+    // drops it below.
+    const retired = {};
+    for (const schema of schemas) {
+        for (const [key, request] of Object.entries(retiredRequestKeys(schema) ?? {})) {
+            retired[key] = { request };
+        }
+    }
+    const merged = {
+        type: "object",
+        properties,
+        additionalProperties: false,
+    };
+    rememberRetiredKeys(merged, retired);
+    return merged;
 }
 /**
  * The body keys `table` does not accept in `mode` — the 400's subject.
@@ -546,6 +609,90 @@ export function unknownRequestKeysMessage(keys) {
         `${keys.join(", ")}. This endpoint rejects keys it does not accept rather ` +
         "than ignoring them.");
 }
+export const RETIRED_CONFIG_KEYS = {
+    // #2645 — pausing moved off `state` onto its own field, so `state` stopped
+    // being author-writable rather than becoming a second way to say "paused".
+    // Every pre-#2645 pull wrote the line, so existing repos hit this on their
+    // first push after upgrading: the failure is deliberate (sponsor decision at
+    // the approval gate, 2026-08-15), because the line has to be removed, not
+    // silently ignored, or the file keeps claiming a pause state push does not
+    // apply.
+    cronTrigger: {
+        state: {
+            toml: "`state` is no longer authored in TOML (#2645), and #2803 replaced it " +
+                "with the server-owned `status`. Availability is " +
+                "`primitive cron-triggers enable|disable`. Delete the line and push " +
+                "again.",
+            request: "`state` is server-owned and superseded by `status` (#2645, #2803). " +
+                "Use `primitive cron-triggers enable|disable` to change availability.",
+        },
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive cron-triggers enable|disable`. " +
+                "Delete the line and push again.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive cron-triggers enable|disable` to change availability.",
+        },
+    },
+    // #2803 — the OBJECT-level availability leaves TOML. The per-version
+    // `[[configs]] status` (`active | archived`) is a different question — which
+    // named config is retired — and stays authorable.
+    prompt: {
+        status: {
+            toml: "`[prompt].status` is no longer authored in TOML (#2803). " +
+                "Availability is server-owned: use `primitive prompts enable|disable`. " +
+                "Delete the line and push again — the per-config `[[configs]] status` " +
+                "is unaffected.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive prompts enable|disable` to change availability.",
+        },
+    },
+    integration: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803), and `draft` no longer " +
+                "exists. Availability is server-owned: use " +
+                "`primitive integrations enable|disable`. Delete the line and push " +
+                "again. If this file describes an ARCHIVED integration, delete the " +
+                "file instead — pull no longer exports tombstones, and the next " +
+                "confirmed `config push --prune` hard-deletes the row.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive integrations enable|disable` to change availability.",
+        },
+    },
+    // #2803 — availability is one server-owned `status`. As a TOML key it made
+    // `config push` a second writer: pushing a file pulled before an operator ran
+    // `webhooks disable` put the endpoint back in service as a side effect. The
+    // tenant app-API create/update also stored the value UNVALIDATED, so any app
+    // admin could write any string into the field the receiver gates on.
+    webhook: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive webhooks enable|disable`. Delete the " +
+                "line and push again. If this file describes an ARCHIVED webhook, " +
+                "delete the file instead — pull no longer exports tombstones, and the " +
+                "next confirmed `config push --prune` hard-deletes the row, freeing " +
+                "its slot and its key.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive webhooks enable|disable` to change availability.",
+        },
+    },
+    // #2803 — availability is one server-owned `status`. As a TOML key it made
+    // `config push` a second writer: pushing a file pulled before an operator ran
+    // `workflows disable` put the workflow back in service as a side effect.
+    workflow: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive workflows enable|disable`. " +
+                "Delete the line and push again.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive workflows enable|disable` to change availability.",
+        },
+    },
+};
+/** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
+export function retiredConfigKey(prefix, key) {
+    return RETIRED_CONFIG_KEYS[prefix]?.[key] ?? null;
+}
 // ── src/config-surface/workflow.ts ───────────────────────────────────────
 /**
  * The `workflow` configuration object's definition (issue #2644, phase 1).
@@ -610,14 +757,6 @@ export const WORKFLOW_SURFACE = {
                     writableOn: BOTH,
                     validation: handler("normalizeWorkflowDescription"),
                 },
-                {
-                    field: "status",
-                    tomlKey: "status",
-                    type: "string",
-                    emit: "always",
-                    writableOn: BOTH,
-                    validation: handler("normalizeWorkflowStatus"),
-                },
                 {
                     field: "accessRule",
                     tomlKey: "accessRule",
@@ -705,6 +844,20 @@ export const WORKFLOW_SURFACE = {
                     kind: "server-owned",
                     note: "ULID assigned on create; never author-authored.",
                 },
+                // #2803 — `status` is the ONE availability control and it is
+                // server-owned. It used to be a `[workflow]` key, which made `config
+                // push` a second writer: pushing a file pulled before an operator ran
+                // `workflows disable` put the workflow back in service as a side
+                // effect. `server-owned` keeps it out of both the TOML surface and the
+                // create/update request schemas, so the only writers are
+                // `workflows enable|disable` and create (which assigns `active`).
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803). Written only by `workflows enable|disable` " +
+                        "and by create, which always assigns `active`. Never authored in " +
+                        "TOML: `config pull` does not emit it and a file that still " +
+                        "carries the key fails push (RETIRED_TOML_KEYS).",
+                },
                 // #2645 criterion 9 — the operational toggle. Configuration is
                 // authored in TOML and applied with `config push`, so anything this
                 // table exposes has the repo as its single writer. Taking a workflow
@@ -909,14 +1062,6 @@ export const PROMPT_SURFACE = {
                     writableOn: BOTH,
                     validation: "passthrough",
                 },
-                {
-                    field: "status",
-                    tomlKey: "status",
-                    type: "string",
-                    emit: "always",
-                    writableOn: BOTH,
-                    validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
-                },
                 // JSON Schema objects. Stored as JSON strings, returned parsed; TOML
                 // may present them as an inline table or a JSON string.
                 {
@@ -957,6 +1102,17 @@ export const PROMPT_SURFACE = {
                     kind: "server-owned",
                     note: "ULID assigned on create; never author-authored.",
                 },
+                // #2803 — the OBJECT-level availability, server-owned. Distinct from
+                // the per-version `[[configs]] status` below, which stays a TOML key:
+                // that says which named config is retired, this says whether the
+                // prompt is in service at all.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive. Written only by " +
+                        "`prompts enable|disable` and by create, which always assigns " +
+                        "`active`. Never authored in TOML; the per-version " +
+                        "`[[configs]] status` is unaffected.",
+                },
                 appId: {
                     kind: "server-owned",
                     note: "Tenant scope, taken from the route; never on the wire.",
@@ -1260,15 +1416,6 @@ export const INTEGRATION_SURFACE = {
                     writableOn: BOTH,
                     validation: "passthrough",
                 },
-                {
-                    field: "status",
-                    tomlKey: "status",
-                    type: "string",
-                    emit: "always",
-                    writableOn: BOTH,
-                    // draft | active | archived, rejected with a 400 naming the set.
-                    validation: handledBy(INTEGRATION_HANDLER, "AdminAPI"),
-                },
                 {
                     field: "timeoutMs",
                     tomlKey: "timeoutMs",
@@ -1304,6 +1451,15 @@ export const INTEGRATION_SURFACE = {
                     kind: "server-owned",
                     note: "ULID assigned on create; never author-authored.",
                 },
+                // #2803 — availability, server-owned. `draft` is gone from the model;
+                // a stored one reads `inactive` through the canonical normalizer.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `integrations enable|disable`, by the delete flow's tombstone, " +
+                        "and by create, which always assigns `active`. Never authored in " +
+                        "TOML: pull does not emit it and pull skips archived rows.",
+                },
                 appId: {
                     kind: "server-owned",
                     note: "Tenant scope, taken from the route; never on the wire.",
@@ -1422,15 +1578,6 @@ export const WEBHOOK_SURFACE = {
                     writableOn: BOTH,
                     validation: "passthrough",
                 },
-                {
-                    field: "status",
-                    tomlKey: "status",
-                    type: "string",
-                    emit: "always",
-                    writableOn: BOTH,
-                    // active | paused; `archived` is reserved for soft-delete.
-                    validation: handledBy(WEBHOOK_HANDLER, "AdminAPI"),
-                },
                 {
                     field: "workflowKey",
                     tomlKey: "workflowKey",
@@ -1507,6 +1654,19 @@ export const WEBHOOK_SURFACE = {
                     kind: "server-owned",
                     note: "ULID assigned on create; never author-authored.",
                 },
+                // #2803 — availability is server-owned. As a `[webhook]` key it made
+                // `config push` a second writer: a file pulled before an operator
+                // paused the webhook put the endpoint back in service on the next
+                // push. `server-owned` keeps it out of the TOML surface AND out of the
+                // create/update request schemas, closing the tenant app-API path that
+                // stored `body.status` unvalidated.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `webhooks enable|disable` and by the delete flow's tombstone. " +
+                        "Never authored in TOML: pull does not emit it, pull skips " +
+                        "archived rows entirely, and a file carrying the key fails push.",
+                },
                 appId: {
                     kind: "server-owned",
                     note: "Tenant scope, taken from the route; never on the wire.",
@@ -1712,29 +1872,37 @@ export const CRON_TRIGGER_SURFACE = {
                 },
             ],
             notExposed: {
-                // #2645 criterion 9 — pause moved off `state` onto the
-                // `operationallyDisabled` toggle. `state` keeps the lifecycle values
-                // the server owns (active / error_paused / archived) and is no longer
-                // part of the TOML surface: pull does not emit it and push does not
-                // apply it, so a push can never resume a trigger an operator paused.
-                // `structural` with update-only requestModes, matching the handlers:
-                // the update handler still reads a supplied `state` (the console
-                // remains a config-editing surface by product decision), while create
-                // assigns "active" itself and must keep rejecting the key rather than
-                // silently dropping it.
+                // #2803 — the ONE availability control, server-owned. Written only by
+                // `cron-triggers enable|disable`, the delete flow (the `archived`
+                // tombstone) and the alarm's error-pause path. `server-owned` keeps it
+                // out of both the TOML surface and the create/update request schemas,
+                // so no configuration write can change availability as a side effect.
+                status: {
+                    kind: "server-owned",
+                    note: "Availability (#2803): active | inactive | archived. Written only " +
+                        "by `cron-triggers enable|disable`, the delete flow and the " +
+                        "error-pause path. Never authored in TOML: pull does not emit it " +
+                        "and a file that still carries the key fails push.",
+                },
+                // #2645 criterion 9 moved pausing off `state`; #2803 retired the field
+                // entirely. It mixed lifecycle (`archived`, `error_paused`) with
+                // availability (`paused`), which is what made two writers possible in
+                // the first place. `server-owned` now, not `structural` with an
+                // update-only mode: the console's carve-out is gone with it, so the
+                // generic update rejects a supplied `state` exactly as create always
+                // did.
                 state: {
-                    kind: "structural",
-                    requestModes: ["update"],
-                    note: "Lifecycle state (active | paused | error_paused | archived). " +
-                        "Still accepted on update for the console; pausing from the CLI " +
-                        "is `cron-triggers pause|resume`, which writes " +
-                        "`operationallyDisabled` instead (#2645). Not authored in TOML.",
+                    kind: "server-owned",
+                    note: "DEPRECATED (#2803), superseded by `status`. Read only by " +
+                        "`canonicalCronStatus()`; normalized back to `active` by " +
+                        "`cron-triggers enable`. Never authored in TOML and never accepted " +
+                        "on the wire.",
                 },
                 operationallyDisabled: {
                     kind: "server-owned",
-                    note: "Operational toggle (#2645). Written only by the pause/resume " +
-                        "endpoints (`cron-triggers pause|resume`); read by the cron tick. " +
-                        "Never authored in TOML and never accepted on the config " +
+                    note: "DEPRECATED (#2803), superseded by `status`. The #2645 operational " +
+                        "toggle, cleared by `cron-triggers enable|disable` as rows are " +
+                        "touched. Never authored in TOML and never accepted on the config " +
                         "create/update wire.",
                 },
                 triggerId: {
@@ -3031,6 +3199,21 @@ export const APP_SETTINGS_SURFACE = {
                     writableOn: UPDATE_ONLY,
                     validation: "passthrough",
                 },
+                {
+                    field: "directLlmEnabled",
+                    tomlKey: "directLlmEnabled",
+                    type: "boolean",
+                    // Always emitted: an app that has not opted the deprecated direct
+                    // LLM/Gemini proxy in must see `directLlmEnabled = false` in its
+                    // pulled `app.toml`, not a key it has to already know about (#2687).
+                    emit: "always",
+                    writableOn: UPDATE_ONLY,
+                    // STRICT, not `!!`: the value arms a credit-spending surface read
+                    // with `=== true`, so `"false"` must be a 400 rather than a stored
+                    // `true`. The generated request schema stays keys-only (#1976), so
+                    // the check is `parseDirectLlmEnabledWrite` in the handler.
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
                 {
                     field: "allowedDomains",
                     tomlKey: "allowedDomains",
@@ -3407,6 +3590,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "magicLinkEnabled",
         "otpEnabled",
         "baseUrl",
+        "directLlmEnabled",
         "memberInvitationsEnabled",
         "memberInvitationLimit",
         "createdAt",
@@ -3554,6 +3738,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "overlapPolicy",
         "rootInput",
         "inputMapping",
+        "status",
         "state",
         "operationallyDisabled",
         "lastError",