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

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

@@ -110,9 +110,19 @@ export interface ConfigField {
      * `"src/workflows/config/workflow-field-handlers.ts#normalizeWorkflowStatus"`.
      * `cli/tests/unit/config-surface-drift-guard.test.ts` fails when the module or
      * the export is missing (#2644 behavior 2b).
+     *
+     * `stage` says WHEN the handler runs, with exactly the meaning `RuleStage`
+     * gives a cross-field rule (#3375). Until this issue the slot named an owner
+     * and never said when, so intent criterion 5 — "a rule declared `preflight`
+     * is provably reached before the first mutating call" — could not cover a
+     * single-field rule at all. It is REQUIRED, so a new field handler cannot be
+     * declared without answering the question, and
+     * `findMalformedFieldValidationStages` closes the key set at
+     * `handler`/`stage`: the slot stays declarative like the field entry itself.
      */
     validation: "passthrough" | {
         handler: string;
+        stage: RuleStage;
     };
     /**
      * This field's declared type genuinely admits more than one TOML spelling
@@ -207,7 +217,18 @@ export interface ConfigTable {
  * CLI call exists would make the registry promise a refusal that in fact lands
  * mid-apply.
  */
-export type CrossFieldRuleStage = "preflight" | "apply";
+export type RuleStage = "preflight" | "apply";
+/**
+ * The cross-field spelling of `RuleStage`, kept as an exported alias.
+ *
+ * #3373 named the type for the only slot that had a stage. #3375 gave
+ * `ConfigField.validation` one too, with the same meaning, so the canonical
+ * name is the general one — and this alias stays because it is part of the
+ * registry's published surface (`CrossFieldRule.stage`, the guard, every
+ * `crossFieldRulesForStage` caller) and renaming it would be a breaking change
+ * to buy a shorter name.
+ */
+export type CrossFieldRuleStage = RuleStage;
 /**
  * One rule of a configuration object that spans more than one field — `durable
  * = true` beside a webhook trigger, `runAs = "system"` beside a non-empty
@@ -337,8 +358,15 @@ export declare const UPDATE_ONLY: readonly ("create" | "update")[];
  * the definition never dispatches through it (#1976 decision of record); the
  * guard asserts the export exists so a renamed handler fails the CLI unit suite
  * instead of leaving a dangling reference (#2644 behavior 2b).
+ *
+ * `stage` is REQUIRED (#3375): a field handler that does not say when it runs
+ * makes the same empty promise the cross-field slot made before #3373 — it
+ * names an owner, and criterion 5 has nothing to check. A `preflight` handler
+ * is reached from `cli/src/commands/sync.ts#runConfigPushPreflight` before the
+ * first mutating call, which `findUnreachedPreflightRules` proves statically;
+ * an `apply` handler is everything else.
  */
-export declare function handledBy(modulePath: string, exportName: string): ConfigField["validation"];
+export declare function handledBy(modulePath: string, exportName: string, stage: RuleStage): ConfigField["validation"];
 /**
  * Name the ONE export that enforces a cross-field rule, as
  * `"<repo-relative module>#<export>"` — the sibling of `handledBy` for a rule
@@ -739,6 +767,115 @@ export declare function hasDeclaredCrossFieldRules(surface: ConfigObjectSurface)
  * `[]`: "not declared yet" must never be read as "has no rules" (principle 6).
  */
 export declare function crossFieldRulesForStage(surface: ConfigObjectSurface, stage: CrossFieldRuleStage): readonly CrossFieldRule[];
+/**
+ * Is a rule declared `preflight` actually reached before `config push` mutates
+ * anything? (issue #3375, project phase 3, intent §Success criteria 5.)
+ *
+ * #3373 gave a rule a `stage`; #3374 declared three surfaces' rules. Both left
+ * the string a PROMISE. "This runs before the first mutating call" was
+ * satisfied by typing `preflight` beside a rule that is not on the preflight
+ * path at all, because the push preflight was an inline block inside the
+ * command's `.action()` callback with no exported symbol — so "reached from the
+ * preflight" had nothing to resolve against.
+ *
+ * #3375 extracts that block into `cli/src/commands/sync.ts#runConfigPushPreflight`
+ * and this module answers the question statically, from the declared
+ * `<module>#<export>`:
+ *
+ *   - `reachableExports` walks the call graph from one entry symbol over module
+ *     SOURCE TEXT and returns what it reached — plus what it could NOT resolve,
+ *     so silence is never a pass.
+ *   - `findUnreachedPreflightRules` reports every `preflight` declaration,
+ *     cross-field or single-field, whose handler is missing from that set.
+ *   - `findMalformedFieldValidationStages` is the field-level twin of #3373's
+ *     `findMalformedRuleDeclarations`: `ConfigField["validation"]` gained a
+ *     `stage` here, and it must be well-formed to mean anything.
+ *
+ * Everything is a PURE function over values and over source text the caller
+ * passes in: `cli/tests/unit/config-surface-preflight-staging-3375.test.ts`
+ * does the filesystem walk, so this module stays vendorable (`types.ts`
+ * §Purity), exactly the split `rules.ts` already uses.
+ *
+ * ── Two things this check is NOT ──────────────────────────────────────────
+ *
+ * It is NECESSARY, not sufficient, and there is deliberately no converse. A
+ * handler reached on one surface's leg satisfies a `preflight` declaration on
+ * another (the residual the intent accepts and #3379 records), and asking "is
+ * this `apply` rule reached from the preflight?" would be wrong by
+ * construction: `validateSigningSecretDeclaration` IS reached on the function
+ * leg and IS correctly `apply` on the webhook surface, where no CLI call
+ * exists.
+ *
+ * The walk is identifier-based over masked source, so it over-approximates in
+ * the PASSING direction: a local variable shadowing an imported handler's name
+ * reads as a call. That is the safe direction for a guard whose failure mode
+ * must be "a promise you did not keep", not "a promise you did keep, reported
+ * as broken".
+ */
+/** A field's `validation` object may carry these keys and no others (#3375). */
+export declare const FIELD_VALIDATION_KEYS: readonly string[];
+/**
+ * The modules a walk may read, and how a specifier resolves between them.
+ *
+ * The caller owns resolution because it owns the filesystem: the CLI test maps
+ * both spellings of the vendored artifact onto the `src/config-surface/`
+ * modules it is a copy of, which is the whole point of DSO-3375-002 — the
+ * generator strips every intra-directory import before concatenating, so the
+ * artifact itself carries no edges between its sections.
+ */
+export interface StaticModuleGraph {
+    /** Repo-relative module path → that module's SOURCE TEXT. */
+    modules: ReadonlyMap<string, string>;
+    /**
+     * Candidate modules a specifier names, seen from `fromModule`.
+     *
+     * `null` = a bare package specifier: deliberately not followed, and never
+     * reported. `[]` = a relative specifier that resolves to no module in the
+     * graph, which IS reported — a guard that silently stops looking is worse
+     * than no guard.
+     */
+    resolve(fromModule: string, specifier: string): readonly string[] | null;
+}
+/** What one walk found, and what it could not resolve on the way. */
+export interface ReachabilityWalk {
+    /** `<module>#<export>` for every symbol reached, module = where it is DECLARED. */
+    reached: ReadonlySet<string>;
+    /** Specifiers and entry symbols the graph could not answer for, sorted. */
+    unresolved: string[];
+}
+/**
+ * Walk the call graph from `entry` and return every symbol it reaches.
+ *
+ * An identifier inside a reached declaration's span is followed when it names
+ * another top-level declaration of the same module, or a value import — which
+ * resolves through the graph to whichever candidate module DECLARES the name,
+ * following `export { x } from` and `export * from` on the way. A symbol is
+ * recorded under the module that declares it, never under a barrel that merely
+ * re-exports it: a declaration that names the barrel is reported unreached,
+ * because the point of the string is to name the one implementation.
+ */
+export declare function reachableExports(entry: string, graph: StaticModuleGraph): ReachabilityWalk;
+/**
+ * Every fault in one surface's FIELD validation declarations, each naming the
+ * surface and the field. `[]` means every field is well-formed.
+ *
+ * Runs over every surface in the registry, migrated or not: field declarations
+ * exist independently of the cross-field slot, so the
+ * `CROSS_FIELD_RULES_UNMIGRATED` ratchet does not — and must not — stand
+ * between a field-level `preflight` declaration and this check (DSO-3375-001).
+ */
+export declare function findMalformedFieldValidationStages(surface: ConfigObjectSurface): string[];
+/**
+ * Every `preflight` declaration on this surface whose handler the walk did not
+ * reach, each naming the surface, the rule (or field), the handler and the
+ * entry point.
+ *
+ * The FIELD half runs on every surface. The CROSS-FIELD half runs only where a
+ * surface has declared, because `crossFieldRulesForStage` throws for one that
+ * has not — "not declared yet" is never "rule-free" (#3373), and asking it
+ * here would turn an unmigrated surface into a crash rather than a skip.
+ */
+export declare function findUnreachedPreflightRules(surface: ConfigObjectSurface, reached: ReadonlySet<string>, entry: string): string[];
 /**
  * Request schemas generated from the configuration-object definitions
  * (issue #2644, phase 5 / criterion 9).
@@ -1239,70 +1376,107 @@ export interface ParsedManifest {
  */
 export declare function parseFunctionManifest(value: unknown): ParsedManifest;
 /**
- * The function MODE vocabulary, and the one place its two spellings meet —
- * #3281, project `server-functions` phase 4.
- *
- * `mode = "request" | "task"` is what an author writes (the intent, "Mode
- * vocabulary?", sponsor decision 2026-09-09): a request function runs inside
- * the call and returns its result; a task function returns a run id and
- * survives restarts. `durable = true | false` is the key the first releases
- * taught, and it stays ACCEPTED as an alias through the transition — a tree
- * pushed with it keeps pushing, and pulls back byte for byte — while `durable`
- * stays the adjective for the property itself.
- *
- * ── Why one module ───────────────────────────────────────────────────────
- *
- * Two spellings for one fact is a place two readers can disagree. So the
- * resolution is written once, here, in the dependency-free tree the CLI
- * vendors (`cli/scripts/gen-config-surfaces.mjs`), and every door reads it:
- * the CLI preflight and diff entity, the server's trigger derivation, the
- * admin config-version route (payload `mode` beside payload `durable`), the
- * invoke branch and the trigger fires. A file — or a payload — that carries
- * both keys has to have them AGREE, or it is refused naming both; a silent
- * winner would be the one thing worse than two spellings.
- *
- * The stored column is still `ServerFunctionConfig.durable` (no `models.yaml`
- * change before phase 7's rename sweep), which is why `configMode` exists:
- * reading the row is the other half of the same translation.
- */
-export type FunctionMode = "request" | "task";
-export declare const FUNCTION_MODES: readonly FunctionMode[];
-/** What a declaration resolved to, or why it could not. */
-export type DeclaredModeResolution = {
-    ok: true;
-    mode: FunctionMode;
+ * The runtime keys a `functions/<key>.toml` no longer decides anything with —
+ * #3482, project `server-functions` phase 4.
+ *
+ * The sponsor settled it on 2026-09-15 (the intent, "Mode vocabulary?",
+ * amended again): the config says NOTHING about how a function runs. A
+ * function is a function; the caller picks the runtime at each call, cron
+ * fires always start a task run, webhook deliveries always run as a request,
+ * and a function that must not run under one runtime tests for it in code with
+ * `assertRuntime`.
+ *
+ * ── Why these keys are accepted, not refused ──────────────────────────────
+ *
+ * Every tree pushed since #3454 that declares a cron trigger carries
+ * `mode = …` ON THE ENTRY, because `cron-trigger-mode-required` demanded it;
+ * plenty carry a top-level `mode` or the older `durable`. Removing the keys
+ * from the accepted set outright would refuse those trees with an unknown-key
+ * error one day after the platform insisted on them, which is the opposite of
+ * principle 5 inside a non-breaking phase.
+ *
+ * So through phase 4 they are ACCEPTED and IGNORED, with one warning per key
+ * naming it and the line to delete; from phase 5 (#3188) they are refused with
+ * the rest of the retirement matrix. The value is not validated — there is
+ * nothing left to validate it against, and refusing a bad value for a key
+ * nobody reads would be a refusal about spelling alone.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity). Both
+ * the CLI preflight (vendored by `cli/scripts/gen-config-surfaces.mjs`) and the
+ * admin config-version route read this one scanner, so the warning an author
+ * sees from `config push` is the sentence the API answers with.
+ */
+/** The two `[function]` keys that no longer say anything (#3482). */
+export declare const RETIRED_FUNCTION_RUNTIME_KEYS: readonly ["mode", "durable"];
+export type RetiredFunctionRuntimeKey = (typeof RETIRED_FUNCTION_RUNTIME_KEYS)[number];
+/** One ignored key met in a `[function]` table. */
+export interface IgnoredFunctionKey {
     /**
-     * Whether the declaration SAID anything — false when neither key was
-     * present and the default applied. The admin route's divergence check
-     * reads this: an omitted mode is no claim, so it cannot diverge.
+     * Where it was: `mode`, `durable`, or `triggers.cron.<name>.mode`. Never
+     * rendered on its own — a reader that wants to branch reads this, and every
+     * printer reads `message`.
      */
-    declared: boolean;
-} | {
-    ok: false;
-    error: string;
-};
+    path: string;
+    /** The sentence the author is owed, with no file prefix (the caller adds it). */
+    message: string;
+}
 /**
- * Resolve `mode` and its alias `durable` to one mode.
+ * Every retired runtime key a `[function]` table still carries.
  *
- * Absent both → `request`. `mode` must be exactly `"request"` or `"task"`;
- * `durable` must be a boolean. Both present and disagreeing is refused naming
- * both keys, so an author who half-migrated a file hears which line to fix.
+ * Reads the table the way the author wrote it: the two top-level keys, and a
+ * `mode` on each `[[function.triggers.cron]]` entry. A cron entry's sentence
+ * says the extra thing its author needs to hear — that the schedule no longer
+ * chooses, because every fire starts a task run (#3334's runner branch is
+ * gone).
+ *
+ * Order is the order an author reads their file in: the top-level keys first,
+ * then the cron entries in declaration order.
  */
-export declare function resolveDeclaredMode(input: {
-    mode?: unknown;
-    durable?: unknown;
-}): DeclaredModeResolution;
+export declare function ignoredFunctionKeys(functionTable: unknown): IgnoredFunctionKey[];
 /**
- * The mode a stored config-version row runs in.
+ * The database types a `[function]` table's retired trigger block names —
+ * #3483.
+ *
+ * Beside `ignoredFunctionKeys` because it answers the same question about the
+ * same table, for the same reader: `config pull` writes a version's AUTHORED
+ * bytes, and a version pushed before the removal carries the block. Without
+ * this the pulled tree would be refused on its next push — a tree an author
+ * cannot get back into a working state, which is the failure D3482-007 already
+ * had to close for the runtime keys.
  *
- * The column is `durable`; a row written before #3281 carries only that, and a
- * row written after it carries the same thing, so there is exactly one reading.
+ * This is NOT a refusal and shares nothing with one. The block is refused on
+ * input by `normalizeTriggerDeclaration`; what a strip needs is the list of
+ * entries it is taking out so it can say so, which is why an entry whose
+ * `type` is unreadable still counts as one entry (the empty string). It is the
+ * block's PRESENCE that goes, not its contents.
+ *
+ * TOML spells the block three ways — an array of tables, a single table, and
+ * an inline array — and a scan that missed one would leave a key behind
+ * (CR3482-002's lesson, applied to a whole table).
  */
-export declare function configMode(row: {
-    durable?: unknown;
-} | null | undefined): FunctionMode;
-/** Is this mode the durable one? The adjective, for the paths that branch on it. */
-export declare function isDurableMode(mode: FunctionMode): boolean;
+export declare function retiredDatabaseTriggerTypes(functionTable: unknown): string[];
+/**
+ * Whether the block is THERE at all — the question a strip has to ask, which
+ * the type list above cannot answer (CR3483-001).
+ *
+ * `database = []` names no type, so the list is empty and a strip that decided
+ * by its length left the key in the pulled file. That file then fails its own
+ * next push: `normalizeTriggerDeclaration` refuses the key by PRESENCE, of any
+ * shape, an empty array included — so the two halves disagreed about what the
+ * block is, and the tree an author pulled was a tree they could not push.
+ * Presence is the one rule both sides read now, spelled the way
+ * `normalizeTriggerDeclaration` spells it — `!== undefined` — so a value one
+ * of them would call a block and the other would not cannot exist.
+ */
+export declare function hasRetiredDatabaseTriggerBlock(functionTable: unknown): boolean;
+/**
+ * The same scan, rendered for one file — the shape `config push` and
+ * `config diff` print and the admin route answers with.
+ *
+ * `label` is what the reader can act on: `functions/<key>.toml` from the CLI,
+ * and the function's key from the API, which has no file to name.
+ */
+export declare function ignoredFunctionKeyWarnings(label: string, functionTable: unknown): string[];
 /**
  * The trigger blocks a function declares, derived from its authored TOML
  * (#3181, project `server-functions`, criterion 4).
@@ -1349,29 +1523,20 @@ export declare function isDurableMode(mode: FunctionMode): boolean;
  * and the CLI has already parsed its own file by the time it asks.
  */
 /**
- * The resolved mode the declaration is checked against (#3281).
+ * Why a webhook trigger is the request runtime, and a cron fire a task run —
+ * #3482, the intent's "Mode vocabulary?" decision of 2026-09-15.
  *
- * The rule is per KIND, and permanent (the intent, "Sync functions write a run
- * row?": *Webhook and database-change triggers require request mode; HTTP and
- * cron allow both*). A webhook delivery and a database write are both waiting
- * inside a request for the function to answer; a cron fire is waiting for
- * nothing, so it starts a task run when the version is a task (#3334).
+ * Neither is a rule about the FUNCTION any more, so neither is a refusal: a
+ * function is a function, and the DOOR decides which runtime runs it. A
+ * webhook delivery runs inside the receiver because the provider is holding
+ * the connection open waiting for an answer; a cron fire starts a task run
+ * because it is waiting for nothing. A function that must not run under one of
+ * them tests for it in code with `assertRuntime`, which is the only lock left.
  *
- * The caller resolves `mode`/`durable` once, through `resolveDeclaredMode`,
- * and hands the answer here — this module never reads the alias itself.
+ * What survives here is the SHAPE of a declaration — the keys, the names, the
+ * cron expression, the caps. The retired `mode` keys are accepted and reported
+ * as ignored by `ignoredFunctionKeys` in `function-retired-keys.ts`.
  */
-export interface TriggerModeOptions {
-    mode?: FunctionMode;
-}
-/**
- * Why a webhook cannot drive a task function, and what to do instead (#3334).
- *
- * The first clause is verbatim what it has always been, so sibling pins on the
- * request-mode prefix (#3281's) keep holding; everything after the dash is the
- * half that was missing — an author who meets this at the push door could not
- * previously tell whether it was a limitation or a design, nor what to write.
- */
-export declare const WEBHOOK_ON_TASK_REFUSAL: string;
 /** A function's single webhook trigger, normalized. */
 export interface WebhookTriggerDeclaration {
     verificationScheme: string;
@@ -1392,15 +1557,9 @@ export interface CronTriggerDeclaration {
     overlapPolicy?: string;
     rootInput?: unknown;
 }
-/** One `[[function.triggers.database]]` entry, normalized (#3184). */
-export interface DatabaseTriggerDeclaration {
-    /** The database type key whose writes fire this function. */
-    type: string;
-}
 export interface TriggerDeclaration {
     webhook: WebhookTriggerDeclaration | null;
     cron: CronTriggerDeclaration[];
-    databases: DatabaseTriggerDeclaration[];
 }
 export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
 /**
@@ -1413,14 +1572,22 @@ export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
  */
 export declare const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
 /**
- * The most database types one function may watch (#3184, D-07).
- *
- * Per-OBJECT, like the cron cap above: a function watching more than a handful
- * of types is describing a fan-in the platform cannot bound per write, and
- * every extra type is another discovery read on somebody's write path.
+ * The rule ids this module owns — one per refusal, declared on the `function`
+ * surface (#3374). The union below closes `refuseTrigger`'s id parameter, so a
+ * twenty-seventh refusal cannot compile without a twenty-seventh id, and that
+ * id fails `cli-unit-tests` until the surface declares it (#3373's anchor).
+ */
+export declare const TRIGGER_RULE_IDS: readonly ["triggers-table", "trigger-kind", "database-trigger-removed", "webhook-trigger-single", "webhook-trigger-table", "webhook-trigger-keys", "webhook-trigger-scheme-required", "webhook-trigger-scheme-none", "webhook-trigger-number", "webhook-trigger-dedup-boolean", "webhook-trigger-verification-table", "cron-trigger-cap", "cron-trigger-entry", "cron-trigger-keys", "cron-trigger-name-required", "cron-trigger-name-charset", "cron-trigger-duplicate", "cron-trigger-expression-required", "cron-trigger-overlap-policy"];
+export type TriggerRuleId = (typeof TRIGGER_RULE_IDS)[number];
+/**
+ * A broken trigger rule. `ruleId` names which one, for a reader that wants to
+ * branch without matching prose; every existing site reads `message` only.
+ * Optional so `new TriggerDeclarationError(message)` — the CLI's own parse
+ * refusal in `function-sync.ts` — keeps constructing.
  */
-export declare const MAX_DATABASE_TRIGGERS_PER_FUNCTION = 5;
 export declare class TriggerDeclarationError extends Error {
+    readonly ruleId?: TriggerRuleId;
+    constructor(message: string, ruleId?: TriggerRuleId);
 }
 /** Is anything at all declared? Used to skip work on the common case. */
 export declare function hasDeclaredTriggers(declaration: TriggerDeclaration): boolean;
@@ -1433,11 +1600,20 @@ export declare function hasDeclaredTriggers(declaration: TriggerDeclaration): bo
  * push boundary can normalize a declaration it read from a stored row without
  * re-parsing bytes.
  */
-export declare function normalizeTriggerDeclaration(functionTable: any, options?: TriggerModeOptions): TriggerDeclaration;
+export declare function normalizeTriggerDeclaration(functionTable: any): TriggerDeclaration;
 /** The stored JSON for `ServerFunctionConfig.triggers`, or null when empty. */
 export declare function serializeTriggerDeclaration(declaration: TriggerDeclaration): string | null;
 /** Read a stored `ServerFunctionConfig.triggers` value back. */
 export declare function parseStoredTriggerDeclaration(stored: unknown): TriggerDeclaration;
+/**
+ * The database types a STORED declaration used to watch, for a reader that
+ * wants to name them — #3483.
+ *
+ * Pure, and separate from the parse on purpose: the parse answers what the
+ * version means NOW (nothing), and this answers what it said, which is only
+ * ever used to write one log line. Nothing branches on it.
+ */
+export declare function storedDatabaseTriggerTypes(stored: unknown): string[];
 /** The `CronTrigger.triggerKey` an entry owns. */
 export declare function cronTriggerKeyFor(functionKey: string, name: string): string;
 /** The entry name a `<functionKey>:<name>` trigger key carries. */
@@ -1597,12 +1773,24 @@ export declare function requiresSigningSecret(scheme: unknown): boolean;
 /** The coded refusals, so a client can branch without matching prose. */
 export declare const SIGNING_SECRET_MUST_BE_SECRET_REF = "SIGNING_SECRET_MUST_BE_SECRET_REF";
 export declare const SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME = "SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME";
+/**
+ * The rule ids this module owns, declared on the `function` surface as
+ * `preflight` and on the `webhook` surface as `apply` (#3374) — one rule, two
+ * surfaces, one handler. `whole-secret-reference` is generic on purpose:
+ * `validateWholeSecretReference` is reused by the Google client secret and by
+ * both webhook controllers under their own labels and codes.
+ */
+export declare const SIGNING_SECRET_RULE_IDS: readonly ["signing-secret-required", "whole-secret-reference", "signing-secret-not-supported"];
+type SigningSecretRuleId = (typeof SIGNING_SECRET_RULE_IDS)[number];
 /**
  * A refusal from this rule. `plain` marks the ones the admin webhook create
  * answered as a bare text body rather than coded JSON — an observable
  * distinction, so it travels with the error rather than being flattened.
+ * `ruleId` names the rule and never reaches the wire: every reader picks
+ * `message`, `code` and `plain`.
  */
 export interface SigningSecretRuleError {
+    ruleId: SigningSecretRuleId;
     message: string;
     code?: string;
     plain?: boolean;
@@ -1632,7 +1820,288 @@ export declare function validateSigningSecretDeclaration(input: {
     verificationScheme: string;
     signingSecret?: unknown;
 }): SigningSecretRuleError | null;
+/**
+ * The workflow rules two runners share (#3374, project `cli-server-rule-parity`
+ * phase 2; intent §Success criteria 3).
+ *
+ * ── One predicate, two messages ──────────────────────────────────────────
+ *
+ * `runAs = "system"` beside a non-empty `accessRule` is dead config: a system
+ * run can only be started by the system and never evaluates its access rule
+ * (#1258, broadening #1172). The server refused it at save time
+ * (`validateWorkflowIdentityConfig`) and the CLI refused it in the push
+ * preflight (`validateWorkflowIdentity`), and the two carried the conjunction
+ * byte-for-byte as separate copies kept in step by a comment. This module is
+ * the one copy: it decides, and returns a STRUCTURED violation — the rule id
+ * and the server's sentence — that each site renders in its own words. The
+ * server pushes the sentence into its `string[]`; the CLI keeps its own hint,
+ * which names the preflight remedy. Neither message changed.
+ *
+ * ── Why a `*-rules.ts` module ────────────────────────────────────────────
+ *
+ * The registry's unclaimed-export check (`findUnclaimedRuleModuleExports`)
+ * keys on this name under `src/config-surface/`: every exported function here
+ * is a rule, so one no surface declares fails `cli-unit-tests`. Shared
+ * predicates that are not rules live elsewhere (`webhook-signing-secret.ts`).
+ * The module is vendored into the CLI artifact like the rest of the
+ * directory, which is what lets `workflow`'s declaration call the rule
+ * `preflight`.
+ */
+/** The rule ids this module owns — the union type below anchors them (#3373). */
+export declare const WORKFLOW_RULE_IDS: readonly ["system-access-rule"];
+type WorkflowRuleId = (typeof WORKFLOW_RULE_IDS)[number];
+/** A violation of one of this module's rules, for a site to render. */
+export interface WorkflowRuleViolation extends RuleRefusal<WorkflowRuleId> {
+}
+/**
+ * `runAs = "system"` with a non-empty string `accessRule`, or null.
+ *
+ * Exactly the conjunction both sites carried: a default, unset, empty or
+ * whitespace-only rule is no rule, and a non-string one (`accessRule = false`)
+ * is malformed input for another check to name, not dead config. The message
+ * is the server's save-time sentence; the CLI renders its own hint from the
+ * same answer.
+ */
+export declare function checkWorkflowSystemAccessRule(input: {
+    runAs?: unknown;
+    accessRule?: unknown;
+}): WorkflowRuleViolation | null;
 export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
+/**
+ * Cron-expression and timezone VALIDITY — the half of `src/cron-parser.ts`
+ * both runners need (#3376, project `cli-server-rule-parity` phase 4).
+ *
+ * ── Why this module exists ───────────────────────────────────────────────
+ *
+ * A malformed cron expression and an unknown timezone are both decidable from
+ * the authored file, so the intent lands both rules `preflight` — which under
+ * this project's vocabulary means the implementation lives here, under
+ * `src/config-surface/`, and is vendored into the CLI artifact.
+ *
+ * It got here by a SPLIT, not a move. `src/cron-parser.ts` is 415 lines, and
+ * roughly 290 of them are timezone-aware scheduling arithmetic — "when does
+ * this expression next fire?" — that only the cron Durable Object runs.
+ * Vendoring is wholesale: the generator concatenates this whole directory, so
+ * moving the file would have shipped that scheduler into the published CLI
+ * package. The validator moved; the scheduler stayed; `src/cron-parser.ts`
+ * re-exports what moved, so no server import changed.
+ *
+ * The scheduler's two entry points are deliberately not NAMED here: a CLI
+ * unit test asserts the artifact does not contain either identifier, which is
+ * how "the artifact carries the validator only" is kept true mechanically
+ * rather than by review.
+ *
+ * ── Not a rules module ───────────────────────────────────────────────────
+ *
+ * `parseCron` THROWS, eight different sentences, and `tests/unit/
+ * cron-parser.test.ts` pins that it throws. A module exporting a `*_RULE_IDS`
+ * list may not contain a `throw` outside its one refusal constructor
+ * (`findUnanchoredRefusals`, #3373), so the rule that renders these answers as
+ * refusals is a separate module, `cron-rules.ts`, and this one is a plain
+ * shared-predicate module — the `webhook-signing-secret.ts` / `function-mode.ts`
+ * precedent.
+ *
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
+ * `Intl.DateTimeFormat` is the one platform call, and it is the timezone
+ * question itself.
+ *
+ * Supported fields (standard POSIX order):
+ *   minute (0-59)
+ *   hour (0-23)
+ *   day-of-month (1-31)
+ *   month (1-12)
+ *   day-of-week (0-6, where 0 = Sunday; 7 also accepted as Sunday)
+ *
+ * Supported syntax per field:
+ *   - "*"          any value
+ *   - "5"          exact value
+ *   - "5-10"       range (inclusive)
+ *   - "star/step"  every N values within the full range (e.g. "* /5" => 0,5,10,...)
+ *   - "a-b/step"   every N values within a range
+ *   - "1,2,3"      comma-separated list of values or ranges
+ *
+ * Not supported: month/day names, "?", "L", "W", "#", last-day modifiers.
+ */
+export interface ParsedCron {
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    daysOfWeek: Set<number>;
+    dayOfMonthWild: boolean;
+    dayOfWeekWild: boolean;
+}
+export declare function parseCron(expr: string): ParsedCron;
+/**
+ * The message `parseCron` would throw for `expr`, or null when it parses.
+ *
+ * The same grammar, asked as a question instead of as an exception, because
+ * both callers want the sentence rather than the control flow: the CLI's push
+ * preflight collects one message per broken entry, and the standalone cron
+ * routes render theirs into a 400 body. `expr` is typed `unknown` because it
+ * arrives as an authored TOML value, where it can be anything at all.
+ */
+export declare function cronExpressionError(expr: unknown): string | null;
+/**
+ * Whether `Intl.DateTimeFormat` accepts `name` as a timezone.
+ *
+ * This is THE timezone check — before #3376 the identical probe was written
+ * out three times (the function push boundary and the standalone create and
+ * update). Each of those sites keeps its own sentence and its own defaulting;
+ * what they now share is this answer. A non-string is false rather than a
+ * throw, for the same reason as above.
+ */
+export declare function isValidTimezone(name: unknown): boolean;
+/**
+ * The cron schedule rules two runners share (#3376, project
+ * `cli-server-rule-parity` phase 4; intent §Success criteria 6).
+ *
+ * ── One implementation, two runners ──────────────────────────────────────
+ *
+ * A cron expression the grammar refuses, and a timezone `Intl` does not know,
+ * are both decidable from the authored file. Before this issue only the SERVER
+ * decided them, inside the apply loop: a `functions/<key>.toml` carrying
+ * either passed `config push`'s preflight, sibling entities were written, and
+ * the function alone was refused — while the command promises that a refusal
+ * means nothing was applied. Now `cli/src/lib/function-sync.ts` and
+ * `src/services/function-trigger-validation.ts` both call the rule below, and
+ * the sentence an author reads is the same on either side of the wire because
+ * it is built in one place.
+ *
+ * ── Why this is a `*-rules.ts` module and the parser is not ──────────────
+ *
+ * The registry's unclaimed-export check (`findUnclaimedRuleModuleExports`)
+ * keys on this name under `src/config-surface/`: every exported function here
+ * is a rule, so one no surface declares fails `cli-unit-tests`. The anchor
+ * also forbids a `throw` outside the one refusal constructor — and `parseCron`
+ * throws eight different sentences, which `tests/unit/cron-parser.test.ts`
+ * pins. So the grammar and the `Intl` probe live next door in
+ * `cron-expression.ts`, which is a shared-predicate module rather than a rules
+ * module, and this one only decides and renders.
+ *
+ * ── What is NOT shared ───────────────────────────────────────────────────
+ *
+ * The standalone cron routes ask the same two predicates and render their own
+ * `Invalid cron expression: …` / `Invalid timezone: …`, with their own
+ * defaulting (create reads an absent timezone as UTC, update does not). That
+ * is intent assumption 2 in the form its own fallback describes, and the shape
+ * `workflow-rules.ts` set in phase 2: one predicate, each site's message and
+ * defaulting preserved. No refusal message changed anywhere.
+ */
+/** The rule ids this module owns — the union type below anchors them (#3373). */
+export declare const CRON_TRIGGER_RULE_IDS: readonly ["cron-trigger-expression", "cron-trigger-timezone"];
+type CronTriggerRuleId = (typeof CRON_TRIGGER_RULE_IDS)[number];
+/** A refused cron entry: the rule and the sentence the site renders. */
+export type CronTriggerRuleRefusal = RuleRefusal<CronTriggerRuleId>;
+/**
+ * One `[[function.triggers.cron]]` entry's schedule, or null.
+ *
+ * Expression first, then timezone, which is the order the push boundary ran
+ * them in — so an entry broken both ways still answers with the expression's
+ * refusal, exactly as before. An unset or empty `timezone` reads as UTC, again
+ * exactly as before: the boundary's `entry.timezone || "UTC"`.
+ */
+export declare function checkCronTriggerEntry(entry: {
+    name: string;
+    cron: string;
+    timezone?: string;
+}): CronTriggerRuleRefusal | null;
+/**
+ * The prompt config's reasoning controls, resolved onto each provider's own
+ * spelling — issue #3358.
+ *
+ * A `[[configs]]` entry states EITHER `reasoningEffort` (a provider-neutral
+ * level, `none` through `high`) or `reasoningBudget` (a token count), never
+ * both. This module is the whole translation: every authored pair either maps
+ * onto the provider's native key or is REFUSED with a message naming the
+ * remedy. Nothing is dropped — that was the trap `providerConfig` already laid
+ * in the tree (stored, serialized, round-tripped, and never read at execution),
+ * and the issue's third success criterion is precisely that a config asking for
+ * something a provider cannot express fails rather than silently doing nothing.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`: the
+ * server's create/update handlers, the executor, and the vendored CLI artifact
+ * all read this one copy, so a refusal at push and a refusal at execution
+ * cannot disagree.
+ *
+ * Provider facts this encodes:
+ *
+ *  - OpenRouter takes a unified `reasoning` block: `{ effort }`,
+ *    `{ max_tokens }`, or `{ enabled: false }` to decline it. `max_tokens` is an
+ *    exact bound on budget-native models and is translated to the nearest
+ *    effort level on effort-only ones, so it is documented as a bound, not a
+ *    guarantee — `metrics.reasoningTokens` is the measure of what was spent.
+ *    Default routing lets an endpoint IGNORE a parameter it does not support,
+ *    so a request carrying `reasoning` also carries
+ *    `provider: { require_parameters: true }`: an endpoint that cannot honor it
+ *    is refused by OpenRouter and surfaces as a failed execution rather than a
+ *    silent drop.
+ *  - Gemini 3.x expresses thinking as a LEVEL
+ *    (`thinkingConfig.thinkingLevel`) and cannot turn it off; `thinkingBudget`
+ *    is accepted there only for backward compatibility and is translated to a
+ *    level rather than honored as a bound, so a numeric budget is refused with
+ *    a pointer at `reasoningEffort`.
+ *  - Gemini 2.5 expresses it as a numeric BUDGET
+ *    (`thinkingConfig.thinkingBudget`); `0` turns thinking off on Flash and
+ *    Flash-Lite, while Pro has a floor of 128 and answers 400 for less.
+ *  - Gemini 2.0 and earlier have no thinking control at all.
+ */
+/** The provider-neutral effort levels a config may state. */
+export declare const REASONING_EFFORTS: readonly ["none", "minimal", "low", "medium", "high"];
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+/** The smallest budget Gemini 2.5 Pro accepts; it cannot stop thinking. */
+export declare const GEMINI_PRO_MIN_THINKING_BUDGET = 128;
+export interface PromptReasoningInput {
+    provider?: string | null;
+    model?: string | null;
+    reasoningEffort?: string | null;
+    reasoningBudget?: number | string | null;
+}
+/** What the executor adds to the upstream request, or `null` for "unset". */
+export type PromptReasoningDirective = {
+    provider: "openrouter";
+    /** The OpenRouter `reasoning` block. */
+    reasoning: Record<string, unknown>;
+    /**
+     * `provider: { require_parameters: true }` — routing restricted to
+     * endpoints that support every parameter in the request.
+     */
+    requireParameters: true;
+} | {
+    provider: "gemini";
+    /** The `generationConfig.thinkingConfig` block. */
+    thinkingConfig: Record<string, unknown>;
+};
+export type PromptReasoningResolution = {
+    ok: true;
+    directive: PromptReasoningDirective | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * How a Gemini model spells its thinking control.
+ *
+ * `level` — Gemini 3.x, `thinkingLevel`, cannot be turned off.
+ * `budget` — Gemini 2.5, `thinkingBudget` in tokens.
+ * `none` — Gemini 2.0 and earlier, no control at all.
+ */
+export type GeminiReasoningFamily = "level" | "budget" | "none";
+export declare function geminiReasoningFamily(model: string): GeminiReasoningFamily;
+/** Gemini Pro: the tier that cannot stop thinking in either family. */
+export declare function isGeminiProModel(model: string): boolean;
+/** Is EITHER reasoning key stated on this config? */
+export declare function hasPromptReasoning(input: PromptReasoningInput): boolean;
+/**
+ * Resolve an authored pair onto the provider's spelling.
+ *
+ * Returns `{ ok: true, directive: null }` when neither key is set — the case
+ * that must leave the upstream payload byte-identical to what it was before
+ * this issue — a directive when the pair maps, and `{ ok: false, error }` when
+ * it does not. The error text is what `config push` reports as the file's
+ * error and what the admin routes answer 400 with.
+ */
+export declare function resolvePromptReasoning(input: PromptReasoningInput): PromptReasoningResolution;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;
 export declare const WEBHOOK_SURFACE: ConfigObjectSurface;
@@ -1753,3 +2222,4 @@ export declare function getConfigTable(label: string, tomlPath: readonly string[
  * names, in declaration order — the coverage guard's anchor (#2644 criterion 2).
  */
 export declare const GENERATED_CONFIG_MODEL_FIELDS: Readonly<Record<string, readonly string[]>>;
+export {};