primitive-admin 1.0.61 → 1.0.63

package/dist/src/lib/config-object-descriptor.js

@@ -0,0 +1,658 @@
+/**
+ * The configuration-object descriptor registry (issue #2645).
+ *
+ * Server-side configuration is authored in TOML and applied with `config push`.
+ * That makes the TOML field surface the thing an operator has to discover, so
+ * it needs a machine-readable definition — the job per-flag `--help` used to do.
+ * This registry is that definition, and it drives four commands:
+ *
+ *   - `config fields <type>`      lists a type's keys, types, required, default
+ *   - `config create <type> <key>`   scaffolds the type's file from `scaffold()`
+ *   - `config set <type>/<key>`   validates the dotted path being edited
+ *   - `config push --only <sel>`  resolves a selector to a type + key
+ *
+ * ── Deliberately a descriptor, never reflection ──────────────────────────
+ * The field list is declared here, not inferred from the pull serializers in
+ * `commands/sync.ts`. Reflection over emitted keys cannot report `required` or
+ * `default`, and an implicit field surface is exactly the drift #2644 exists to
+ * end. The workflow key set is CONSUMED from #2644's vendored definition
+ * (`config-surface.ts` / `generated-config-surfaces.ts`) and the app settings
+ * from `app-settings-descriptor.ts`, rather than restated, so there is still
+ * one definition per field.
+ *
+ * ── Drift guard ──────────────────────────────────────────────────────────
+ * `cli/tests/unit/config-object-descriptor.test.ts` cross-checks the registry
+ * against `SYNC_RESOURCE_TYPES` (every per-entity type has exactly one
+ * descriptor) and `PUSH_PRUNE_SPECS` (the declared identity path is a real
+ * field), and asserts each scaffold parses and carries every required field. A
+ * new sync resource type therefore fails a test rather than silently
+ * under-reporting from `config fields`.
+ *
+ * ── Relationship to #2644 ────────────────────────────────────────────────
+ * #2644 defines one shared field definition across the server, the TOML surface
+ * and CLI validation. These descriptors are sized to be ABSORBED by it: they
+ * carry only what the four commands above need, and no validation behavior.
+ */
+import { APP_SETTINGS_DESCRIPTOR, } from "./app-settings-descriptor.js";
+import { WORKFLOW_TABLE } from "./config-surface.js";
+import { SYNC_RESOURCE_TYPES, } from "./sync-resource-types.js";
+/** The identity path a descriptor declares, or `undefined` when keyed by filename. */
+export function describedIdentityPath(descriptor) {
+    return descriptor.identity;
+}
+function resourceType(label) {
+    const found = SYNC_RESOURCE_TYPES.find((t) => t.label === label);
+    if (!found)
+        throw new Error(`no sync resource type '${label}'`);
+    return found;
+}
+/** Shorthand for a descriptor field. */
+function f(path, type, description, options = {}) {
+    return {
+        path,
+        type,
+        description,
+        required: !!options.required,
+        ...(options.default === undefined ? {} : { default: options.default }),
+    };
+}
+/** TOML text for a table of `key = value` lines, with a leading header. */
+function tomlSection(header, lines) {
+    return [`[${header}]`, ...lines].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Derived field lists — consumed from the existing descriptors, not restated.
+// ---------------------------------------------------------------------------
+/** Human-readable one-liners for the `[workflow]` keys. */
+const WORKFLOW_FIELD_NOTES = {
+    name: "Display name",
+    description: "What the workflow does",
+    inputSchema: "JSON Schema for the workflow input",
+    outputSchema: "JSON Schema for the workflow output",
+    perUserMaxRunning: "Concurrent runs allowed per user",
+    perUserMaxQueued: "Queued runs allowed per user",
+    perAppMaxRunning: "Concurrent runs allowed across the app",
+    perAppMaxQueued: "Queued runs allowed across the app",
+    queueTtlSeconds: "How long a queued run stays eligible",
+    dequeueOrder: "fifo | lifo",
+    requiresClientApply: "Client must apply the result before the run completes",
+    syncCallable: "Callable synchronously by clients",
+    templateMissingMarker: "Emit a marker when a template variable is missing",
+    accessRule: "CEL expression deciding who may run the workflow",
+    runAs: "Identity the run executes as",
+    lock: "Run-scoped lock declaration",
+    capabilities: "Capabilities the workflow is granted",
+};
+const WORKFLOW_FIELD_TYPES = {
+    string: "string",
+    number: "number",
+    boolean: "boolean",
+    "string[]": "string[]",
+    json: "json",
+};
+/**
+ * What the server assumes when a `[workflow]` key is absent.
+ *
+ * The vendored `WORKFLOW_TABLE` (#2644) carries key set and value shape but
+ * not defaults, so the defaults are stated here, next to the other types'.
+ * They are not free text: the `models.yaml` `WorkflowDefinition` defaults are
+ * the source of truth, and
+ * `cli/tests/unit/config-object-descriptor.test.ts` parses that model and fails
+ * when a default here disagrees or a newly-defaulted field is missing. Without
+ * them `config fields workflow` reported `default null` for the queueing and
+ * dispatch knobs — the command that replaced per-flag `--help` under-reporting
+ * exactly what the removed flags used to document (issue #2645).
+ *
+ * Exported because `config diff`'s workflow comparator needs exactly this table
+ * to normalize omitted-vs-defaulted fields, and kept a hand-mirrored second
+ * copy of it until #2731. Two tables can disagree; a guarded one cannot go
+ * stale unnoticed.
+ */
+export const WORKFLOW_FIELD_DEFAULTS = {
+    perUserMaxRunning: 4,
+    perUserMaxQueued: 100,
+    perAppMaxRunning: 25,
+    perAppMaxQueued: 10000,
+    queueTtlSeconds: 43200,
+    dequeueOrder: "fifo",
+    requiresClientApply: true,
+    syncCallable: false,
+};
+const WORKFLOW_FIELDS = [
+    f("workflow.key", "string", "Workflow key — defaults to the file name", {
+        required: true,
+    }),
+    ...WORKFLOW_TABLE.fields.map((d) => f(`workflow.${d.tomlKey}`, WORKFLOW_FIELD_TYPES[d.type] ?? "string", WORKFLOW_FIELD_NOTES[d.tomlKey] ?? d.tomlKey, {
+        required: d.tomlKey === "name",
+        default: WORKFLOW_FIELD_DEFAULTS[d.tomlKey],
+    })),
+    f("steps", "table[]", "The workflow's steps, in order", { required: true }),
+    // Under `[workflow]`, not at the root: that is where `serializeWorkflow`
+    // emits it and where the push leg reads it from. A root-level path here made
+    // `config set workflow/<key> activeConfigName=<name>` write a key push ignores,
+    // so the scriptable activation path silently did nothing (issue #2645).
+    f("workflow.activeConfigName", "string", "Which named config under workflows/<key>.configs/ is live"),
+];
+/**
+ * The `[test]` surface of a test-case sidecar (#2769), declared ONCE and
+ * attached to each of the four blocks that carry tests.
+ *
+ * With `tests create|update|delete` gone, this is where the field list is
+ * discoverable. The spellings are the authored ones: the three references are
+ * NAMES (resolved to ids at push time, which is what makes a sidecar portable
+ * across apps), and the three JSON fields carry JSON text.
+ */
+const TEST_CASE_COMPANION_FIELDS = [
+    f("test.name", "string", "Test case name; the file name is its slug", {
+        required: true,
+    }),
+    f("test.description", "string", "What the case checks"),
+    // #2968 — the one place a case author can ask what may go in here, so it
+    // names the integration request surface rather than splitting the shared list.
+    f("test.inputVariables", "string", "JSON text of the input variables; an integration case's variables ARE its " +
+        "request (method, path, headers, query, body — or form, or bodyMode with " +
+        "multipartFields); an absent method uses requestConfig.defaultMethod, an " +
+        "absent path is /, headers/query merge with the configured ones, an " +
+        "absent bodyMode uses requestConfig.bodyMode, multipartFields merge with " +
+        "requestConfig.multipartFieldMapping by field name, and an " +
+        "unauthored body is no body"),
+    f("test.configName", "string", "Name of the config this case is pinned to"),
+    f("test.evaluatorPromptKey", "string", "Key of the judge prompt, when scored by one"),
+    f("test.evaluatorConfigName", "string", "Name of the judge prompt's config"),
+    f("test.expectedOutputPattern", "string", "Regex the output must match"),
+    f("test.expectedOutputContains", "string", "JSON text: array of required phrases"),
+    f("test.expectedJsonSubset", "string", "JSON text: object deep-matched against the output"),
+];
+/** One owner's `<key>.tests/` companion entry (#2769). */
+function testCaseCompanion(fileHint, attachmentHint) {
+    return {
+        fileHint,
+        description: "One test case for this block; the directory beside the file " +
+            `(${attachmentHint}) holds its attachments. An empty spelling ("", "{}", ` +
+            '"[]") clears the field on push; removing the file and running ' +
+            "`config push --prune` deletes the case",
+        fields: TEST_CASE_COMPANION_FIELDS,
+    };
+}
+/**
+ * The named-config sidecar surface (issue #2645, spec §Contracts/Named configs).
+ *
+ * `workflows configs create/update/duplicate/archive/activate` are gone, so
+ * these keys are the whole of what used to be their flags. Listing them under
+ * the workflow rather than as their own `config fields` type keeps one type per
+ * pushable object — a sidecar is part of a workflow, not a thing you can push
+ * on its own — while still answering "what may this file contain?", which is
+ * the question criterion 7 exists for. The config's NAME is the file name and
+ * is deliberately absent from the list: it is not a key of the file.
+ */
+const WORKFLOW_COMPANION_FILES = [
+    {
+        fileHint: "workflows/<key>.configs/<name>.toml",
+        description: "One of the workflow's named configs; <name> is its name, and workflow.activeConfigName says which is live",
+        fields: [
+            f("config.description", "string", "What this config is tuned for"),
+            f("config.status", "string", "draft | active | archived"),
+            f("steps", "table[]", "This config's steps, in order", {
+                required: true,
+            }),
+            f("expr.cel", "table", "Named CEL guards travelling with these steps"),
+        ],
+    },
+    testCaseCompanion("workflows/<key>.tests/<name>.toml", "workflows/<key>.tests/<name>/"),
+];
+const APP_SETTING_TYPES = {
+    string: "string",
+    boolean: "boolean",
+    number: "number",
+    "string[]": "string[]",
+    object: "table",
+};
+const APP_FIELDS = APP_SETTINGS_DESCRIPTOR.map((d) => f(`${d.section}.${d.key}`, APP_SETTING_TYPES[d.type], `App setting ${d.field}`, { required: false }));
+// ---------------------------------------------------------------------------
+// The registry.
+// ---------------------------------------------------------------------------
+export const CONFIG_OBJECT_DESCRIPTORS = [
+    {
+        type: "integration",
+        resourceType: resourceType("integration"),
+        fileHint: "integrations/<key>.toml",
+        identity: "integration.key",
+        description: "An outbound HTTP integration a workflow step can call",
+        fields: [
+            f("integration.key", "string", "Integration key", { required: true }),
+            f("integration.displayName", "string", "Display name", { required: true }),
+            f("integration.description", "string", "What the integration calls"),
+            f("integration.timeoutMs", "number", "Request timeout in milliseconds"),
+            f("integration.accessRule", "string", 'CEL expression deciding who may call it; absent denies every non-admin caller (use "true" to allow any app member)'),
+            f("requestConfig", "table", "Method, URL, headers and body template", {
+                required: true,
+            }),
+        ],
+        companionFiles: [
+            testCaseCompanion("integrations/<key>.tests/<name>.toml", "integrations/<key>.tests/<name>/"),
+        ],
+        scaffold: (key) => [
+            tomlSection("integration", [
+                `key = "${key}"`,
+                `displayName = "${key}"`,
+                // #2803 — no `status` line: availability is server-owned, a pushed
+                // file carrying the key is rejected, and a new object is active.
+                `# CEL expression deciding who may call this integration.`,
+                `# With no rule, every caller who is not an app admin or owner is denied.`,
+                `accessRule = "true"`,
+            ]),
+            "",
+            tomlSection("requestConfig", [
+                `method = "GET"`,
+                `url = "https://example.com/"`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "webhook",
+        resourceType: resourceType("webhook"),
+        fileHint: "webhooks/<key>.toml",
+        identity: "webhook.key",
+        description: "An inbound webhook endpoint that starts a workflow",
+        fields: [
+            f("webhook.key", "string", "Webhook key", { required: true }),
+            f("webhook.displayName", "string", "Display name", { required: true }),
+            f("webhook.description", "string", "What sends to this endpoint"),
+            f("webhook.workflowKey", "string", "Workflow the delivery starts", {
+                required: true,
+            }),
+            f("webhook.verificationScheme", "string", "How a delivery's signature is verified", { default: "none" }),
+            f("webhook.signingSecret", "string", 'A `{{secrets.KEY}}` reference — never the secret itself'),
+            f("webhook.toleranceSeconds", "number", "Signature timestamp tolerance"),
+            f("webhook.deduplicationEnabled", "boolean", "Drop repeated delivery ids"),
+            f("webhook.deduplicationWindowMs", "number", "Deduplication window"),
+            f("webhook.maxBodyBytes", "number", "Inbound body cap; unset keeps 5 MiB"),
+            f("webhook.secretGracePeriodMs", "number", "How long the previous signing secret stays valid after a rotate"),
+            f("allowedIps.cidrs", "string[]", "CIDR ranges allowed to deliver"),
+            f("inputMapping", "table", "Maps the delivery body onto the workflow input"),
+            f("metadata", "table", "Free-form metadata carried with each delivery"),
+            f("verification", "table", "Per-scheme verification settings, e.g. [verification.jwt]"),
+        ],
+        scaffold: (key) => [
+            tomlSection("webhook", [
+                `key = "${key}"`,
+                `displayName = "${key}"`,
+                // #2803 — no `status` line: availability is server-owned, a pushed
+                // file carrying the key is rejected, and a new webhook is active.
+                `# The workflow a delivery starts.`,
+                `workflowKey = ""`,
+                `verificationScheme = "none"`,
+                `# Signing secrets are references, never literals:`,
+                `# signingSecret = "{{secrets.MY_WEBHOOK_SECRET}}"`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "cron-trigger",
+        resourceType: resourceType("cron-trigger"),
+        fileHint: "cron-triggers/<key>.toml",
+        identity: "cronTrigger.key",
+        description: "A schedule that starts a workflow",
+        fields: [
+            f("cronTrigger.key", "string", "Trigger key", { required: true }),
+            f("cronTrigger.displayName", "string", "Display name", { required: true }),
+            f("cronTrigger.description", "string", "What the schedule is for"),
+            f("cronTrigger.cron", "string", "Cron expression", { required: true }),
+            f("cronTrigger.timezone", "string", "IANA timezone", { default: "UTC" }),
+            f("cronTrigger.workflowKey", "string", "Workflow the tick starts", {
+                required: true,
+            }),
+            f("cronTrigger.overlapPolicy", "string", "skip | allow", {
+                default: "skip",
+            }),
+            // #2645 criterion 9 — `cronTrigger.state` used to live here. Pausing a
+            // trigger wrote `state`, and so did `config push`, which made two writers
+            // for one piece of state. Pause state moved to the `operationallyDisabled`
+            // runtime toggle (`cron-triggers pause|resume`), and `state` went back to
+            // being server-owned lifecycle, so there is no `state` key to author.
+            f("rootInput", "table", "Static input passed to every run"),
+            f("inputMapping", "table", "Maps the tick onto the workflow input"),
+        ],
+        scaffold: (key) => [
+            tomlSection("cronTrigger", [
+                `key = "${key}"`,
+                `displayName = "${key}"`,
+                `# Minute hour day month weekday`,
+                `cron = "0 * * * *"`,
+                `timezone = "UTC"`,
+                `workflowKey = ""`,
+                `overlapPolicy = "skip"`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "blob-bucket",
+        resourceType: resourceType("blob-bucket"),
+        fileHint: "blob-buckets/<key>.toml",
+        identity: "bucket.key",
+        description: "A blob storage bucket and its access model",
+        fields: [
+            f("bucket.key", "string", "Bucket key", { required: true }),
+            f("bucket.name", "string", "Display name", { required: true }),
+            f("bucket.description", "string", "What the bucket holds"),
+            // Required, and immutable once the bucket exists: the create endpoint
+            // rejects a missing or unknown tier (`blob-buckets-controller.ts`,
+            // VALID_TTL_TIERS), and the tier is part of the R2 key prefix, so it can
+            // never be changed afterwards. Reporting it as optional — and scaffolding
+            // a file without it — left `config create blob-bucket <key>` producing a file
+            // whose first push 400s (issue #2645).
+            f("bucket.ttlTier", "string", "Retention tier: 1d | 3d | 14d | 28d | 180d | 365d | permanent; immutable once the bucket exists", { required: true }),
+            f("bucket.preset", "string", "Access preset: public | authenticated | admin-only | personal-uploads; mutually exclusive with accessPolicy and ruleSetId"),
+            f("bucket.accessPolicy", "string", "Inline access policy; mutually exclusive with preset"),
+            f("bucket.ruleSetId", "string", "Rule set governing access"),
+        ],
+        scaffold: (key) => [
+            tomlSection("bucket", [
+                `key = "${key}"`,
+                `name = "${key}"`,
+                `# Retention tier, fixed at creation: 1d, 3d, 14d, 28d, 180d, 365d or permanent.`,
+                `ttlTier = "permanent"`,
+                `# One of preset, accessPolicy or ruleSetId decides who may read and write.`,
+                `# Presets: public, authenticated, admin-only, personal-uploads.`,
+                `preset = "admin-only"`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "prompt",
+        resourceType: resourceType("prompt"),
+        fileHint: "prompts/<key>.toml",
+        identity: "prompt.key",
+        description: "An LLM prompt and its named model configs",
+        fields: [
+            f("prompt.key", "string", "Prompt key", { required: true }),
+            f("prompt.displayName", "string", "Display name", { required: true }),
+            f("prompt.description", "string", "What the prompt is for"),
+            f("prompt.inputSchema", "json", "JSON Schema for the prompt input"),
+            f("prompt.outputSchema", "json", "JSON Schema for the prompt output"),
+            f("configs", "table[]", "Named model configs", { required: true }),
+            f("configs.name", "string", "Config name", { required: true }),
+            f("configs.active", "boolean", "Marks the live config", {
+                default: false,
+            }),
+            // `prompts configs update --status archived` was the only way to retire a
+            // config before this issue removed it, so the key that replaced it has to
+            // be listed — an unlisted field is a capability the removal took away as
+            // far as anyone reading `config fields` can tell (issue #2645, review
+            // follow-up). Absent means unchanged: the server defaults a new config to
+            // active and leaves an existing one as it is.
+            f("configs.status", "string", "draft | active | archived"),
+            f("configs.description", "string", "What this config is tuned for"),
+            f("configs.provider", "string", "Model provider", { required: true }),
+            f("configs.model", "string", "Model id", { required: true }),
+            f("configs.temperature", "number", "Sampling temperature"),
+            f("configs.maxTokens", "number", "Output token cap"),
+            f("configs.outputFormat", "string", "text | json"),
+            f("configs.systemPrompt", "string", "System prompt"),
+            f("configs.userPromptTemplate", "string", "User prompt template"),
+        ],
+        companionFiles: [
+            testCaseCompanion("prompts/<key>.tests/<name>.toml", "prompts/<key>.tests/<name>/"),
+        ],
+        scaffold: (key) => [
+            tomlSection("prompt", [
+                `key = "${key}"`,
+                `displayName = "${key}"`,
+            ]),
+            "",
+            "[[configs]]",
+            `name = "default"`,
+            `# Exactly one config carries active = true; it is the live one.`,
+            `active = true`,
+            `provider = "openrouter"`,
+            `model = "anthropic/claude-sonnet-4.5"`,
+            `systemPrompt = ""`,
+            `userPromptTemplate = ""`,
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "workflow",
+        resourceType: resourceType("workflow"),
+        fileHint: "workflows/<key>.toml",
+        identity: "workflow.key",
+        description: "A workflow definition and its steps",
+        fields: WORKFLOW_FIELDS,
+        companionFiles: WORKFLOW_COMPANION_FILES,
+        scaffold: (key) => [
+            tomlSection("workflow", [
+                `key = "${key}"`,
+                `name = "${key}"`,
+                // #2803 — no `status` line: availability is server-owned, a pushed
+                // file carrying the key is rejected, and a new workflow is active.
+                `# CEL expression deciding who may run this workflow.`,
+                `accessRule = "true"`,
+            ]),
+            "",
+            "[[steps]]",
+            `id = "start"`,
+            `kind = "noop"`,
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "transform",
+        resourceType: resourceType("transform"),
+        fileHint: "transforms/<name>.rhai",
+        description: "A Rhai transform script; the file name is the script name",
+        // A `.rhai` file is a script body, not a table of keys. `config fields
+        // transform` reports that rather than inventing TOML keys for it.
+        fields: [],
+        companionFiles: [
+            testCaseCompanion("transforms/<name>.tests/<case>.toml", "transforms/<name>.tests/<case>/"),
+        ],
+        scaffold: (key) => [
+            `// Transform: ${key}`,
+            `// The script's return value is the step's output.`,
+            `input`,
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "database-type-config",
+        resourceType: resourceType("database-type-config"),
+        fileHint: "database-type-configs/<type>.toml",
+        identity: "type.databaseType",
+        description: "A database type: its schema, operations and access model",
+        fields: [
+            f("type.databaseType", "string", "Type name", { required: true }),
+            f("type.ruleSetName", "string", "Rule set governing record access"),
+            f("type.celContextAccess", "string", "CEL expression exposing context to rules; empty string clears it"),
+            f("type.defaultAccess", "string", "Access applied when no rule matches"),
+            f("type.autoPopulatedFields", "table", "Fields the server fills in"),
+            f("type.timestamps", "table", "Create/update timestamp field names"),
+            f("models", "table", "The `[models.*]` schema subtree"),
+            f("operations", "table[]", "Named query and mutation operations"),
+            f("subscriptions", "table[]", "Named subscriptions"),
+            f("triggers", "table", "Record lifecycle triggers"),
+            f("metadata", "table", "Declared-access manifest"),
+        ],
+        scaffold: (key) => [
+            tomlSection("type", [`databaseType = "${key}"`]),
+            "",
+            `[models.${key}]`,
+            `# Field definitions go here, e.g.`,
+            `# title = { type = "string", required = true }`,
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "rule-set",
+        resourceType: resourceType("rule-set"),
+        fileHint: "rule-sets/<name>.toml",
+        description: "A named set of CEL access rules",
+        fields: [
+            f("ruleSet.name", "string", "Rule set name", { required: true }),
+            f("ruleSet.resourceType", "string", "What the rules govern", {
+                required: true,
+            }),
+            f("ruleSet.description", "string", "What the rule set is for"),
+            f("rules", "table", "category → operation → CEL expression"),
+        ],
+        scaffold: (key) => [
+            tomlSection("ruleSet", [
+                `name = "${key}"`,
+                `resourceType = "database"`,
+            ]),
+            "",
+            tomlSection("rules.record", [
+                `read = "true"`,
+                `write = "false"`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "group-type-config",
+        resourceType: resourceType("group-type-config"),
+        fileHint: "group-type-configs/<type>.toml",
+        identity: "groupTypeConfig.groupType",
+        description: "Access configuration for one group type",
+        fields: [
+            f("groupTypeConfig.groupType", "string", "Group type name", {
+                required: true,
+            }),
+            f("groupTypeConfig.ruleSetName", "string", "Rule set governing the group"),
+            f("groupTypeConfig.autoAddCreator", "boolean", "Add the creator as a member", { default: true }),
+            f("metadata", "table", "Declared-access manifest"),
+        ],
+        scaffold: (key) => [
+            tomlSection("groupTypeConfig", [
+                `groupType = "${key}"`,
+                `ruleSetName = ""`,
+                `autoAddCreator = true`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "collection-type-config",
+        resourceType: resourceType("collection-type-config"),
+        fileHint: "collection-type-configs/<type>.toml",
+        identity: "collectionTypeConfig.collectionType",
+        description: "Access configuration for one collection type",
+        fields: [
+            f("collectionTypeConfig.collectionType", "string", "Collection type name", {
+                required: true,
+            }),
+            f("collectionTypeConfig.ruleSetName", "string", "Rule set governing the collection"),
+            f("metadata", "table", "Declared-access manifest"),
+        ],
+        scaffold: (key) => [
+            tomlSection("collectionTypeConfig", [
+                `collectionType = "${key}"`,
+                `ruleSetName = ""`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "metadata-category-config",
+        resourceType: resourceType("metadata-category-config"),
+        fileHint: "metadata-category-configs/<resourceType>.<category>.toml",
+        identity: "metadataCategoryConfig.category",
+        description: "Schema and access rules for one metadata category",
+        fields: [
+            f("metadataCategoryConfig.resourceType", "string", "Resource type the category attaches to", { required: true }),
+            f("metadataCategoryConfig.category", "string", "Category name", {
+                required: true,
+            }),
+            f("metadataCategoryConfig.description", "string", "What the category holds"),
+            f("metadataCategoryConfig.readRule", "string", "CEL expression for reads"),
+            f("metadataCategoryConfig.writeRule", "string", "CEL expression for writes"),
+            f("metadataCategoryConfig.schema", "table", "Field definitions"),
+        ],
+        // The file is named `<resourceType>.<category>.toml`, so `config create
+        // metadata-category-config document.review` splits the key on the first dot.
+        scaffold: (key) => {
+            const dot = key.indexOf(".");
+            const resource = dot > 0 ? key.slice(0, dot) : key;
+            const category = dot > 0 ? key.slice(dot + 1) : key;
+            return [
+                tomlSection("metadataCategoryConfig", [
+                    `resourceType = "${resource}"`,
+                    `category = "${category}"`,
+                    `readRule = "true"`,
+                    `writeRule = "false"`,
+                ]),
+                "",
+                tomlSection("metadataCategoryConfig.schema.fields", []),
+                "",
+            ].join("\n");
+        },
+    },
+    {
+        type: "email-template",
+        resourceType: resourceType("email-template"),
+        fileHint: "email-templates/<emailType>.toml",
+        identity: "template.emailType",
+        description: "An override for one transactional email",
+        fields: [
+            f("template.emailType", "string", "Which email this overrides", {
+                required: true,
+            }),
+            f("template.subject", "string", "Subject line", { required: true }),
+            f("template.htmlBody", "string", "HTML body"),
+            f("template.textBody", "string", "Plain-text body"),
+        ],
+        scaffold: (key) => [
+            tomlSection("template", [
+                `emailType = "${key}"`,
+                `subject = ""`,
+                `textBody = ""`,
+            ]),
+            "",
+        ].join("\n"),
+    },
+    // ---- root singletons ----------------------------------------------------
+    {
+        type: "app",
+        fileHint: "app.toml",
+        description: "App settings — the `app.toml` root singleton",
+        fields: APP_FIELDS,
+        scaffold: () => [
+            tomlSection("app", [`name = ""`, `mode = "standard"`]),
+            "",
+            tomlSection("auth", [
+                `passkeyEnabled = false`,
+                `emailSignInEnabled = true`,
+            ]),
+            "",
+            tomlSection("cors", [`mode = "universal"`]),
+            "",
+            tomlSection("invitations", [`enabled = false`, `limit = 0`]),
+            "",
+        ].join("\n"),
+    },
+    {
+        type: "var",
+        fileHint: "vars.toml",
+        description: "Non-secret config vars — the `vars.toml` root singleton",
+        // `vars.toml` is a FLAT root table (`API_BASE_URL = "https://…"`), so the
+        // keys are the app's own and there is no fixed field list to report.
+        freeFormRootKeys: true,
+        fields: [],
+        scaffold: () => [
+            "# Per-environment non-secret config vars.",
+            "# Bind as {{ vars.KEY }} in workflow/integration config and vars.* in CEL",
+            "# rules. Never put a credential here — use `primitive secrets` for that.",
+            "",
+        ].join("\n"),
+    },
+];
+const BY_TYPE = new Map(CONFIG_OBJECT_DESCRIPTORS.map((d) => [d.type, d]));
+/** Every selector type name, in registry order. */
+export const CONFIG_OBJECT_TYPES = CONFIG_OBJECT_DESCRIPTORS.map((d) => d.type);
+export function getConfigObjectDescriptor(type) {
+    return BY_TYPE.get(type);
+}
+//# sourceMappingURL=config-object-descriptor.js.map