primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/sync.d.ts

@@ -0,0 +1,2670 @@
+import { Command } from "commander";
+import { ApiClient } from "../lib/api-client.js";
+import { type OperationFormHints } from "../lib/toml-database-config.js";
+import { type FieldForm } from "../lib/toml-native-form.js";
+import { type PushMode } from "../lib/config-payload.js";
+import { type ConfigObjectSurface, type ConfigTable } from "../lib/generated-config-surfaces.js";
+import { type PromptKind } from "../lib/generated-config-surfaces.js";
+import { type AgentFunctionFacts } from "../lib/generated-config-surfaces.js";
+import { type DocumentSchemaResolution } from "../lib/function-document-types.js";
+import { type PresenceOutcome, type TestBlockType } from "../lib/sync-resource-types.js";
+export { resolveSlugCollisions, slugifyTestCaseName, testCaseFileBasenames, } from "../lib/test-case-file-names.js";
+import type { SyncState } from "../types/index.js";
+import { type SyncSelection } from "../lib/sync-selectors.js";
+/**
+ * Wrap a server-side error so the printed message identifies which entity
+ * was in flight. Used by every entity create/update/delete call site in the
+ * push loops (issue #684).
+ *
+ * Format: `Failed to ${action} ${kind} ${key}: ${serverMessage}`
+ *
+ * - `ConflictError` is rethrown unchanged so the existing
+ *   `ConflictError → conflicts[]` accumulator in each loop still fires.
+ * - Other errors are rewrapped as a new `ApiError` carrying the wrapped
+ *   message + the original `details[]` and `statusCode`.
+ */
+export declare function wrapEntityError(err: unknown, action: "create" | "update" | "delete" | "activate", kind: string, key: string): Error;
+/**
+ * Attribute a `[[configs]]` failure to the prompt AND the config (#2972).
+ *
+ * The server describes such a failure in terms of the entry alone ("Config
+ * name already exists for this prompt"), and push applies a prompt through
+ * several requests, so a run over a tree of prompts printed one bare line the
+ * operator could only attribute by reading the create log above it. The pair
+ * is the same identity the server stores the entry under (`promptId#configName`).
+ *
+ * The result is marked `entityNamed`, so the prompt-level wrapper around the
+ * shared update body leaves it alone.
+ */
+export declare function wrapPromptConfigError(err: unknown, action: "create" | "update" | "activate", promptKey: string, configName: string | undefined): Error;
+export declare function computeFileHash(filePath: string): string;
+/**
+ * A transform's comparison hash: the script body itself (#2731 B7).
+ *
+ * Unlike the config types there is no projection to do — the `.rhai` bytes are
+ * exactly what push sends and exactly what diff compares — so the "semantic"
+ * hash is just a stable hash of the body, computable from a server response
+ * without going through the file.
+ */
+export declare function computeScriptBodyHash(body: string): string;
+export declare function shouldPushFile(filePath: string, storedHash: string | undefined): boolean;
+/**
+ * Hash the *expanded* (post-fragment-splice) content of a workflow TOML.
+ *
+ * The raw-file hash (`computeFileHash`) misses fragment-only edits: if a
+ * workflow uses `include = ["x"]` and only `workflow-fragments/x.toml`
+ * changes, the workflow file is byte-identical and shouldPushFile would
+ * skip the push, leaving the server with stale expanded steps.
+ *
+ * This helper hashes the parsed-and-expanded data instead, so fragment
+ * edits change the hash and force a re-push. Pass the already-parsed
+ * `tomlData` (from `parseTomlFile`) — that function runs the expander,
+ * so `tomlData` is the canonical expanded shape the server will see.
+ */
+export declare function computeExpandedContentHash(parsed: any): string;
+/**
+ * Variant of `shouldPushFile` for workflow files: compares the stored hash
+ * against the hash of the *expanded* content rather than the raw file
+ * bytes. Required so that edits to included fragments invalidate the
+ * push-skip cache for any workflow that references them.
+ */
+export declare function shouldPushExpandedFile(parsed: any, storedHash: string | undefined): boolean;
+/**
+ * The `[workflow].activeConfigName` a file actually states, trimmed — or
+ * `undefined` when the file has no opinion about activation.
+ *
+ * Push reads the key the same way: `applyWorkflowConfigSidecars` activates a
+ * configuration only for a truthy name and otherwise leaves the running one
+ * alone (`cli/src/lib/workflow-config-apply.ts`). Every diff decision about
+ * activation keys off this one predicate so the comparison cannot claim a
+ * difference push has no way to reconcile (#2743, review follow-up).
+ */
+export declare function authoredActiveConfigName(parsed: any): string | undefined;
+/**
+ * The configuration a server workflow is RUNNING — its `activeConfigId`, or the
+ * first config as the fallback `serializeWorkflow` has always used, so pull's
+ * `activeConfigName` and the diff's reading of it can never disagree.
+ */
+export declare function resolveActiveWorkflowConfig(workflow: any, configs: any[]): any;
+/**
+ * Normalize a parsed workflow TOML object into the form the SERVER would hold
+ * after a `config push` of that file. Used by `diff` so a hand-authored workflow
+ * compares equal to the running state it already describes — while a server
+ * value that genuinely differs still shows as Modified.
+ *
+ * In order:
+ *   1. Trim the fields the server trims (`name`, `description`).
+ *   2. Drop explicit-empty authored values — a `""` string or an empty
+ *      `capabilities` array. Push sends these as `null` (or the model default),
+ *      and the pull serializer omits the key for a cleared field, so "spelled
+ *      out as empty" and "absent" have to hash the same (#2743).
+ *   3. Lowercase the two enums and floor the five queue limits, mirroring the
+ *      server's accepted-value canonicalization
+ *      (`src/workflows/config/workflow-field-handlers.ts`). A value the server
+ *      would REJECT is left alone: push fails loudly for those, so there is
+ *      nothing to preview. #2743 — without this, `dequeueOrder = "LIFO"` or
+ *      `perUserMaxRunning = 4.9` pushes fine and then reports Modified forever.
+ *   4. Fill the model defaults (`WORKFLOW_MODEL_DEFAULTS`) for what the file
+ *      omits. `perAppMax*` / `queueTtlSeconds` joined that list in #1177: once
+ *      the pull serializer emitted them (a GET always returns them, they carry
+ *      a non-null model default), an unchanged workflow hashed unequal to a
+ *      local TOML that omits them — a false `modified` that made `config pull`
+ *      rewrite the file just to inject defaults. (`status` was on this list
+ *      until #2803 took availability off the config wire entirely.)
+ *   5. Fill `activeConfigName` with the name the server itself creates
+ *      (`default`), so a hand-authored file that never named a config compares
+ *      equal to the workflow that pushing it produces (#2743). This is the
+ *      compare-BY-NAME case only: when the local file names no configuration at
+ *      all, `config diff` hashes both sides with `compareActivation: false` and
+ *      the fill never decides anything.
+ *   6. Fill `key` from `resolvedKey` when the file omits it. `[workflow].key`
+ *      is optional — push and diff both resolve it from the FILENAME
+ *      (`tomlData.workflow?.key || basename(file, ".toml")`) — while the pull
+ *      serializer always emits it. Without this a file relying on the filename
+ *      hashes unequal to the very workflow it describes and reports Modified
+ *      forever, which is exactly the non-convergence #2743 removes. Callers
+ *      that already know the resolved key pass it; the rest leave the key as
+ *      authored.
+ *
+ * Only the DIFF-hash path (`hashWorkflowTomlForDiff`) normalizes; the stored
+ * content-hash path that push's skip check compares is untouched, so upgrading
+ * forces no one-time re-push (same note as #1446's schema canonicalization).
+ *
+ * Returns a shallow clone with a normalized `workflow` table; the input is
+ * not mutated. Non-workflow TOML (no `workflow` table) is returned unchanged.
+ */
+export declare function normalizeWorkflowTomlDefaults(parsed: any, resolvedKey?: string): any;
+/**
+ * Canonical content hash of a workflow TOML for `diff`'s content comparison.
+ * Applies `normalizeWorkflowTomlDefaults` first so omitted-vs-defaulted fields
+ * don't spuriously diff, then runs the same `computeExpandedContentHash` that
+ * pull stores and push compares. Both the local file and the
+ * `serializeWorkflow`-produced remote form flow through this single function,
+ * so the two sides are normalized identically by construction.
+ *
+ * `resolvedKey` is the key the caller already paired the two sides on (the
+ * `[workflow].key`, or the filename when the file omits it). Passing it lets a
+ * file that relies on the filename fallback hash equal to the remote form,
+ * which always spells the key out — see `normalizeWorkflowTomlDefaults`.
+ *
+ * `compareActivation: false` drops `activeConfigName` from the hash. `config diff`
+ * passes it when the local file names no configuration: push activates nothing
+ * for such a file, so the configuration the server happens to be running is not
+ * a difference push could ever reconcile, and hashing it in would report the
+ * workflow Modified after every successful push — the non-convergence #2743
+ * exists to remove (review follow-up). The remote name stays visible as a hint
+ * on the Synced row instead. Defaults to comparing, so the include-reconcile
+ * path (`reconcileWorkflowIncludes`, which asks whether the local file already
+ * expands to the running state) keeps seeing activation as content.
+ */
+export declare function hashWorkflowTomlForDiff(parsed: any, resolvedKey?: string, options?: {
+    compareActivation?: boolean;
+}): string;
+/**
+ * Build the canonical content hash for a *server* workflow (as returned by
+ * `getWorkflow` + active `getWorkflowConfig`), mirroring exactly what a fresh
+ * `config pull` would write to disk. Serializes via `serializeWorkflow`, parses
+ * the resulting TOML (remote serialized TOML never carries `include`s, so a
+ * plain `parseConfigToml` is sufficient — no fragment path needed), then hashes
+ * through `hashWorkflowTomlForDiff` so it lines up with the local-file hash.
+ *
+ * `logger` is optional but `config diff` passes it: the serializer's
+ * unrecognized-server-key warning (#2644) is the only signal that this CLI
+ * version cannot represent a field the server holds, and a diff that swallowed
+ * it would report the workflow as in sync with no hint that anything is
+ * missing.
+ */
+export declare function hashRemoteWorkflowForDiff(workflow: any, draft: any, configs: any[], logger?: (message: string) => void, options?: {
+    compareActivation?: boolean;
+}): string;
+export interface ParsedAuthSettings {
+    settings: Record<string, any>;
+    warnings: string[];
+}
+/**
+ * Build the [auth] block of app.toml from server settings (pull direction).
+ *
+ * Thin wrapper over the shared field descriptor
+ * (`cli/src/lib/app-settings-descriptor.ts`), which now owns the [auth] field
+ * set that `AUTH_BOOLEAN_KEYS`/`RECOGNIZED_AUTH_KEYS` used to hard-code. The
+ * descriptor drives all four sections in one place, so pull, push, and the
+ * unrecognized-key warning can never drift apart.
+ */
+export declare function serializeAuthBlock(settings: any): Record<string, any>;
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * direction). Kept as a focused helper over the shared descriptor; the full
+ * push path uses `parseTomlToAppSettings` for every section. Only keys present
+ * in the TOML are forwarded, so an omitted key never overwrites server state.
+ * Descriptor errors (a type mismatch) are surfaced alongside the
+ * unrecognized-key warnings.
+ */
+export declare function parseAppAuthSettings(auth: Record<string, any>): ParsedAuthSettings;
+type VarEntity = {
+    modifiedAt: string;
+    contentHash?: string;
+};
+/**
+ * Decide whether `config pull` should (over)write `vars.toml`, given the outcome
+ * of fetching the app's config vars.
+ *
+ * The distinction that matters (issue #1423 review): a SUCCESSFUL fetch that
+ * returns zero vars is safe to write — the comment-only file is the intended
+ * empty state. A FAILED fetch (transient 401/500/network) must NOT write,
+ * because `serializeVars([])` would clobber a good local `vars.toml` with a
+ * comment-only file while the pull otherwise reports success. On failure we
+ * keep the prior manifest entries so the untouched file and the sync state stay
+ * consistent.
+ *
+ * Pure and side-effect-free (the caller owns the actual `writeFileSync`) so the
+ * clobber guard is unit-testable without a live server.
+ */
+export declare function planVarsPull(outcome: {
+    ok: true;
+    vars: any[];
+} | {
+    ok: false;
+}, priorVars?: Record<string, VarEntity>): {
+    write: boolean;
+    content: string | null;
+    varEntities: Record<string, VarEntity>;
+};
+/**
+ * `config pull --only var/<KEY>` — the same plan, narrowed to the named keys
+ * (issue #2645).
+ *
+ * `vars.toml` is one file for the whole var surface, so a scoped pull cannot
+ * just re-emit what the server returned: that would drop every var the
+ * operator did not name, including local edits they have not pushed yet. The
+ * merge is therefore local-file-first — the file's current keys are kept as
+ * they are, and only the SELECTED keys are taken from the server (or removed,
+ * when the server no longer has them).
+ *
+ * Pure like `planVarsPull`, for the same reason: this is the one place a pull
+ * can silently discard an author's work, so it has to be testable without a
+ * live server.
+ */
+export declare function planScopedVarsPull(serverVars: Array<{
+    key: string;
+    value?: string;
+    updatedAt?: string;
+    modifiedAt?: string;
+}>, selectedKeys: ReadonlySet<string>, localVars: Record<string, string>, priorVars?: Record<string, VarEntity>): {
+    content: string;
+    varEntities: Record<string, VarEntity>;
+};
+/**
+ * Validate a `config push`'s webhook writes against the server's per-app cap.
+ * Returns a list of human-readable errors (empty when the push may proceed).
+ *
+ * Run in `config push`'s up-front preflight (the `planVarsPush` cap pattern) so a
+ * push that would run past the cap aborts BEFORE any mutation. Without it the
+ * push creates webhooks one at a time until the server rejects one at the cap,
+ * leaving a partial push.
+ *
+ * **Only creates are capped.** The server grandfathers apps that already hold
+ * more webhooks than the cap: it refuses new creates and nothing else. A plain
+ * file count would break that — `config pull` writes one toml per webhook, so a
+ * grandfathered app pulls more files than the cap and could then never push
+ * again, its workflows, databases and vars included. So the check compares the
+ * local keys against the keys already on the server: a push that creates
+ * nothing new is always allowed, however far over the cap the app is, and a
+ * push that does create is rejected only when the resulting row count would
+ * exceed the cap.
+ *
+ * The remote key list this runs against comes from `GET
+ * /admin/api/apps/{appId}/webhooks`, which applies no default status filter, so
+ * archived rows are in `remoteKeys` exactly as they are in the server's count.
+ * The two therefore agree on what is already on the server.
+ *
+ * Still advisory rather than authoritative: this counts creates the way the
+ * *config dir* implies, while the apply loop decides create-vs-update from
+ * local sync state, so a checkout with missing sync state issues creates this
+ * check did not predict. Those creates name keys the server already holds, and
+ * the server does not cap a create that adds no row — it answers 409
+ * `WEBHOOK_KEY_EXISTS`, which `adoptByKeyOnCreate409` converges on. A push
+ * allowed here can still be rejected server-side (concurrent writes, a stale
+ * list); that rejection carries `WEBHOOK_LIMIT_REACHED` and names the limit.
+ *
+ * Planned prunes are deliberately NOT netted out of the count: `--prune` runs
+ * after the webhook create loop, so a push that only fits once its prunes land
+ * would still fail mid-apply. Prune first, then push the additions.
+ */
+export declare function validateWebhookCapForPush(localKeys: string[], remoteKeys: string[]): string[];
+/**
+ * Validate a parsed `vars.toml` table against the same key/value constraints
+ * the server enforces (key format, string type, non-empty, size cap) plus the
+ * aggregate per-app var-count cap. Returns a list of human-readable errors
+ * (empty when valid).
+ *
+ * Run in `config push`'s up-front preflight pass (issue #1423 review) so an
+ * invalid entry — or a file that would exceed the server's `MAX_VARS_PER_APP`
+ * cap — aborts BEFORE any mutation is applied. Validating only individual
+ * entries let a 101-entry file create/update many vars before the server
+ * rejected a later create at the cap, leaving a partial push (issue #1423
+ * review pass 3). Pure and side-effect-free so it's unit-testable without a
+ * live server.
+ *
+ * `onlyKeys` narrows the check to the keys a `config push --only var/<key>` will
+ * actually write (issue #2645). A single-object push must not be aborted by an
+ * entry it is not going to touch, so the per-entry checks run over the selected
+ * keys and the file-wide count cap — a property of the whole file, not of these
+ * entries — is left to the plan-level check the caller makes against the final
+ * server count.
+ */
+export declare function validateVarsFile(parsedVars: Record<string, unknown>, options?: {
+    onlyKeys?: ReadonlySet<string>;
+}): string[];
+/**
+ * Plan the config-var writes a `config push` should make, detecting concurrent
+ * remote edits before overwriting them (issue #1423 review).
+ *
+ * This is the client-side half of a two-layer concurrency guard. The vars
+ * PUT/DELETE endpoints now honor an `expectedModifiedAt` precondition (issue
+ * #1423 review r-2 P1) and raise a `ConflictError` when the server row changed
+ * since the caller's snapshot — the atomic, server-side check every other
+ * synced entity relies on. This function is the fast fail-before-mutate layer:
+ * it compares the recorded baseline against the current remote snapshot and, for
+ * a var whose remote value has drifted from what we last synced, reports a
+ * conflict (fed into the same `conflicts[]` accumulator the other entities use)
+ * before any write is attempted. A var tracked at the baseline but absent from
+ * the remote snapshot (deleted remotely while edited locally) is remote drift
+ * too, and also reported as a conflict rather than silently recreated.
+ * Conversely, a var removed locally that is already absent remotely is NOT
+ * planned for deletion — its desired (absent) state is already met, so a DELETE
+ * would 404 and fail the push. The same drift check guards deletions: a var
+ * removed locally whose remote value no longer matches the baseline was edited
+ * remotely since the last sync, and deleting it would silently discard that
+ * edit — reported as a conflict instead. `force` skips the conflict guard,
+ * matching `config push --force` for every other entity.
+ *
+ * A var only the SERVER moved is the other half of the same comparison, and it
+ * is reported rather than skipped (issue #3714). Its local value still equals
+ * the baseline, so there is nothing to push and no conflict — but the skip that
+ * follows from "local is unchanged" used to be taken before the snapshot was
+ * consulted at all, so the push said nothing about a var edited in the Admin
+ * Console and counted it among the skipped-unchanged. The `drifted[]` keys are
+ * what every other synced type reaches through `classifyPushChange` →
+ * `server-drifted`: the caller prints `DRIFT var: <key>` under "Server drift —
+ * not pushed", writes nothing, and leaves the exit code alone. A baseline key
+ * the snapshot no longer holds at all is the same one-sided move (the server
+ * deleted the row; the local file stands still) and is reported the same way.
+ * `--force` is the resolution that keeps the local value, `config pull` the one
+ * that takes the server's.
+ *
+ * Pure and side-effect-free (the caller owns the API calls and sync-state
+ * updates) so the guard is unit-testable without a live server. Assumes
+ * `parsedVars` has already passed `validateVarsFile` (values are strings). The
+ * caller normally fails the push closed when the remote snapshot can't be
+ * fetched, but under `--force` it falls back to an empty snapshot and sets
+ * `snapshotUnavailable` — which keeps removed-key deletions in the plan (they'd
+ * otherwise be mistaken for already-deleted and dropped) and leans on the apply
+ * loop's idempotent 404 handling (issue #1423 review r-2 P2).
+ */
+export declare function planVarsPush(parsedVars: Record<string, string>, baseline: Record<string, VarEntity> | undefined, remoteVars: Array<{
+    key: string;
+    value?: string;
+    updatedAt?: string;
+}>, options?: {
+    force?: boolean;
+    snapshotUnavailable?: boolean;
+}): {
+    upserts: Array<{
+        action: "create" | "update";
+        key: string;
+        value: string;
+        valueHash: string;
+    }>;
+    deletions: string[];
+    conflicts: Array<{
+        key: string;
+        serverModifiedAt: string;
+        localModifiedAt: string;
+    }>;
+    /** Keys the SERVER alone moved — reported, never written (issue #3714). */
+    drifted: Array<{
+        key: string;
+        serverModifiedAt: string;
+    }>;
+    skippedCount: number;
+};
+/**
+ * Compute the number of config vars the server would hold after a push plan
+ * is applied (issue #1423 review pass 5). Validating only the local file's
+ * entry count misses remote-only vars: 95 local entries plus 10 vars that
+ * exist only on the server passes a local-count check, and the creates then
+ * exceed the server's cap mid-push, after earlier writes were already
+ * applied. Counted from the fetched remote snapshot: planned deletions remove
+ * keys that exist remotely (the plan already omits deletes for absent keys),
+ * and only upserts whose key is NOT already on the server add to the total.
+ * Conflicted keys are not mutated, so they contribute nothing beyond their
+ * current remote presence. Pure and side-effect-free so it's unit-testable
+ * without a live server.
+ */
+export declare function countVarsAfterPush(remoteVars: Array<{
+    key: string;
+}>, plan: {
+    upserts: Array<{
+        key: string;
+    }>;
+    deletions: string[];
+}): number;
+/**
+ * Compute the `config diff` rows for config vars (issue #1423 review). Before
+ * this, `config diff` ignored vars entirely, so an add/remove/value-drift between
+ * the local `vars.toml` and the server read as no difference. Value-aware: a
+ * var present on both sides whose value differs is reported as `modified`
+ * (framed like the other content-aware entities — `config pull` would rewrite the
+ * local value). Pure and side-effect-free so it's unit-testable without a live
+ * server.
+ */
+export declare function diffVars(localVars: Map<string, string>, remoteVars: Map<string, string>): Array<{
+    type: "var";
+    key: string;
+    status: string;
+    hint?: string;
+}>;
+/**
+ * Which of a workflow's configs `config pull` writes as sidecar files
+ * (issue #2645, spec §Contracts/Named configs).
+ *
+ * Every config EXCEPT the active one. The active config's body is already the
+ * `steps` at the top of `workflows/<key>.toml` — that is where authors edit it
+ * and where `applyWorkflowBody` writes it — so emitting it again as a sidecar
+ * would put the same body in two files and create a mismatch to adjudicate on
+ * the next push. Two declarations of one piece of state is the shape of problem
+ * this whole issue removes; it would be perverse to introduce one here.
+ *
+ * A config whose steps were not fetched is SKIPPED rather than written empty.
+ * A sidecar is a claim about the server, and `steps = []` is a claim that would
+ * tell the next push to blank a live configuration.
+ *
+ * Pure, so the selection is unit-testable without a live server.
+ */
+export declare function workflowConfigSidecarsToWrite(workflow: any, configs: any[]): Array<{
+    name: string;
+    content: string;
+}>;
+/**
+ * The names a workflow's configs occupy on the server, whatever their body.
+ *
+ * `workflowConfigSidecarsToWrite` deliberately skips a config whose steps were
+ * not fetched, so it cannot answer "which sidecar files are stale". This can:
+ * a local file whose name is absent HERE names a config the server no longer
+ * has, which is the only safe basis for deleting it (issue #2645, review
+ * follow-up).
+ */
+export declare function workflowConfigNamesOnServer(workflow: any, configs: any[]): Set<string>;
+/**
+ * Delete the sidecars naming a config the server no longer has (#2645).
+ *
+ * Pull is what makes the repo describe the server, and a sidecar left behind
+ * after its config was archived — or after that config became the active one,
+ * whose body is the workflow file's `steps` — is a file that would RE-CREATE it
+ * on the next push. The repo would then be silently undoing the archive.
+ *
+ * Returns the file names removed, so pull can say what it did.
+ */
+export declare function removeStaleWorkflowConfigSidecars(configDir: string, key: string, namesOnServer: Set<string>): string[];
+/**
+ * The content hash `config push` skips a workflow on — sidecars included.
+ *
+ * The stored hash used to cover `workflows/<key>.toml` alone, so editing or
+ * adding a named config sidecar without touching the workflow file left the
+ * hash unchanged: push reported success and made no call at all, which is
+ * worse than failing (issue #2645, review follow-up). The named configs are
+ * part of what push applies, so they are part of what push compares.
+ *
+ * A workflow with no sidecars hashes exactly as before, so the common case
+ * does not re-push once on upgrade. An unreadable sidecar hashes to a distinct
+ * value rather than throwing: a hash is a comparison, and the parse error
+ * belongs to the apply path, which raises it with the file name attached.
+ */
+export declare function workflowHashInput(configDir: string, key: string, parsedWorkflowToml: any): any;
+/** See `workflowHashInput`. */
+export declare function computeWorkflowContentHash(configDir: string, key: string, parsedWorkflowToml: any): string;
+/**
+ * Canonical hash of a named config sidecar, for `config diff` (#2645).
+ *
+ * Hashes the parsed body rather than the bytes so comment and key-order
+ * differences do not read as drift — the same semantic comparison `config diff`
+ * makes everywhere else (spec criterion 3).
+ */
+export declare function hashWorkflowConfigSidecar(parsed: any): string;
+/**
+ * Does the file's `[workflow].activeConfigName` name a configuration that the
+ * push could actually activate (#2743, review follow-up)?
+ *
+ * The diff normalizer equates an omitted `activeConfigName` with `default` —
+ * the name the server itself gives the config it creates — so a file that
+ * spells `default` out hashes equal to the omitted form. For a workflow with no
+ * configuration at all (a legacy row the GET's auto-migration could not heal),
+ * the remote side serializes an EMPTY active config name and normalizes to
+ * `default` too, so the pair hashes equal while `config push` would stop on
+ * `activeConfigName "default" names no configuration`. Reporting Synced for a
+ * file whose next push fails is the one drift a change gate must not skip.
+ *
+ * A name the repo carries as a sidecar resolves: push creates that config and
+ * activates it (and the sidecar comparison already reports the difference).
+ * Read-only and non-throwing, like every other diff predicate.
+ */
+export declare function workflowActiveConfigNameUnresolvable(configDir: string, key: string, localParsed: any, configs: any[]): boolean;
+/**
+ * The `config diff` note for a workflow whose file names no configuration while
+ * the server runs one other than the `default` it creates itself (#2743, review
+ * follow-up).
+ *
+ * Such a file is not drift push can act on: activation is preserved, not
+ * converged, so the row is Synced — the alternative, reporting Modified,
+ * repeats forever because no push changes it. But the repo does not describe
+ * which configuration is live, and only `config pull` records it, so the fact is
+ * carried as a hint on the Synced row — the same way an operational disable is
+ * (`outOfServiceHint`). The server-created `default` is the shape a
+ * hand-authored file already means, so it is silent.
+ *
+ * Pure and non-throwing, like every other diff predicate. Returns the existing
+ * hint untouched when there is nothing to add.
+ */
+export declare function unmanagedActiveConfigHint(localParsed: any, workflow: any, configs: any[], existingHint?: string): string | undefined;
+/**
+ * Drop the archived rows from a pull listing (#2803).
+ *
+ * A tombstone is retired, not configuration. Exporting one wrote a file the
+ * repo then claimed to describe — and, once `status` left the TOML surface, a
+ * file whose very next push would fail on the `status` line it carried.
+ * `config push --prune` is the path that reclaims an archived row; pull's job
+ * is to describe what is configured.
+ */
+export declare function skipArchivedForPull<T extends {
+    status?: unknown;
+}>(items: T[]): T[];
+/**
+ * The sync-state entries a pull keeps for the archived rows it did NOT export
+ * (#2803).
+ *
+ * Pull removes a tombstone's file, and prune candidates come only from prior
+ * sync state — so dropping the state entry with the file would strand the row:
+ * no file to delete, no managed key to prune, and (for webhooks and cron
+ * triggers) a cap slot and a reserved key nothing could ever reclaim, which is
+ * the exact failure #2232 fixed. So the pull records the tombstone instead: no
+ * file, but a managed entry carrying the archived row's CURRENT `modifiedAt`,
+ * so the next opt-in, confirmed `config push --prune` point-reads it, finds it
+ * unchanged, and hard-deletes it — the reclamation path the model promises.
+ *
+ * Only keys the config tree already managed are recorded. A row archived
+ * server-side that this repo never described is not this repo's to delete.
+ *
+ * Pure, so it is unit-testable without a live server.
+ */
+export declare function archivedTombstoneEntries(items: any[], select: {
+    keyOf: (item: any) => string;
+    idOf: (item: any) => string;
+}, managedKeys: Iterable<string>): Record<string, {
+    id: string;
+    modifiedAt: string;
+}>;
+/**
+ * Fold one type's tombstone entries into the sync state this pull is building
+ * (#2803, corrected by #2887).
+ *
+ * Two rules, and the second one is the fix. A tombstone is recorded only for a
+ * key this pull did NOT export (an exported key is a live row and its own
+ * record) and only when the selection covers it. And a recorded key is marked
+ * as MATCHED: archived rows are dropped before `selectPull` runs, so the
+ * selector that named one never reached the set that decides whether the pull
+ * found what it was asked for. `config pull --only workflow/<key>` against an
+ * archived managed row therefore removed the file, saved the tombstone, and
+ * then exited 1 saying "the server has no workflow/<key>" — a failure report
+ * about a mutation that had already succeeded, which is the worst thing an
+ * automation can be told. The fix is generic, so integrations and webhooks
+ * (which had the bug first) get it too.
+ *
+ * Mutates `built` and `matchedSelectors` and returns the keys it recorded, so
+ * the caller can report each one. Pure otherwise, and unit-testable.
+ */
+export declare function recordArchivedTombstones(built: Record<string, {
+    id: string;
+    modifiedAt: string;
+}>, tombstones: Record<string, {
+    id: string;
+    modifiedAt: string;
+}>, context: {
+    label: string;
+    selection: SyncSelection | null;
+    matchedSelectors: Set<string>;
+}): string[];
+/**
+ * The `config diff` annotation for an object an operator took out of service
+ * (issue #2645, criterion 9; #2803).
+ *
+ * Availability is deliberately not a TOML key, so an object that is out of
+ * service is NOT drift — the committed configuration still describes it
+ * exactly. Saying so out loud is the point: the reason the control exists is
+ * that an out-of-band write used to make `config diff` report a difference
+ * nobody intentionally created (#1976). Reporting it as a hint on an
+ * otherwise-`Synced` row is what keeps that promise visible instead of merely
+ * true.
+ *
+ * Reads either spelling: the canonical `status: "inactive"` for a type that has
+ * cut over to #2803's single control, and the superseded
+ * `operationallyDisabled` boolean for one that has not yet.
+ *
+ * An ARCHIVED row gets its own annotation. `config pull` no longer exports
+ * tombstones, so without one an archived webhook or integration whose file is
+ * still in the tree read as plain `Synced` — the one status where "the server
+ * has exactly what the file says" is most misleading.
+ *
+ * When the row already carries a hint — a real content difference — the toggle
+ * is APPENDED rather than substituted: the drift is the part that needs acting
+ * on, and dropping it to announce the pause would hide the more urgent fact.
+ *
+ * Pure, so it is unit-testable without a live server.
+ */
+export declare function outOfServiceHint(remote: any, existingHint?: string): string | undefined;
+/**
+ * Serialize an integration DETAIL response to its `integrations/<key>.toml`.
+ *
+ * #2631: `accessRule` is the CEL expression gating who may call the
+ * integration. It comes back on the detail only (not the list summary), and it
+ * is written to TOML so `config pull` → `config push` round-trips the rule instead
+ * of clearing it. A null/empty rule has no TOML representation and is simply
+ * omitted; the push path sends `null` for an omitted rule, which matches the
+ * server state it came from.
+ */
+export declare function serializeIntegration(integration: any, logger?: (message: string) => void): string;
+/**
+ * Build the `config push` body for one integration TOML.
+ *
+ * `accessRule` follows the #1567 TOML-owned rule: send value-or-`null` so
+ * removing the line from the file clears the rule server-side rather than
+ * leaving a stale one live. There is deliberately NO local "rule is required"
+ * check here — a remote integration missing from local sync state is pushed as
+ * a create, expected to 409, and adopted by key (#1006); a local check would
+ * strand that path. The server decides (#2631).
+ */
+export declare function buildIntegrationPushPayload(key: string, tomlData: any, { mode }?: {
+    mode?: PushMode;
+}): Record<string, any>;
+export declare function webhookConfigToTomlTable(scheme: string, config: any): Record<string, any> | undefined;
+export declare function tomlTableToWebhookConfig(scheme: string, table: any): Record<string, any> | undefined;
+export declare function serializeWebhook(webhook: any, logger?: (message: string) => void): string;
+/**
+ * Build the `config push` body for one webhook TOML.
+ *
+ * The `[webhook]`-derived half comes from the vendored definition; the four
+ * structural tables the file also carries (`[allowedIps]`, `[inputMapping]`,
+ * `[metadata]`, `[verification.<scheme>]`) keep their own conversion, which is
+ * why the definition declares them `structural` rather than as fields.
+ */
+export declare function buildWebhookPushPayload(key: string, tomlData: any, { mode }?: {
+    mode?: PushMode;
+}): Record<string, any>;
+export declare function serializeCronTrigger(trigger: any, logger?: (message: string) => void): string;
+/**
+ * Build the `config push` body for one cron-trigger TOML.
+ *
+ * `state` is absent from the create body because the definition says the create
+ * handler assigns it (`writableOn: ["update"]`) — the CLI used to send it and
+ * the server used to drop it silently.
+ */
+export declare function buildCronTriggerPushPayload(key: string, tomlData: any, { mode }?: {
+    mode?: PushMode;
+}): Record<string, any>;
+export declare function serializeBlobBucket(bucket: any, logger?: (message: string) => void): string;
+/**
+ * Build the PATCH payload for a blob-bucket update from local TOML.
+ *
+ * EXACT extraction of the inline builder shared by the existing-update and
+ * 409-adopt branches — do NOT "clean up" the truthiness checks on the access
+ * model. The server treats `preset` and `accessPolicy` as mutually exclusive,
+ * only clears `ruleSetId` when a preset/accessPolicy is also present, and
+ * refuses to leave a bucket with no access model or a blank name — so those
+ * fields are not clearable. `bucketKey` and `ttlTier` are immutable and never
+ * sent. Both call sites must go through this helper so their field sets never
+ * drift.
+ */
+export declare function buildBlobBucketUpdatePayload(bucket: any): any;
+/**
+ * #3201's post-create status patch is RETIRED — #3799 (DSO-3799-005).
+ *
+ * `status` was update-only, so `POST /prompts` and `POST /prompts/:id/configs`
+ * both assigned `active` whatever the body said, and an authored
+ * `status = "archived"` needed a follow-up PATCH ordered after the activation of
+ * the entry the file marks live. Both create paths honor the key now
+ * (`writableOn: BOTH`, validated by one rule on all three paths), so the entry
+ * lands retired on its own create: the same end state, two fewer calls per
+ * retired config, and no window in which the server holds a status the file
+ * never asked for. That window is what made a pulled tree unpushable into a
+ * fresh environment once an agent's schemas are checked against each
+ * non-archived config's provider — the check fired on the transient active
+ * state.
+ */
+/**
+ * Which `[[configs]]` entry a prompt file marks as live (issue #2645).
+ *
+ * Exactly one entry may carry `active = true`. Two is an error rather than a
+ * first-wins rule: making the file's meaning depend on entry order is the kind
+ * of implicit behavior this issue exists to remove, and silently picking one
+ * would let the repo claim something the server does not do.
+ *
+ * `isActive` is accepted as a legacy spelling — the create leg read it before
+ * pull ever wrote a marker, so a hand-authored file carrying it keeps working.
+ */
+export declare function promptActiveConfigName(configs: any[]): string | undefined;
+/**
+ * The push payload for one `[[configs]]` entry of a prompt (issue #2645).
+ *
+ * One builder for both directions so create and update cannot drift: a field
+ * the file owns has to reach the server whether the config is new or already
+ * there, which is what "removing a flag removes no capability" means in
+ * practice.
+ *
+ * `description` is sent as `?? null` on update and omitted on create (#1567):
+ * dropping the key from a `[[configs]]` block must CLEAR it on an existing
+ * config, and the PATCH nulls on an explicit `null` while preserving on omit.
+ * `status` is the opposite — omitted means "unchanged", because the server
+ * defaults a new config to active and an existing one keeps what it has.
+ */
+export declare function promptConfigPayload(tomlConfig: any, options?: {
+    create?: boolean;
+}): Record<string, any>;
+/**
+ * Build the POST body for a blob-bucket create from local TOML.
+ *
+ * `ttlTier` is here and absent from the update body because the definition says
+ * so (`writableOn: ["create"]`) — the retention tier is fixed at creation.
+ */
+export declare function buildBlobBucketCreatePayload(key: string, bucket: any): Record<string, any>;
+export declare function serializePrompt(prompt: any, logger?: (message: string) => void): string;
+/**
+ * The `config push` warning for a resource pushed with no `accessRule` (#2652).
+ *
+ * Returns `null` when a rule is declared — and for a `runAs = "system"`
+ * workflow, which rejects any rule and cannot be started by a member at all.
+ * Otherwise it names the resource, the consequence, and the one-line restore,
+ * because after the #2652 flip a ruleless prompt or caller workflow denies
+ * every non-admin caller from the deploy onward.
+ *
+ * Both kinds now push `accessRule` as value-or-`null` — the prompt since #1567,
+ * the workflow since #2743's always-send conversion — so for either one an
+ * omitted key really does leave the resource ruleless on the server. The
+ * workflow wording says so explicitly, because it used to say the opposite
+ * (the update path preserved a stored rule) and an operator who learned that
+ * caveat needs to see it retracted.
+ */
+export declare function missingAccessRuleWarning(opts: {
+    kind: "prompt" | "workflow";
+    key: string;
+    accessRule: unknown;
+    runAs?: unknown;
+}): string | null;
+/**
+ * Build the `config push` body for one prompt TOML's `[prompt]` table.
+ *
+ * The prompt's own fields only — its `[[configs]]` entries are separate
+ * requests, built by `buildPromptConfigPayload`.
+ */
+export declare function buildPromptPushPayload(key: string, tomlData: any, { mode }?: {
+    mode?: PushMode;
+}): Record<string, any>;
+/**
+ * Build the POST body for a prompt create.
+ *
+ * `POST /prompts` is the one endpoint that writes BOTH models: the prompt, and
+ * the "default" `AppPromptConfig` it seeds from the same body. So this body is
+ * the `[prompt]` table's create half plus the FIRST `[[configs]]` entry's LLM
+ * settings — minus the three keys the prompt half owns or the handler assigns
+ * itself:
+ *
+ *   - `configName`  — the seeded config is always named "default".
+ *   - `description` — the body's slot belongs to the PROMPT, and the handler
+ *     hard-codes the seeded config's to "Default configuration". An authored
+ *     `[[configs]]` description therefore has nowhere to go in this body, so
+ *     push applies it right after the create rather than losing it.
+ *   - `outputSchema` — same shape: the body's slot is the prompt's, so the
+ *     seeded config's own value is applied by the follow-up PATCH
+ *     (`seededOnlyPromptConfigFields`) instead of being dropped.
+ *
+ * Every other config field rides along from the definition, so a new LLM
+ * setting reaches a brand-new prompt without an edit at this call site.
+ */
+export declare function buildPromptCreatePayload(key: string, tomlData: any): Record<string, any>;
+/**
+ * The PATCH body reconciling the seeded config with the first `[[configs]]`
+ * entry, or `null` when the entry needs none of it.
+ *
+ * #2972 — the entry's NAME belongs in this patch too. The create handler names
+ * the seeded config "default" whatever the entry is called, so a file whose
+ * first entry is named anything else got that entry's settings stored under
+ * "default": a later entry actually named "default" then collided with it and
+ * the push died half-applied, and a file naming no entry "default" quietly
+ * landed a config it never mentions while its first entry never existed. Both
+ * end here, because the rename runs before any further config is created.
+ *
+ * `seededConfigName` is what the server called it — read from the create
+ * response rather than assumed, so a handler that one day honors the name
+ * produces no needless PATCH.
+ *
+ * #3201 — the entry's `status` was deferred the OTHER way, to a patch after the
+ * activation, because the create pointed the prompt's `activeConfigId` at a
+ * config it had forced live. #3799 (DSO-3799-005) — the create carries the
+ * entry's `status` itself now, so there is no deferral either way and this patch
+ * is the two fields `POST /prompts` cannot express, nothing more.
+ */
+export declare function seededOnlyPromptConfigFields(firstConfig: any, seededConfigName?: string): Record<string, any> | null;
+/**
+ * Build the create/update body for ONE `[[configs]]` entry.
+ *
+ * `create` carries the provider/model defaults a brand-new config needs; on
+ * update those defaults must NOT be applied, or editing an unrelated key would
+ * silently re-point a config at the default model.
+ */
+export declare function buildPromptConfigPayload(tomlConfig: any, { mode }?: {
+    mode?: PushMode;
+}): Record<string, any>;
+/**
+ * Rewrite a workflow TOML file's string-form `inputSchema` / `outputSchema` to
+ * native object form for `config migrate-toml` (issue #1446).
+ *
+ * Purely local, no server fetch. Parses the raw source WITHOUT expanding
+ * fragment `include`s (so those directives survive the rewrite), swaps a
+ * JSON-string schema for its parsed object when it round-trips faithfully
+ * (`canEmitNative === null`), and re-serializes via `stringifyConfigToml`.
+ *
+ * Only rewrites when a field is actually converted: a file whose schemas are
+ * already native, absent, or un-representable (a `null` default) is returned
+ * with `changed: false` and its original bytes untouched — so migrate is
+ * idempotent and never reports a spurious migration or reformats a file it
+ * didn't need to touch.
+ */
+export declare function rewriteWorkflowSchemasToNative(rawToml: string, workflowKey?: string, log?: (message: string) => void): {
+    content: string;
+    changed: boolean;
+};
+/**
+ * #2644 — `config push` rejects any key the vendored definition does not
+ * recognize, so a mistyped or newer-server key fails locally instead of being
+ * silently dropped on the way to the server (design gate, 2026-08-12). Returns
+ * the error message, or null when every key is known.
+ *
+ * Works for any migrated type, single or repeated: a repeated table's entries
+ * are checked one by one and the unknown keys reported together, so a typo in
+ * the third `[[configs]]` block is as loud as one in the first.
+ */
+export declare function configUnknownKeyError(filePath: string, tomlData: any, table: ConfigTable): string | null;
+/**
+ * #2644 — the document-level half of the same rejection: a top-level table the
+ * object's definition does not declare, or a field table written with the wrong
+ * array markers. Returns one message per problem, or `[]` when the file's shape
+ * is recognized.
+ *
+ * Unrecognized keys INSIDE a table were already rejected; a mistyped table
+ * HEADER was not, and it is the more destructive of the two — `[integraton]`
+ * leaves `[integration]` absent, so the push builder reads an empty table and
+ * sends `description: null` / `accessRule: null`, CLEARING them server-side.
+ * The design gate settled the posture (2026-08-12): push rejects everything
+ * unknown, tables included.
+ */
+export declare function configDocumentShapeErrors(filePath: string, tomlData: any, surface: ConfigObjectSurface): string[];
+/**
+ * Which directories `config push` checks for unrecognized keys, and against which
+ * tables.
+ *
+ * Derived from the registry crossed with `SYNC_RESOURCE_TYPES`, so a type
+ * gains the check by being defined — nobody has to remember to list it here.
+ *
+ * Workflows carry an EMPTY `tables` list: `validateWorkflowToml` already
+ * reports their `[workflow]` keys alongside the #685 misnest check, in one
+ * message per file, but nothing checked a workflow file's top-level tables —
+ * so the surface is listed here for the document-level check and skipped for
+ * the per-table one.
+ */
+export declare function unknownKeyPreflightTargets(): Array<{
+    dir: string;
+    surface: ConfigObjectSurface;
+    tables: ConfigTable[];
+}>;
+/** One config file the TOML preflight rejects, and the row it belongs to. */
+export interface ConfigFileValidationError {
+    /** The `config diff` row type, e.g. `prompt`. */
+    type: string;
+    /** The row key the local file pairs on. */
+    key: string;
+    filePath: string;
+    /** The messages, verbatim — the same text `config push` aborts with. */
+    messages: string[];
+}
+/**
+ * `config push`'s preflight — every check the authored files decide on their
+ * own, run before the FIRST mutating call (#976 fix A, #3320, #3375).
+ *
+ * The block below was inline inside the push command's `.action()` callback
+ * until #3375 lifted it here unchanged. It had to become an exported symbol
+ * for the registry's promise to be checkable at all: a rule declared
+ * `preflight` says it runs before `config push` mutates anything, and
+ * `src/config-surface/preflight-reachability.ts` resolves that claim
+ * statically from the declared `<module>#<export>` against exactly this entry
+ * point. With the preflight anonymous, "reached from the preflight" had
+ * nothing to resolve against, and the stage string was satisfied by typing it.
+ *
+ * Its boundary is therefore precise and load-bearing: this function is what
+ * contributes to `preflightValidationErrors` and aborts. The advisory reads
+ * that follow the abort in the action — the remote vars snapshot and both caps
+ * — stay there and are declared `apply`, because the server is what enforces
+ * them (`intent` §Non-goals, "Emptying the apply stage").
+ *
+ * A network call inside a preflight is not disqualifying: `listIntegrations`
+ * was already here, answering "will this `integration:` grant have a target?"
+ * against the live listing merged with the tree, and falling back to the tree
+ * alone when the listing cannot be fetched.
+ *
+ * `input` names what the block used to close over. `client` is narrowed to the
+ * one method it calls, so an apply call cannot drift in here later without
+ * that being a visible change to this signature.
+ */
+export declare function runConfigPushPreflight(input: {
+    configDir: string;
+    resolvedAppId: string;
+    pushSelection: SyncSelection | null;
+    syncState: SyncState | null;
+    force: boolean;
+    isCrossAppPush: boolean;
+    client: Pick<ApiClient, "listIntegrations" | "listFunctions">;
+}): Promise<{
+    parsedVars: Record<string, unknown> | null;
+}>;
+export declare function promptKindFileErrors(filePath: string, tomlData: any): string[];
+/**
+ * The functions an agent's references are checked against at push — #3798,
+ * DSO-3798-002.
+ *
+ * `config push` applies prompts, then (for agents) the server functions leg,
+ * so a reference may be satisfied by a function that is live already or by one
+ * this push creates. What the push BELIEVES is therefore the live listing
+ * overlaid by the function files this push SELECTS (`--only`, every file when
+ * unscoped): a selected file's schemas are what the server will hold after the
+ * push, so it wins over the live row. An UNSELECTED file is not read at all —
+ * its edits will not be applied, and a function only it declares will not
+ * exist afterwards.
+ *
+ * `live` is `null` when the listing could not be fetched: the selected files
+ * still count, and `liveListed` lets the refusal say why every other reference
+ * could not be confirmed. A live row that is archived is a tombstone, not a
+ * function; an inactive one is accepted (the turn engine re-checks
+ * availability on every call).
+ */
+export declare function agentFunctionFactsForPush(input: {
+    configDir: string;
+    pushSelection: SyncSelection | null;
+    live: ReadonlyArray<Record<string, unknown>> | null;
+}): {
+    facts: AgentFunctionFacts;
+    liveListed: boolean;
+};
+/**
+ * The function half of an agent's declaration — #3798: every tool, turn
+ * context and history function that the functions this push believes
+ * (`agentFunctionFactsForPush`) do not have, and every tool function lacking an
+ * input or output schema. The same `resolveAgentDeclaration` the admin routes
+ * run; only its function refusals are reported here, because the collector
+ * (`promptKindFileErrors`) already reported the file-decidable ones.
+ */
+export declare function promptAgentFunctionErrors(filePath: string, tomlData: any, known: {
+    facts: AgentFunctionFacts;
+    liveListed: boolean;
+}): string[];
+/**
+ * The order `config push` applies prompt files in — #3798. An agent names
+ * server functions that must exist when it is created, and the push applies
+ * prompts before functions, so agent files go AFTER the server-functions leg;
+ * every other file keeps its place. A file that does not parse stays first, so
+ * the leg reports it where it always has.
+ */
+export declare function partitionPromptFilesForPush(promptsDir: string, files: readonly string[]): {
+    beforeFunctions: string[];
+    afterFunctions: string[];
+};
+/**
+ * Every `prompts/<key>.tests/*.toml` sidecar whose prompt is an agent — #3798
+ * (§D1: prompt test cases are refused for the kind in v1). The admin test-case
+ * routes refuse the same case with `AGENT_TEST_CASE_NOT_SUPPORTED`; this says
+ * so before anything is applied.
+ */
+export declare function promptAgentSidecarErrors(configDir: string): string[];
+/**
+ * The immutable-`kind` refusal for a prompt update the comparison gate did not
+ * decide — #3626, CR3626-001.
+ *
+ * `kind` is create-only (D3626-008), and the gate refuses a change to it on
+ * every path that compares the two sides. Two update paths do not compare: a
+ * prompt whose DETAIL read failed falls back to the manifest byte-hash gate,
+ * which `--force` writes straight through, and a prompt ADOPTED after a
+ * create's 409 is re-issued as an update without a comparison at all. Both
+ * would otherwise PATCH the file's schemas, access rule and metadata onto a
+ * row of the other kind, and only then have its configs refused against the
+ * kind the update cannot change.
+ *
+ * Returns the gate's own outcome shape, so `recordDeclined` prints the same
+ * two values and the same remedy — create the prompt under a new key.
+ *
+ * `null` when the kinds agree and when the server's kind is simply not KNOWN:
+ * a push that could not read live state at all has nothing to compare, and
+ * that path's contract (`decideDegradedPush`, #2880) is already "decline
+ * unless the operator forces it", stated for every field at once.
+ */
+export declare function promptKindImmutableOutcome(storedKind: PromptKind | undefined, localDoc: any): Extract<PushGateOutcome, {
+    action: "immutable";
+}> | null;
+/**
+ * The one deprecation notice a prompt file using the FLAT chat spelling earns
+ * — #3626 §4, beside the `celContextAccess` notice's precedent.
+ *
+ * Advisory: the push continues and the keys are applied. `null` when the file
+ * is already written in the grouped spelling, so a migrated tree is silent.
+ */
+export declare function promptFlatChatKeyWarning(filePath: string, tomlData: any): string | null;
+export declare function collectConfigFileValidationErrors(configDir: string): ConfigFileValidationError[];
+/**
+ * Every `functions/<key>.toml` whose file-decidable errors `config push` would
+ * refuse (#3320).
+ *
+ * A second collector rather than a branch inside
+ * `collectConfigFileValidationErrors`, and deliberately so: push calls that one
+ * UNBOUNDED over the whole tree, which is right for the checks it runs (a
+ * mistyped key anywhere means the tree is not pushable) and wrong for these — a
+ * `config push --only webhook/<key>` must not be blocked by a broken function
+ * the operator did not select (#2645). The push path therefore runs these
+ * inside its own `selectFiles`-bounded function loop, and `config diff`, which
+ * compares the whole tree by construction, runs them from here.
+ *
+ * A file that does not parse is skipped: the per-type loop that reads it names
+ * the parse error itself, and reporting it twice helps nobody.
+ */
+export declare function collectFunctionTomlValidationErrors(configDir: string): ConfigFileValidationError[];
+/**
+ * The retired runtime keys every `functions/*.toml` in the tree still carries
+ * — #3482, the warning half of the collector above.
+ *
+ * Separate from the errors because it IS separate: a file carrying one of
+ * these pushes, with every other key applied, so it is not a row `config diff`
+ * calls invalid. It is a line an author reads on stderr from both commands, so
+ * the two keep reading identically (the #2880 symmetry the errors collector
+ * exists for, applied to advice rather than refusals).
+ */
+export declare function collectFunctionTomlIgnoredKeyWarnings(configDir: string): string[];
+/**
+ * The collectors' rows, one per diff row (#2880 symmetry, #3320).
+ *
+ * Two collectors reach the same function file — the definition-driven one
+ * every per-entity type runs, and the function preflight — and a file can
+ * break both at once (a mistyped `entrty`, which then leaves no `entry`).
+ * Push reports every message from both, so an overlay that let one row's
+ * messages REPLACE the other's would drop a diagnostic push prints, which is
+ * exactly the asymmetry #2880 forbids. Merging by row keeps the two commands
+ * reading identically.
+ */
+export declare function mergeConfigFileValidationErrors(collected: ConfigFileValidationError[]): ConfigFileValidationError[];
+/**
+ * Every `<key>.tests/*.toml` sidecar under a config directory.
+ *
+ * Test cases are a registered surface (#2644 phase 3) but they are not a
+ * `SYNC_RESOURCE_TYPES` directory — they live beside the block they test, in
+ * `prompts/<key>.tests/`, `workflows/<key>.tests/`, `transforms/<name>.tests/`
+ * and (since #2769) `integrations/<key>.tests/` — so
+ * `unknownKeyPreflightTargets`, which crosses
+ * the registry with that table, never reaches them. Listing them here gives the
+ * sidecars the same unrecognized-key rejection every per-entity file has
+ * (criterion 6): a mistyped `[test]` key fails the push instead of being
+ * dropped on the way to the server.
+ */
+export declare function testCaseTomlFiles(configDir: string): string[];
+/** The `[workflow]` case of `configUnknownKeyError` (#2644 phase 1). */
+export declare function workflowUnknownKeyError(filePath: string, tomlData: any): string | null;
+/**
+ * Will `config push` reach this workflow key through its UPDATE path?
+ *
+ * The push takes that path when sync state already holds an id for the key —
+ * the `existingId` the apply loop reads. Everything else is a create (including
+ * a create that 409s and adopts by key, which cannot be known before the server
+ * answers). Exported so the front-loaded preflight can decide, before the first
+ * mutating call, which files the update-only `name` pre-check applies to.
+ */
+export declare function isWorkflowUpdateTarget(key: string, syncState: {
+    entities?: {
+        workflows?: Record<string, any>;
+    };
+} | null): boolean;
+/**
+ * Will the apply loop actually SEND this workflow, or skip it as unchanged?
+ *
+ * Mirrors the loop's skip condition (`!force && existingId &&
+ * !shouldPushExpandedFile(...)`): a create always sends, `--force` always
+ * sends, and an update sends only when the expanded content (workflow file plus
+ * its config sidecars) differs from the hash sync state recorded for it.
+ *
+ * Exported so the front-loaded preflight can scope the update-only `name`
+ * pre-check to the files this push will really update. Without that scoping a
+ * workflow created through the manifest-key `name` fallback — an authoring
+ * shape the create path deliberately supports — would push once and then fail
+ * every later push, including a no-change one and its `--dry-run`, on a file
+ * the push was never going to send (#2743, review follow-up).
+ */
+export declare function workflowPushSendsUpdate(configDir: string, key: string, parsedWorkflowToml: any, syncState: {
+    entities?: {
+        workflows?: Record<string, any>;
+    };
+} | null, force?: boolean): boolean;
+/**
+ * The UPDATE path's `name` pre-check (#2743).
+ *
+ * Always-send means the update payload carries `name: value ?? null`, and the
+ * server rejects a `null` name — it is required and cannot be cleared. Caught
+ * here, the operator gets an error naming their file before any PATCH is sent;
+ * caught server-side, they get a bare 400 part-way through a push. Pull always
+ * writes `name`, so a file reaching the update path without one is a deliberate
+ * authoring state, not a round-trip artifact.
+ *
+ * Called from the front-loaded preflight (#976) for every workflow this push
+ * will SEND through the update path (`workflowPushSendsUpdate` — an unchanged
+ * file the apply loop skips is not one) — so it aborts before the first
+ * mutating call and reports under `--dry-run` too — and again inside the update
+ * closure as defense-in-depth, which is also where the adopt-by-key path (a
+ * create the server 409s, unknowable up front) meets it.
+ *
+ * The CREATE path deliberately does NOT call this: it falls back to the
+ * manifest key (`name: workflow.name || key`), which is the accepted way to
+ * author a new workflow whose display name is its key.
+ *
+ * Returns `null` when the name is present.
+ */
+/**
+ * The preflight error a project's document schema contributes, or `null` —
+ * #3719.
+ *
+ * Only a `refusal` counts: a unique constraint on a stringset field, which no
+ * writer can key consistently, so the push stops before any mutation. Every
+ * other unusable-schema case stays the apply loop's warning (D3455-004).
+ */
+export declare function documentSchemaPreflightError(resolution: DocumentSchemaResolution): string | null;
+export declare function workflowUpdateNameError(filePath: string, workflow: any): string | null;
+export declare function serializeWorkflow(workflow: any, draft: any, configs: any[], logger?: (message: string) => void): string;
+export declare function serializeDatabaseType(typeConfig: any, operations: any[], ruleSetIdToName: Map<string, string>, options?: {
+    /** Per-op form hints derived from the existing file. */
+    hints?: OperationFormHints;
+    /** Default form for ops with no hint. New files → "native". */
+    defaultForm?: FieldForm;
+    /** Sink for human-readable fallback messages (logged via `info`). */
+    logger?: (message: string) => void;
+    /** Server subscription rows to emit as `[[subscriptions]]` (issue #803). */
+    subscriptions?: any[];
+}): string;
+/**
+ * Flatten an email-template detail response onto its field surface.
+ *
+ * The API returns `{ emailType, hasOverride, override: {…}, default: {…} }` —
+ * only the `override` half is the field surface (the `default` half is what the
+ * platform ships), which is why both envelope keys are declared
+ * `responseOnlyKeys` in the definition.
+ */
+export declare function emailTemplateOverrideRecord(template: any): Record<string, any>;
+export declare function serializeEmailTemplate(template: any, logger?: (message: string) => void): string;
+/**
+ * Build the upsert body for one email-template TOML.
+ *
+ * `emailType` is deliberately absent: it identifies WHICH built-in template the
+ * override replaces and travels in the URL path, which is what the definition's
+ * `notExposed`/`tomlOnlyKeys` pair records.
+ */
+export declare function buildEmailTemplatePushPayload(tomlData: any): {
+    subject: string;
+    htmlBody: string;
+    textBody: string;
+};
+export declare function serializeRuleSet(ruleSet: any, logger?: (message: string) => void): string;
+/**
+ * The create/update body for one rule-set TOML (#2644).
+ *
+ * The field half comes from the definition — which is what keeps
+ * `resourceType` off the update body, since the update handler never reads it —
+ * and the structural `[rules]` tree is attached beside it.
+ *
+ * `name` is trimmed here because the server trims it before storing
+ * (`rule-sets-controller.ts`, create and update). This body is also what the
+ * comparator projects the local side through (#2731 B1), so leaving the
+ * untrimmed spelling in would compare a name the server will never hold: the
+ * push would "succeed", change nothing, and be planned again on every run.
+ */
+export declare function buildRuleSetPushPayload(tomlData: any, mode: PushMode): Record<string, any>;
+export declare function serializeGroupTypeConfig(config: any, ruleSetIdToName: Map<string, string>, logger?: (message: string) => void): string;
+/**
+ * The create/update body for one group-type config (#2644).
+ *
+ * Takes the entity `parseGroupTypeConfigToml` produced, AFTER the rule-set
+ * name → id resolution: the definition says which fields the server accepts in
+ * each mode, so `groupType` rides the create body and the URL on update.
+ */
+export declare function buildGroupTypeConfigPayload(configData: any, mode: PushMode): Record<string, any>;
+export declare function serializeCollectionTypeConfig(config: any, ruleSetIdToName: Map<string, string>, logger?: (message: string) => void): string;
+/** The create/update body for one collection-type config (#2644). */
+export declare function buildCollectionTypeConfigPayload(configData: any, mode: PushMode): Record<string, any>;
+/**
+ * The upsert body for one metadata-category config (#2644).
+ *
+ * One endpoint serves create and update, so every field is writable in both
+ * modes and the body carries the whole definition-declared surface. The
+ * identity pair rides the URL too (`PUT …/{resourceType}/{category}`); sending
+ * it in the body as well is what the POST form has always taken.
+ */
+export declare function buildMetadataCategoryPayload(configData: any): Record<string, any>;
+/**
+ * Issue #1567 — the TOML-owned fields of a database-type config, derived from
+ * the definition (#2644 phase 3).
+ *
+ * These are fields the `database-type-configs/*.toml` file OWNS: the local file is the
+ * source of truth, so removing one from the TOML must clear it server-side
+ * (config-as-code), not silently preserve the stale value.
+ *
+ * The list used to be written out here, a second statement of the `[type]`
+ * field surface that a new field would have had to be added to by hand. It is
+ * now every exposed `[type]` scalar except the immutable identity, plus the two
+ * sub-trees the definition classifies `structural` and the file nonetheless
+ * owns whole (`triggers`, `metadataManifest`). `schema` is deliberately NOT
+ * owned this way — it keeps its own `hasSchema` prior-state discriminator,
+ * since a schema is a large sub-tree whose absence is ambiguous.
+ */
+export declare function dbTypeOwnedScalars(table?: ConfigTable): string[];
+export declare const DB_TYPE_OWNED_SCALARS: readonly string[];
+/** The user-facing TOML key for a wire field (for push output). */
+export declare function dbTypeFieldLabel(key: string): string;
+/**
+ * True when a value carries real content. null/undefined, blank/whitespace
+ * strings, and empty objects/arrays all count as "no value" — the same
+ * normalization the server applies (`value || null`) when it decides whether a
+ * field is set.
+ */
+export declare function hasMeaningfulValue(v: any): boolean;
+/**
+ * Issue #1567 — always-send owned db-type scalars as value-or-`null`.
+ *
+ * The server PATCH endpoint distinguishes an omitted key (preserve) from an
+ * explicit `null` (clear), so sending every owned scalar as `value ?? null`
+ * converges the server to the local TOML: a field removed from the file lands
+ * as `null` and is cleared. Matches the always-send pattern the sibling
+ * `collection-type-config` push already uses.
+ */
+export declare function buildOwnedScalarUpdate(typeConfig: any): Record<string, any>;
+/**
+ * Issue #1567 — the owned scalars this push genuinely clears: the outgoing
+ * value is empty but the server currently holds a real value (a non-null →
+ * null transition). Used for the "Cleared <field>" report so removing an
+ * access gate is never silent, and to decide whether an otherwise
+ * type-field-less push still needs a type-config PATCH. Returns wire field
+ * names (map with `dbTypeFieldLabel` for output). `serverConfig` is the live
+ * GET; without it (fresh type or a failed fetch) nothing is reported cleared.
+ */
+export declare function ownedScalarsBeingCleared(updateData: Record<string, any>, serverConfig: any): string[];
+/** The look-ahead a type-config PATCH carries about this push's operations. */
+export interface PendingOpClaims {
+    pendingOpDeletes: string[];
+    finalOpNames: string[];
+    pendingOpUpdates: Array<{
+        name: string;
+        access: string | null;
+        params: any;
+    }>;
+    pendingOpUpserts: Array<Record<string, any>>;
+}
+/**
+ * What this push's operation set will BE, stated to the server (issues #813,
+ * #1336, #2732).
+ *
+ * The type-config PATCH runs its gates BEFORE the same push's operation calls,
+ * so without a look-ahead every gate judges the pre-push operations: a push
+ * that removes a model is blocked by the very references it is deleting. The
+ * file IS the target state (config-as-code), so the claims are derived from it:
+ *
+ *   - `finalOpNames` — the names the type ends with. Both other claims are
+ *     verified against it server-side, which is what keeps them from being a
+ *     gate bypass for a direct-API caller.
+ *   - `pendingOpDeletes` — its complement among the ops last sync recorded, so
+ *     an op this push deletes is excluded from the schema / OPS_EXIST gates.
+ *   - `pendingOpUpserts` — the post-push BODY of every declared op, so the
+ *     schema-edit gate lints a rewritten op as rewritten and a model removal
+ *     plus its operation rewrites lands in one push (#2732).
+ *   - `pendingOpUpdates` — the rule-only form (`access`/`params`) the manifest
+ *     re-lint reads (#1336).
+ *
+ * All four are built here and sent together, on the dry-run and on the real
+ * PATCH alike. They are never conditioned on the push having a deletion: a push
+ * that only REWRITES operations is exactly the case #2732 exists for.
+ */
+export declare function buildPendingOpClaims(operations: any[], existingOpNames: string[]): PendingOpClaims;
+export declare function parseDatabaseTypeToml(tomlData: any): {
+    typeConfig: any;
+    operations: any[];
+    subscriptions: any[];
+};
+/**
+ * The parsed shape of a rule-set TOML: the definition's fields plus the
+ * structural `[rules]` tree. Identical to the create body, which is what
+ * `config diff` hashes both sides through.
+ */
+export declare function parseRuleSetToml(tomlData: any): any;
+export declare function parseGroupTypeConfigToml(tomlData: any): any;
+export declare function parseCollectionTypeConfigToml(tomlData: any): any;
+/**
+ * `config diff`'s hash for one configuration object, over the field set its
+ * DEFINITION declares (#2644 criterion 8).
+ *
+ * Both sides — the local file and the server entity — run through this one
+ * function, so a field is visible to `config diff` exactly when the definition
+ * exposes it. Each type used to carry a hand-written
+ * `hashLocal*ForDiff` / `hashRemote*ForDiff` pair naming its own fields: a
+ * third copy of the field surface, with the same failure mode as the other two
+ * (a field pushed and pulled but missing from the hash is invisible to diff, so
+ * an edit reads as "nothing differs" until push applies it).
+ *
+ * `extras` carries the values that are NOT definition fields and must still be
+ * compared: the authored sub-trees the definition classifies `structural`
+ * (`[rules]`, `[[operations]]`, the `[metadata]` manifest) and the
+ * `_unresolvedRuleSetName` marker below. `undefined` entries are dropped so an
+ * absent extra and an omitted one hash the same.
+ */
+export declare function projectConfigForComparison(table: ConfigTable, entity: any, extras?: Record<string, any>): Record<string, any>;
+export declare function hashConfigForDiff(table: ConfigTable, entity: any, extras?: Record<string, any>): string;
+/**
+ * The fields two projected records disagree on — what a conflict report prints
+ * (#2731 B5) and what the immutable-field pre-check reads (B8).
+ *
+ * Compared over the UNION of keys, so a key present on one side only is a
+ * difference rather than a silently ignored one. Values compare by canonical
+ * JSON, which is key-order insensitive for objects and order-SENSITIVE for
+ * arrays — a reordered array is a real change, per the comparator caveats.
+ * Structural sub-trees (`rules`, `schema`, `metadataManifest`, operations,
+ * subscriptions) arrive as single extras keys and therefore compare as units.
+ */
+export declare function diffProjectedRecords(local: Record<string, any>, remote: Record<string, any>): Array<{
+    field: string;
+    local: any;
+    server: any;
+}>;
+/**
+ * The paths at which two projected records disagree, named the way the FILE
+ * spells them (#3267) — what a `config diff` Modified row prints.
+ *
+ * `diffProjectedRecords` answers at the granularity of the projection, and
+ * for a database type that is too coarse to act on: the 27 operations arrive
+ * as one `operations` extra, the whole `[models.*]` tree as one `schema`
+ * string. A row that read Modified for a reason the operator could not see —
+ * an empty params set spelled two ways, an operation block the file declares
+ * twice — was undiagnosable from the CLI. So this walks INTO each differing
+ * field: a keyed child collection (`spec.childKeys`) is compared row by row
+ * and named `operations["getInstitution"].params`, with a row only one side
+ * has or that the file repeats named as such; a TOML-string field
+ * (`spec.tomlFields`) is parsed on both sides and named by the path inside it
+ * (`schema (models.Institution.fields.name.required)`); everything else is
+ * walked as a value to its first differing leaf.
+ *
+ * Paths come back in projected-key order, keyed rows in key order, so the
+ * list is stable across runs, and every leaf is its own entry — a schema
+ * that differs in seven model fields is seven paths, so the caller's "+N
+ * more" cap counts them the way it counts operations. A value the walk
+ * cannot descend into (an array of a different length, a scalar against an
+ * object) is named at the level it stopped.
+ */
+export declare function describeProjectedDifferences(spec: Pick<ConfigDiffSpec, "childKeys" | "tomlFields">, local: Record<string, any>, remote: Record<string, any>): string[];
+/**
+ * The differing fields the definition says an UPDATE does not accept (#2731 B8).
+ *
+ * A local edit to such a field (rule-set `resourceType`, `writableOn:
+ * CREATE_ONLY`) would PATCH "successfully" while changing nothing server-side,
+ * and then re-report forever — the exact shape of non-convergence this issue
+ * exists to end. Extras keys are not definition fields and are never named.
+ */
+export declare function findImmutableFieldDiffs(table: ConfigTable, fieldDiffs: ReadonlyArray<{
+    field: string;
+}>): string[];
+/**
+ * Which side of a converted resource changed (#2731 B4).
+ *
+ * `baselineHash` is the manifest's `semanticHash`: the comparator's hash of the
+ * state both sides last agreed on. With it the answer is exact. Without it —
+ * a manifest written before this issue landed — the direction is INFERRED from
+ * the legacy signals rather than defaulting to "apply": a stored `contentHash`
+ * still matching the file's bytes proves the local side did not move, and a
+ * stored `modifiedAt` still matching the live one proves the server did not.
+ * When neither signal establishes a side (or the row was just adopted), the
+ * answer is `unknown-direction`, which callers treat as a conflict needing
+ * `config pull` or `--force`. An upgraded installation's first push must never
+ * silently overwrite server drift.
+ */
+export type PushChangeClass = "unchanged" | "local-edited" | "server-drifted" | "both-changed" | "unknown-direction";
+export declare function classifyPushChange(input: {
+    localHash: string;
+    remoteHash: string;
+    baselineHash?: string;
+    /**
+     * The server record has NOT been written since the last sync (#3317).
+     *
+     * Its own `modifiedAt` is what says so, and that is evidence no hash can
+     * contradict: a record nothing has written cannot have drifted, so the local
+     * file is the only side that can have moved. A baseline hash disagreeing
+     * with the current remote projection then says something about the BASELINE
+     * — recorded by a CLI whose projection of the same record differed — and not
+     * about the server. Left false by callers whose row timestamp does not cover
+     * everything the projection compares; `decidePushForConfig` owns that
+     * judgement.
+     */
+    serverUnchangedSinceSync?: boolean;
+    legacy?: {
+        localBytesMatchStoredContentHash?: boolean;
+        liveModifiedAtMatchesStored?: boolean;
+    };
+}): PushChangeClass;
+/** The rule-set name/id maps `config diff` resolves references through. */
+export interface ConfigDiffMaps {
+    ruleSetIdToName: Map<string, string>;
+    ruleSetNameToId: Map<string, string>;
+}
+/**
+ * How one configuration type is hashed for `config diff`: its definition, the
+ * definition-driven parse both sides go through, the pull serializer that turns
+ * a server entity into the file pull would have written, and the structural
+ * values hashed alongside the definition's fields.
+ */
+export interface ConfigDiffSpec {
+    label: string;
+    table: ConfigTable;
+    /**
+     * TOML doc -> the wire-shaped entity (the same parse `config push` uses).
+     *
+     * `extra` is the per-type context the projection needs and the document does
+     * not carry (#2880): a test case's id→name lookups, through which the two
+     * spellings of a reference meet. Mirrors `serialize`, which has taken one
+     * since the database types joined.
+     */
+    parse(doc: any, extra?: any): any;
+    /** Server entity -> the TOML `config pull` would write. */
+    serialize(record: any, maps: ConfigDiffMaps, extra?: any): string;
+    /** Structural values to hash beside the definition's fields. */
+    extras?(entity: any, doc: any, extra?: any): Record<string, any>;
+    /**
+     * Rewrite the parsed entity the way the SERVER rewrites an accepted one
+     * (#2880 DSO-003).
+     *
+     * Some handlers canonicalize on the way in — an integration's base URL gains
+     * a trailing slash, its methods are upper-cased — so the state the server
+     * returns is not the text the file holds. Comparing them raw makes an
+     * authored-but-noncanonical value `local-edited` on every run and push
+     * re-apply the same update forever; restamping the baseline cannot fix it,
+     * because the local side never moves. Applied to both sides (the remote
+     * reaches it through the same projection), so it must be idempotent.
+     */
+    canonicalize?(entity: any): void;
+    /**
+     * The projected keys THIS FILE does not manage (#2880 criterion 3).
+     *
+     * A handful of fields are present-only by design: push sends them when the
+     * file spells them and leaves the server's value alone when it does not,
+     * because "absent" here means "not authored here" rather than "cleared" — a
+     * webhook with no `[verification]` section at all, whose signing material a
+     * push must not revoke as a side effect. Comparing such a field against a
+     * server that holds one reports a difference push will never act on: the
+     * update omits the key, the server keeps its value, and the row comes back
+     * Modified on every run. So the local side inherits the remote value for
+     * exactly the keys the file leaves unmanaged, and the two commands agree
+     * that there is nothing to do.
+     */
+    unmanaged?(doc: any): string[];
+    /**
+     * The projected extras that are KEYED child collections, by the key each
+     * row carries (#3267) — a database type's `operations` by `name`. The
+     * comparison already sorts these by key (`byKey`); this is what lets a
+     * difference in one be NAMED as the row and the sub-field it is in, rather
+     * than as the whole collection.
+     */
+    childKeys?: Record<string, string>;
+    /**
+     * The projected extras that are TOML documents held as strings (#3267) —
+     * a database type's `[models.*]` `schema`. Named as the path inside the
+     * document that differs, when both sides parse.
+     */
+    tomlFields?: string[];
+    /** Whether the entity carries a rule-set reference needing resolution. */
+    ruleSetRef?: boolean;
+    /** How the type names itself in the rule-set resolution message. */
+    describe(entity: any): string;
+}
+/**
+ * Every type the shared comparator serves — the types `config diff` compares
+ * field-for-field, and that `config push` gates on the same projection
+ * (#2731 B1/B2; webhooks joined the comparator in #2757 and their push joined
+ * the same gate in #2880, so no registered type answers "changed?" from the
+ * file's bytes any more).
+ *
+ * Published so the round-trip acceptance bar (#2731 B9) can require a fixture
+ * per type instead of listing them a second time by hand: converting a type is
+ * then one edit here, and the bar says so if its round trip is untested.
+ */
+export declare function configDiffSpecLabels(): string[];
+/** The diff spec for a configuration type. Throws rather than skipping a check. */
+export declare function configDiffSpec(label: string): ConfigDiffSpec;
+/**
+ * Project a LOCAL config file onto the record both `config diff` and `config push`
+ * compare (#2644 field set, #2731 shared gate). The hash is a thin wrapper, so
+ * a push that needs to SAY what differs and a diff that only needs to know THAT
+ * something differs read the same projection.
+ */
+export declare function projectLocalConfig(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps, extra?: any): Record<string, any>;
+/** The same projection for a SERVER entity — see `hashRemoteConfigForDiff`. */
+export declare function projectRemoteConfig(spec: ConfigDiffSpec, record: any, maps: ConfigDiffMaps, extra?: any): Record<string, any>;
+/**
+ * BOTH sides of one comparison, with the file's unmanaged keys reconciled
+ * (#2880) — the one place `spec.unmanaged` is honored, so `config diff` and
+ * `config push` cannot read the same file differently.
+ */
+export declare function projectConfigPair(spec: ConfigDiffSpec, localParsed: any, remoteRecord: any, maps: ConfigDiffMaps, extra?: any, localExtra?: any): {
+    local: Record<string, any>;
+    remote: Record<string, any>;
+};
+/**
+ * One `config diff` row's content verdict for a registered type (#2880).
+ *
+ * The three outcomes the per-type blocks were each spelling out by hand:
+ * equal (`exists`), different (`modified`, framed as a preview of
+ * `config pull`), and "could not tell" — a missing record or a comparison that
+ * threw, which degrades THIS row and never the whole diff. Written once so a
+ * type joining the comparator cannot accidentally report a fourth thing.
+ *
+ * The two `extra` arguments are the same split `decidePushForConfig` makes:
+ * `extra` carries what only the SERVER side has (a database type's operation
+ * rows), while `localExtra` is context BOTH sides read a value through — a test
+ * case's id→name lookups. Giving the local side nothing was a silent
+ * mistranslation: a sidecar pinned by a resolvable `configId` projected the id
+ * while the server's projection resolved it to the name, so an untouched file
+ * reported Modified in diff and drifted in push.
+ */
+export declare function compareLocalToRemote(spec: ConfigDiffSpec, localParsed: any, remoteRecord: any, maps?: ConfigDiffMaps, extra?: any, localExtra?: any): {
+    status: string;
+    hint?: string;
+};
+/** Hash a LOCAL config file's definition-projected field set (#2644). */
+export declare function hashLocalConfigForDiff(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps, extra?: any): string;
+/**
+ * Hash a SERVER entity the same way, by serializing it into the file `sync
+ * pull` would write and hashing that — so the two sides are normalized
+ * identically by construction, and a legacy encoding on disk (a JSON-string
+ * operation, an id-based rule-set reference) is not a false `Modified`.
+ *
+ * `extra` carries the sibling rows a type's file also holds: a database type's
+ * operations and subscriptions, which the list response does not include.
+ */
+export declare function hashRemoteConfigForDiff(spec: ConfigDiffSpec, record: any, maps: ConfigDiffMaps, extra?: any): string;
+/** One field's disagreement between the local file and the live server entity. */
+export interface PushFieldDiff {
+    field: string;
+    local: any;
+    server: any;
+}
+/**
+ * What `config push` should do with one converted-type file, and why.
+ *
+ * `create`/`skip`/`update` are the applying outcomes; `drift`, `conflict`,
+ * `immutable` and `live-unavailable` are the four ways push declines to apply
+ * and says so.
+ */
+export type PushGateOutcome = {
+    action: "live-unavailable";
+} | {
+    action: "create";
+} | {
+    action: "skip";
+    localHash: string;
+    remoteHash: string;
+} | {
+    action: "update";
+    direction: "local-edited" | "forced" | "adopt-untracked";
+    localHash: string;
+    remoteHash?: string;
+    expectedModifiedAt?: string;
+    fields: PushFieldDiff[];
+} | {
+    action: "drift";
+    localHash: string;
+    remoteHash: string;
+    fields: PushFieldDiff[];
+} | {
+    action: "conflict";
+    direction: "both-changed" | "unknown-direction";
+    localHash: string;
+    remoteHash: string;
+    fields: PushFieldDiff[];
+    serverModifiedAt?: string;
+} | {
+    action: "immutable";
+    localHash: string;
+    remoteHash: string;
+    fields: PushFieldDiff[];
+    immutableFields: string[];
+};
+/** The manifest entry a converted type's gate reads (all fields optional). */
+export interface PushBaselineEntry {
+    modifiedAt?: string;
+    contentHash?: string;
+    semanticHash?: string;
+    /**
+     * The version the manifest last saw active, for a versioned type (#3317).
+     * Read only beside `serverModifiedAtCoversProjection`: a recorded pointer
+     * that is not the live one denies the timestamp's claim that the server
+     * stood still.
+     */
+    activeConfigId?: string;
+}
+/**
+ * `config push`'s change decision for one configuration file (#2731 B1/B3/B4/B8).
+ *
+ * This replaces `shouldPushFile` for the converted types. The differences that
+ * matter, in order:
+ *
+ *  - the comparison is `config diff`'s — the definition-projected field set on
+ *    both sides — so "skip as unchanged" and "Synced" cannot disagree, and a
+ *    comment-only or formatting-only edit is not a change;
+ *  - the right-hand side is the LIVE entity, not the manifest, so out-of-band
+ *    server drift is visible instead of being overwritten;
+ *  - the manifest becomes a baseline that answers WHICH side moved, so a
+ *    difference is attributed rather than assumed to be a local edit.
+ *
+ * Declining is a first-class outcome here. `drift`, `conflict` and `immutable`
+ * each carry the field diff their report prints, and nothing is applied.
+ *
+ * `adoptsUntrackedByKey` is the one exception a type can ask for, and it is
+ * documented on the field: an object the manifest has never recorded is the
+ * adopt its create path would have performed via a 409 (#1006/#2909), not a
+ * difference to refuse.
+ */
+/**
+ * What the DEGRADED gate does with one file — the path a converted type takes
+ * when its live read failed (#2880 criterion 7).
+ *
+ * Falling back to the manifest's byte hash is right while there is one to fall
+ * back to. Without one, `shouldPushFile(file, undefined)` answers "push it",
+ * so a fresh checkout or a lost manifest turned "we could not read the server"
+ * into "overwrite the server", unconditionally and silently — the one shape of
+ * blind write this issue's direction attribution exists to prevent. So a
+ * baseline-less update DECLINES: the resource is not written and the operator
+ * is told which of `config pull` / `--force` clears it.
+ *
+ * A file the manifest does not name is declined for the same reason, and this
+ * is the part that is easy to get wrong: an unrecorded file looks like a
+ * create, but only LIVE STATE can say the server has nothing under that key —
+ * and live state is exactly what this path could not read. The create that
+ * follows is adopted by key on the 409 and re-issued as an update, so
+ * "there is no recorded entity to overwrite" would have been a blind overwrite
+ * of a resource this run never compared. Every section's degraded gate is
+ * reached only when the live read failed, so there is no case here where
+ * absence was proved.
+ */
+export type DegradedPushDecision = {
+    action: "skip";
+} | {
+    action: "send";
+} | {
+    action: "decline";
+    reason: "no-baseline";
+};
+export declare function decideDegradedPush(input: {
+    force?: boolean;
+    storedContentHash?: string;
+    currentFileHash?: string;
+}): DegradedPushDecision;
+export declare function decidePushForConfig(input: {
+    spec: ConfigDiffSpec;
+    maps: ConfigDiffMaps;
+    localParsed: any;
+    /** The live server entity, or null/undefined when the server has none. */
+    live?: {
+        record: any;
+        extra?: any;
+        modifiedAt?: string;
+    } | null;
+    /** The manifest entry, absent when this file has never been synced. */
+    entry?: PushBaselineEntry | null;
+    /** Byte hash of the local file — the legacy direction signal. */
+    localFileHash?: string;
+    /**
+     * Per-type context for the LOCAL projection (#2880) — a test case's id→name
+     * lookups. Separate from `live.extra`, which carries remote-only rows (a
+     * database type's operations) the local parse must never see.
+     */
+    localExtra?: any;
+    force?: boolean;
+    /**
+     * Whether the live record's `modifiedAt` covers EVERYTHING this type's
+     * projection compares (#3317).
+     *
+     * Opt-in, because it is a claim about the data model rather than about this
+     * push. A server function's header row carries its fields and the
+     * `activeConfigId` pointer, and a version is immutable, so any change to
+     * what the comparison reads moves that one timestamp — an equal timestamp
+     * therefore PROVES the server stood still, and a baseline hash that
+     * disagrees is stale rather than evidence of drift (the reporter's conflict,
+     * printed over two identical timestamps).
+     *
+     * A database type's is the counter-example and the reason this is not the
+     * default: its operations and subscriptions are rows of their own, so an
+     * out-of-band edit to one changes the projection while the type's own
+     * `modifiedAt` stands still. Claiming coverage there would turn a real
+     * server change into a silent overwrite.
+     *
+     * The timestamp is trusted only alongside the version pointer: when the
+     * manifest recorded an `activeConfigId`, the live record must still point at
+     * it. The baseline is written from a header refetched AFTER the push, and a
+     * concurrent activation landing in that window leaves the manifest carrying
+     * the other operator's timestamp beside the version this push activated —
+     * two timestamps that agree about a server that moved to a version the local
+     * file never saw. The pointer is what moved, so it is what settles it.
+     */
+    serverModifiedAtCoversProjection?: boolean;
+    /**
+     * Whether this type's push path ADOPTS an existing object by key (#2909).
+     *
+     * Opt-in, and it changes exactly one outcome: a live entity the manifest has
+     * no row for at all. Prompts (#1006), and the other types whose create path
+     * recovers a 409 through `adoptByKeyOnCreate409`, treat that as the adopt it
+     * has always been — an object pushed from another slot, created out of band,
+     * or orphaned by a push that aborted before recording it, which the local
+     * file is the declared intent for. Without this the gate reads that same
+     * shape as a difference it cannot attribute, refuses, and the create the
+     * adopt guard recovers from is never even sent (the #2909 regression).
+     *
+     * #2934 — the criterion is the CREATE PATH, not which issue converted the
+     * type: cron triggers, webhooks, integrations, blob buckets and the
+     * group/collection type configs all recover their create's key conflict the
+     * same way, so they pass it too. Passing it at one call site left the other
+     * five reporting a conflict for the adopt their own create documents.
+     *
+     * Rule sets keep it OFF, and that is a decision rather than an omission:
+     * #2731 made a never-synced rule set differing from a same-named live one the
+     * conflict the operator resolves with `config pull` or `--force`, its own
+     * tests pin that, and `resourceType` — the field a wrong adopt would silently
+     * strand — is one an update cannot repair.
+     */
+    adoptsUntrackedByKey?: boolean;
+}): PushGateOutcome;
+/**
+ * The identity a file may leave to its name, written back into the parsed
+ * document before the shared gate reads it (#2731 B1).
+ *
+ * Four types let the file name stand in for the identity field inside the file
+ * (`orders.toml` for a database type, `group.profile.toml` for a metadata
+ * category, and so on). The gate re-parses the DOCUMENT, so the derived value
+ * has to be in it: an omitted `databaseType` otherwise projects as absent
+ * against a server record that carries it, and — since these identities are
+ * declared create-only — the file reports an immutable-field difference on
+ * every push while `config diff`, which injects the same value before it hashes
+ * (~sync.ts:11744), reads it Synced.
+ *
+ * A value the file states always wins; this only fills the gap the file name
+ * was already filling for the rest of push.
+ */
+export declare function withDerivedIdentity(doc: any, tomlPath: string, identity: Record<string, string | undefined>): any;
+/**
+ * Which server-side entity this file's update targets (#2731 B3).
+ *
+ * The manifest is a cache, so it can be wrong in both directions: it can name
+ * an entity the server no longer has (pointing an update at a 404 where the
+ * operator asked for a re-create, #1659), and it can be silent about one that
+ * is there (sending a create that comes back 409 to be adopted). When live
+ * state was read, live state answers; the manifest is the fallback for the
+ * degraded path only, where it is also what the byte-hash gate has always used.
+ */
+export declare function resolveExistingId(input: {
+    liveOk: boolean;
+    liveId?: string;
+    manifestId?: string;
+}): string | undefined;
+/**
+ * Which CHILD rows a database type's push reconciles against (#2731 B3).
+ *
+ * `resolveExistingId` answers this for a whole entity; a database type's
+ * operations and subscriptions are rows with the same question and the same
+ * two possible answers. The manifest can name an operation the server no
+ * longer has (the update PUTs a row that is gone) and be silent about one it
+ * does have (the create POSTs a duplicate key) — both abort the push with a
+ * server error, which is exactly the recovery `--force` is supposed to
+ * perform.
+ *
+ * When the reconcile read the rows, they ARE the baseline: existence, the
+ * timestamp each update guards with, and — as the complement of the file's own
+ * list — which rows this push deletes. `undefined` means the read did not
+ * happen (the degraded path, or a type live state says is absent), and the
+ * manifest stays what it has always been.
+ */
+export declare function liveChildBaseline(live: Map<string, any> | undefined, manifestChildren?: Record<string, {
+    modifiedAt: string;
+}>): Record<string, {
+    modifiedAt: string;
+}> | undefined;
+/**
+ * The app's live rule sets, indexed the three ways push reads them (#2731 B3).
+ *
+ * One fetch answers three questions, and leaving any of them to the manifest
+ * reintroduces the split this issue is about:
+ *
+ *  - `byFileKey` — the rule set this file's own gate compares against;
+ *  - `idToName` — how a REFERENCING type's server record is serialized back
+ *    into the file pull would write, so a `ruleSetId` is compared as the name
+ *    the file spells;
+ *  - `nameToId` — how a referencing file's `ruleSetName` resolves to something
+ *    push can send. Seeding it from live is what lets `--only
+ *    group-type-config/team` resolve a rule set that exists on the server but
+ *    was never recorded locally, instead of failing as an unresolved
+ *    reference.
+ */
+export declare function indexLiveRuleSets(ruleSets: any[]): {
+    byFileKey: Map<string, any>;
+    idToName: Map<string, string>;
+    nameToId: Map<string, string>;
+};
+/**
+ * The baseline a successful apply stamps, from the SERVER's own record
+ * (#2731 B4).
+ *
+ * The baseline is compared against both sides on the next run, so it has to be
+ * in the server's spelling: handlers normalize what they store (rule-set
+ * create/update trims `name`), and a baseline taken from the local file would
+ * make the very next legitimate local edit read as "both sides changed" — a
+ * conflict the operator can only clear with `--force`.
+ *
+ * `undefined` — no baseline — is the honest answer when the response carries
+ * nothing projectable and no refetch is available. The next run then falls back
+ * to the legacy `contentHash`/`modifiedAt` signals, which is what an upgraded
+ * installation runs on anyway; an invented baseline would instead assert
+ * agreement that was never observed.
+ */
+export declare function remoteSemanticBaseline(input: {
+    spec: ConfigDiffSpec;
+    maps: ConfigDiffMaps;
+    /** What the write returned. Usable only if it is the stored entity. */
+    returned?: any;
+    extra?: any;
+    /**
+     * How this type recognizes its own stored record. The default — it carries a
+     * `modifiedAt` — is what separates the stored entity from a bare
+     * `{ success: true }` acknowledgement, whose empty projection would otherwise
+     * be stamped as the state both sides agreed on. Types whose comparator reads
+     * an envelope (an email template's `{ emailType, hasOverride, override }`)
+     * say where their timestamp actually lives.
+     */
+    isStoredRecord?: (returned: any) => boolean;
+}): string | undefined;
+/** What `config push` decides for one transform (#2731 B7). */
+export type ScriptPushOutcome = {
+    action: "skip";
+    localHash: string;
+    remoteHash: string;
+} | {
+    action: "update";
+    direction: "local-edited" | "forced" | "no-active-body";
+    localHash: string;
+} | {
+    action: "drift";
+    localHash: string;
+    remoteHash: string;
+} | {
+    action: "conflict";
+    direction: "both-changed" | "unknown-direction";
+    localHash: string;
+    remoteHash: string;
+};
+/**
+ * `config push`'s change decision for one transform (#2731 B7).
+ *
+ * A transform's comparator IS its bytes: the body push sends is the body diff
+ * compares, so there is no projection to reconcile — only the same three
+ * questions every converted type asks. Local versus the LIVE active body, with
+ * the manifest demoted to the baseline that says which side moved.
+ *
+ * A script the manifest has never seen reaches here too (adopted by name from
+ * the live index). It has no baseline and no legacy signal, so an unequal body
+ * classifies as `unknown-direction` — a conflict to report rather than a server
+ * body to overwrite on a guess.
+ */
+export declare function decidePushForScript(input: {
+    localBody: string;
+    /** Byte hash of the local file — the legacy direction signal. */
+    localFileHash?: string;
+    /**
+     * The live active body, and the script row's timestamp beside it — the other
+     * legacy direction signal (#2731 B4). Activating a config updates the script
+     * row, so a timestamp still equal to the manifest's proves the server body
+     * has not moved: an upgraded installation's first push applies a genuine
+     * local edit instead of reporting a direction it could have known.
+     *
+     * `null` is an ANSWER, not a failed read: the script row exists and nothing
+     * is active on it. See below.
+     */
+    live: {
+        body: string;
+        modifiedAt?: string;
+    } | null;
+    entry?: {
+        contentHash?: string;
+        semanticHash?: string;
+        modifiedAt?: string;
+    } | null;
+    force?: boolean;
+}): ScriptPushOutcome;
+/**
+ * One side of a field diff, rendered for a conflict report (#2731 B5).
+ *
+ * A rule set's `rules` tree or a template's HTML body can be kilobytes; the
+ * useful statement about them is that they differ and how big they are, not
+ * their contents scrolling past.
+ */
+export declare function summarizeFieldValue(value: any): string;
+/**
+ * The push summary line (#2731 criterion 10).
+ *
+ * The two established spellings are preserved exactly; drift — resources push
+ * deliberately did NOT apply — is appended only when there is some, so an
+ * operator never has to infer it from a change count that stayed put.
+ */
+export declare function formatPushSummary(input: {
+    pushed: number;
+    skipped: number;
+    drifted: number;
+}): string;
+/**
+ * The summary line a FAILED push ends on (#2731 B5).
+ *
+ * "Re-run `config push` to converge" is true of one failure only: a database
+ * type the validate-first gate blocked (#813), where the next push carries the
+ * corrected state. A conflict is the opposite — the run declined to apply
+ * precisely because both sides moved, so repeating it reports the same
+ * conflict forever (the alpha.62 field report ends in that loop). Apply
+ * failures, which used to be absent from this line entirely, need the file
+ * fixed rather than either.
+ */
+export declare function formatPushFailureSummary(input: {
+    pushed: number;
+    blockedDatabaseTypes: number;
+    conflicts: number;
+    applyFailures: number;
+}): string;
+/**
+ * How many of a failed push's planned changes actually applied.
+ *
+ * `changes` records what push SET OUT to do, so the honest success count is
+ * that list minus everything the run then refused or the server rejected:
+ *
+ *  - a validate-first blocked database type (issue #813) keeps its labels for
+ *    visibility, but none of them landed — including its operations;
+ *  - a conflict on a change that was already counted (a late 409, recorded
+ *    before the write) cancels that change.
+ *
+ * A conflict the GATE declined (`planned: false`) is deliberately NOT
+ * subtracted: it never added a `changes` entry, so charging the count for it
+ * reports a push that did apply something as having applied nothing.
+ */
+export declare function countAppliedChanges(input: {
+    changes: Array<{
+        type: string;
+        key: string;
+    }>;
+    conflicts: Array<{
+        planned?: boolean;
+    }>;
+    blockedDatabaseTypes: string[];
+    schemaBlockedCount: number;
+}): number;
+/**
+ * The semantic baseline to stamp for a file both sides now agree on (#2731 B4).
+ *
+ * `contentHash` records what the local BYTES were; this records what the
+ * comparator SAW, which is what makes "who changed?" answerable: after a pull
+ * or a successful push, local and server agree, so one hash is the baseline for
+ * both. Best-effort by design — an unreadable or unparseable file yields
+ * `undefined`, and a missing baseline degrades to the legacy inference rather
+ * than taking the command down.
+ */
+export declare function configSemanticHash(label: string, filePath: string, maps: ConfigDiffMaps): string | undefined;
+/**
+ * The sync state `config push` writes into (#2731 B6, closing #2374).
+ *
+ * `loadSyncState` answers `null` for an absent sync-state baseline, and
+ * every per-entity state write in the push loops is guarded by `if (syncState)`
+ * — so a first push created every resource and recorded none of them. The next
+ * push then re-entered the create path for everything and depended on 409
+ * adoption to recover, which for database types hard-failed on operations.
+ *
+ * Building the state up front (the same shape the cross-app-push branch
+ * already builds) makes those guards hold from the first run, so the
+ * end-of-push and catch-path saves persist what the push actually did.
+ */
+export declare function ensurePushSyncState(existing: SyncState | null, appId: string, serverUrl: string): SyncState;
+export declare function parseTomlFile(filePath: string): any;
+/**
+ * Paginate through a list endpoint, collecting all items.
+ */
+export declare function fetchAll<T>(listFn: (params: {
+    limit: number;
+    cursor?: string;
+}) => Promise<{
+    items: T[];
+    nextCursor?: string | null;
+}>, pageSize?: number, maxPages?: number): Promise<T[]>;
+/**
+ * Issue #976 / #1006: shared 409 → adopt-by-key recovery for `config push`
+ * create paths. When a CREATE hits a per-app unique-key constraint, the resource
+ * is already on the server but missing from local sync state: orphaned by a
+ * prior push that aborted before recording it, a mid-apply crash, or an
+ * out-of-band create with the same key. Rather than hard-fail forever, this
+ * helper looks the resource up by its unique key and hands the matched item
+ * back so the caller can re-issue the create as an UPDATE and converge.
+ *
+ * The conflict surfaces inconsistently across create routes, so detection is
+ * deliberately broad (see `isConflict` below):
+ *   - a 409 status (webhooks, cron triggers, the standard case);
+ *   - an "already exists" message — some routes surface the 409 as HTTP 400,
+ *     e.g. workflows;
+ *   - a "must be unique" message — routes with no explicit conflict catch let
+ *     dynamo-bao's per-app unique-constraint error propagate verbatim (e.g. rule
+ *     sets, whose create route has no 409 translation). This matches the
+ *     server's own admin-api convention (`src/admin-api.ts`), which treats
+ *     "must be unique" as a duplicate-key conflict.
+ * Any other error is NOT a conflict and re-throws unchanged (see below).
+ *
+ * Safety (load-bearing): exact-key match only. The `lookup` is app-scoped, so a
+ * key match is also an ownership match — an unrelated resource is never
+ * overwritten. The three non-adopt outcomes each surface a clear error and do
+ * NOT touch the server:
+ *   - a non-409 create error is re-wrapped via `wrapEntityError` and re-thrown
+ *     (no lookup is attempted);
+ *   - a lookup failure throws a clear "already exists but could not be adopted
+ *     (lookup failed: …)";
+ *   - a 409 with no matching key re-throws the ORIGINAL create error rather
+ *     than silently proceeding.
+ *
+ * Pagination is the caller's concern: `lookup` must return the COMPLETE
+ * candidate set. For cursor-based lists (webhooks, integrations, prompts,
+ * workflows) wrap the list call in `fetchAll`; the cron-triggers route already
+ * drains every page server-side (#1668) so its flat `{ items }` is complete.
+ * The UPDATE re-issue and sync-state stamping stay with the caller because they
+ * differ per entity.
+ *
+ * @returns the matched existing item (guaranteed non-null on return).
+ */
+export declare function adoptByKeyOnCreate409<T>(opts: {
+    err: unknown;
+    kind: string;
+    key: string;
+    lookup: () => Promise<T[]>;
+    matchKey: (item: T) => boolean;
+}): Promise<T>;
+/**
+ * Resolve a key-based rule set name reference to an ID.
+ * Throws if the name cannot be resolved and throwOnMissing is true.
+ */
+export declare function resolveRuleSetReference(entityConfig: any, ruleSetNameToId: Map<string, string>, entityLabel: string, options?: {
+    throwOnMissing?: boolean;
+    hint?: string;
+}): void;
+/**
+ * Rule-set name→ID for the rule sets a scoped push is NOT applying
+ * (issue #2645, review follow-up).
+ *
+ * Database, group and collection type configs name their rule set by NAME and
+ * resolve it through the map the rule-set apply loop fills in as it goes. Under
+ * `--only` that loop iterates the selected files alone, so `config push --only
+ * database-type-config/orders` threw "Rule set … not found" for a type whose rule set
+ * the operator had no reason to select — the single-object apply path refusing
+ * an ordinary object, which is the opposite of what `--only` is for.
+ *
+ * A rule set the sync state already carries an id for is resolvable without
+ * being applied, which is exactly what a reference needs. One that has never
+ * been pushed still cannot resolve: there is no id to point at, and inventing
+ * one would silently create the reference against nothing. That case keeps
+ * throwing, with the hint to widen the selection.
+ *
+ * Pure, so the seeding is unit-testable without a server or a filesystem.
+ */
+export declare function unselectedRuleSetIds(params: {
+    /** Every rule-set file in the slot. */
+    files: string[];
+    /** The subset this push is applying — seeded entries never shadow these. */
+    selected: string[];
+    /** The id sync state holds for a rule-set file's key, if it has one. */
+    idForFileKey: (fileKey: string) => string | undefined;
+    /** The `ruleSet.name` a file declares — the name references use. */
+    nameForFile: (file: string) => string | undefined;
+}): Map<string, string>;
+export declare function getTestsDir(configDir: string, blockType: string, blockKey: string): string;
+export interface TestCaseLookupMaps {
+    configIdToName: Map<string, string>;
+    promptIdToKey: Map<string, string>;
+}
+export declare function serializeTestCase(testCase: any, lookupMaps?: TestCaseLookupMaps, options?: {
+    /** The sidecar path the warning names, e.g. `prompts/greet.tests/a.toml`. */
+    file?: string;
+    logger?: (message: string) => void;
+}): string;
+export declare function parseTestCaseToml(tomlData: any): any;
+/**
+ * Pull server-side `Script` rows into `transforms/*.rhai` and record
+ * each in the returned sync-state map. Issue #892 slice 7 + codex
+ * follow-up on PR #893; body materialization fixed in issue #1196.
+ * Exported so the unit test can drive it against stubbed
+ * `client.listScripts` / `client.getScript`.
+ *
+ * Two-call contract: `listScripts` returns the `Script` HEADER only
+ * (no `body` — see `serializeScript` in `src/admin-api.ts`). The Rhai
+ * source lives on a versioned `ScriptConfig`. So for each listed
+ * script we fetch the full record with `getScript`, which returns the
+ * header plus serialized `configs` (each carrying its `body`), and
+ * write the ACTIVE config's body. Reading the body off the list shape
+ * (the old behavior) always produced 0-byte files.
+ *
+ * Idempotency: every call writes the active-config body the server
+ * returned, so re-running `config pull` on an unchanged server overwrites
+ * with the same bytes and produces the same `contentHash`. The result
+ * map always reflects the current server state for the writes performed.
+ *
+ * `count` is the number of files actually written, not the number of
+ * scripts listed: scripts with no active config and scripts whose
+ * config fetch fails are skipped (we never clobber a `.rhai` with an
+ * empty file).
+ *
+ * Older-server graceful path: if `listScripts` rejects (e.g. older
+ * server without the route), the caller catches and treats it as
+ * "no scripts to pull", leaving the directory empty. A per-script
+ * `getScript` failure is caught and that one script is skipped without
+ * aborting the rest of the pull.
+ */
+export declare function pullScripts(client: ApiClient, appId: string, configDir: string, logger?: (msg: string) => void, 
+/**
+ * `config pull --only` (issue #2645): which transform names this pull may
+ * write. Defaults to every one the server lists.
+ */
+selects?: (name: string) => boolean): Promise<{
+    scriptEntities: Record<string, {
+        id: string;
+        modifiedAt: string;
+        contentHash?: string;
+        semanticHash?: string;
+    }>;
+    count: number;
+    /**
+     * Which scripts the server listed, for the #1659 prune pass. `ok: false` when
+     * the listing failed (an older server without the route, or a transient
+     * error) or when any per-script fetch failed — in either case this pull's
+     * picture of the type is incomplete and must not drive deletions. Scripts
+     * skipped for having no active config are still *present*, so their keys stay
+     * in the set and their local `.rhai` survives.
+     */
+    presence: PresenceOutcome;
+    /**
+     * Whether the script LISTING succeeded. Distinct from `presence`: a failed
+     * per-script fetch blocks pruning but still leaves the other scripts written,
+     * so their fresh state entries must be kept. Only a failed listing means
+     * nothing was written and the prior state slot should be preserved whole.
+     */
+    listOk: boolean;
+    /** Names the server listed, empty when the listing failed. */
+    serverKeys: string[];
+}>;
+/**
+ * The manifest row `config push` records for a function it just pushed
+ * (#3317), and whether the server had already moved past that push.
+ *
+ * The header is refetched AFTER the version push, so the row's `modifiedAt`
+ * is the live timestamp — but the version pointer and the envelope are the
+ * push's own: the manifest names what THIS run activated, not whatever the
+ * refetch happened to find. A concurrent activation landing between the push
+ * and the refetch is exactly the case those two must not be conflated in:
+ * recording the refetched pointer would make the other operator's version the
+ * baseline the local file is then read as a plain edit of, and the next push
+ * would roll it back without `--force`. Recording the pushed pointer beside
+ * the live timestamp is what `decidePushForConfig` reads as "the pointer
+ * moved" — a refusal, until the operator pulls or forces.
+ *
+ * `movedTo` names the version the refetched header points at when it is not
+ * the pushed one, so the caller can say so at the moment it is known rather
+ * than leaving it for the next push to report.
+ */
+export declare function pushedFunctionBaseline(input: {
+    functionId: string;
+    /** The header refetched after the push, or the pre-push listing row. */
+    refreshed: any;
+    existingModifiedAt?: string;
+    contentHash: string;
+    /** The version the push activated (created, or the matched no-op). */
+    pushedVersion: any;
+    envelopeHash: string;
+    sources: string[];
+    spec: ConfigDiffSpec;
+    maps: ConfigDiffMaps;
+}): {
+    entity: {
+        id: string;
+        modifiedAt: string;
+        contentHash: string;
+        semanticHash?: string;
+        envelopeHash: string;
+        activeConfigId?: string;
+        sources: string[];
+    };
+    movedTo: string | null;
+};
+/**
+ * Pull server-side `ServerFunction` rows into `functions/` (#3179).
+ *
+ * Two things make this different from every other type's pull:
+ *
+ *   1. **A function is more than its file.** The active config VERSION holds an
+ *      envelope with the authored TOML bytes and every source file, so the pull
+ *      writes `functions/<key>.toml` plus the TypeScript beside it, and records
+ *      the source paths so prune can remove the code with the function.
+ *   2. **Bytes, not a re-serialization.** The stored TOML is written verbatim,
+ *      so comments, key order and line endings survive the round trip (F-009).
+ *      A function that has never had code pushed has no stored bytes; that one
+ *      gets a canonical serialization of its header, which is still a pushable
+ *      file.
+ *
+ * A stored source path is never trusted: `planFunctionPull` refuses one that
+ * normalizes outside the tree, and the refusals are reported rather than
+ * swallowed.
+ */
+export declare function pullFunctions(client: ApiClient, appId: string, configDir: string, logger?: (msg: string) => void, selects?: (key: string) => boolean): Promise<{
+    functionEntities: Record<string, {
+        id: string;
+        modifiedAt: string;
+        contentHash?: string;
+        semanticHash?: string;
+        envelopeHash?: string;
+        activeConfigId?: string;
+        sources?: string[];
+    }>;
+    count: number;
+    presence: PresenceOutcome;
+    listOk: boolean;
+    serverKeys: string[];
+    /**
+     * Everything the server listed, archived rows included. Pull exports no file
+     * for a tombstone, so without the row here the archived function would be
+     * stranded: no file to delete and no managed key to prune, and its key would
+     * go on blocking the app's whole namespace with nothing able to reclaim it.
+     * The caller folds these into the state through `archivedTombstoneEntries`.
+     */
+    items: any[];
+}>;
+/** The outcome of one block's test-case pull (#2769). */
+export type TestCasePullOutcome = 
+/** The listing succeeded; `count` cases were written and stale files removed. */
+{
+    ok: true;
+    count: number;
+}
+/** The listing failed: nothing was written, and the caller preserves state. */
+ | {
+    ok: false;
+};
+/**
+ * Every test case a block has, draining the cursor (#2769).
+ *
+ * The endpoint returns 50 per page. Reconciling the sidecar against page one
+ * alone would delete every file past it and drop the ids that keep push from
+ * duplicating them, so the whole set is collected BEFORE anything is written.
+ */
+export declare function listAllTestCases(client: ApiClient, appId: string, blockType: TestBlockType, blockId: string): Promise<{
+    ok: true;
+    items: any[];
+} | {
+    ok: false;
+}>;
+/**
+ * Copy a block's prior `entities.testCases` records into the pull's fresh map
+ * (#2769), returning how many were carried.
+ *
+ * `config pull` rebuilds the test-case slot from scratch, so a block whose
+ * listing failed would silently lose its ids — and the next push would create a
+ * second copy of every case it could no longer recognize. A failed fetch means
+ * "unknown", so the prior picture stands.
+ */
+export declare function carryForwardTestCaseEntities(params: {
+    prior: Record<string, any> | undefined;
+    target: Record<string, any>;
+    blockType: string;
+    blockKey: string;
+}): number;
+/**
+ * Write one block's test cases into its `<key>.tests/` sidecar and record them
+ * in sync state. Exported so the unit tests can drive it against a stubbed
+ * client on a temp directory.
+ */
+export declare function pullTestCasesForBlock(params: {
+    client: ApiClient;
+    appId: string;
+    blockType: TestBlockType;
+    blockId: string;
+    blockKey: string;
+    configDir: string;
+    testCaseEntities: Record<string, any>;
+    /** Last sync's records, for the fallbacks a partial failure falls back to. */
+    priorTestCaseEntities?: Record<string, any>;
+    lookupMaps?: TestCaseLookupMaps;
+    logger?: (message: string) => void;
+}): Promise<TestCasePullOutcome>;
+/**
+ * One pull leg: every block of a type the pull selected (#2769).
+ *
+ * The selection is the caller's — a leg is handed the blocks `--only` left in,
+ * so a scoped pull never reads, writes or removes a sidecar it was not asked
+ * about. A block whose listing failed keeps its prior state entries and is
+ * reported as skipped rather than silently reconciled to empty.
+ */
+export declare function pullTestCasesForBlocks(params: {
+    client: ApiClient;
+    appId: string;
+    configDir: string;
+    blockType: TestBlockType;
+    blocks: Array<{
+        id: string;
+        key: string;
+    }>;
+    testCaseEntities: Record<string, any>;
+    priorTestCaseEntities?: Record<string, any>;
+    lookupMaps?: TestCaseLookupMaps;
+    logger?: (message: string) => void;
+}): Promise<{
+    count: number;
+    skippedBlocks: string[];
+}>;
+interface PushResolutionMaps {
+    promptKeyToId: Map<string, string>;
+    promptConfigNameToId: Map<string, string>;
+    workflowConfigNameToId: Map<string, string>;
+    scriptConfigNameToId?: Map<string, string>;
+    integrationConfigNameToId?: Map<string, string>;
+    /**
+     * Fill one block's config name→id entries from the server on demand (#2769),
+     * resolving `false` when the block has no id yet.
+     *
+     * A test case may pin a config on a block this push did not select, or run
+     * under `--dry-run`, where nothing was written to learn the ids from. The
+     * lookup is READ-ONLY and independent of both, so a name that a real push
+     * resolves never reads as broken.
+     */
+    loadBlockConfigs?: (blockType: TestBlockType, blockKey: string) => Promise<boolean>;
+    /** Whether a block is authored locally but not on the server yet. */
+    isPlannedBlock?: (blockType: TestBlockType, blockKey: string) => boolean;
+}
+/** A failure row the push reports and exits nonzero on (`applyFailures`). */
+type ApplyFailure = {
+    type: string;
+    key: string;
+    message: string;
+};
+/** The attachment bookkeeping a test case's sync-state record carries. */
+type RecordedAttachments = {
+    attachments?: Record<string, string>;
+    attachmentFilenames?: string[];
+};
+/**
+ * Which attachments a push must upload, and which the SERVER holds that the
+ * sidecar no longer does (#2769).
+ *
+ * Comparison is by content hash: the pre-#2769 state recorded names only, so a
+ * byte change under an unchanged name was invisible. A state entry still in the
+ * old format has no hash to compare against, so every file counts as changed
+ * and re-uploads once (an idempotent overwrite) — after which the state carries
+ * hashes and the next push skips them.
+ *
+ * The removed set is a REPORT, not an action: deleting a remote attachment
+ * because a local file is missing waits for `--prune`.
+ */
+export declare function planAttachmentPush(params: {
+    local: Array<{
+        filename: string;
+        hash: string;
+    }>;
+    recorded: RecordedAttachments | undefined;
+}): {
+    upload: string[];
+    removedRemotely: string[];
+};
+/**
+ * Create a test case carrying the identity its file name asserts (#2896).
+ *
+ * The one case protocol detection cannot answer is a create into an EMPTY
+ * block: there is no listed record to read `key` off. Push is optimistic there,
+ * and an older server's 400 is the answer — retried once without the key, and
+ * named, because a case created without one will duplicate on the next clone.
+ */
+export declare function createTestCaseWithIdentity(params: {
+    client: ApiClient;
+    appId: string;
+    blockType: TestBlockType;
+    blockId: string;
+    payload: any;
+    /** Omitted when the server has no keys; then this is exactly the old call. */
+    key?: string;
+    logger?: (message: string) => void;
+}): Promise<any>;
+/**
+ * Push one block's authored test-case sidecar. Exported so the unit tests can
+ * drive it against a stubbed client on a temp directory.
+ *
+ * Plain push creates and updates only: a file the operator removed is reported
+ * as a pending deletion and handled by `--prune` (`applyTestCasePrune`).
+ */
+export declare function pushTestCasesForBlock(params: {
+    client: ApiClient;
+    appId: string;
+    blockType: TestBlockType;
+    blockId: string;
+    blockKey: string;
+    configDir: string;
+    syncState: SyncState | null;
+    dryRun: boolean;
+    changes: Array<{
+        type: string;
+        action: string;
+        key: string;
+    }>;
+    /** Where a rejected create/update/upload goes — it fails the push (#2731 B2). */
+    failures: ApplyFailure[];
+    /**
+     * What push DECLINED to apply (#2880): server drift, a conflict, a live read
+     * that failed with no baseline. Reported exactly as every other converted
+     * type reports it — the caller passes its `recordDeclined`.
+     */
+    declined?: (type: string, key: string, outcome: Extract<PushGateOutcome, {
+        action: "drift" | "conflict" | "immutable" | "live-unavailable";
+    }>, storedModifiedAt?: string) => void;
+    /** The id→name lookups the comparison reads a reference through (#2880). */
+    lookupMaps?: TestCaseLookupMaps;
+    /**
+     * Re-derive `lookupMaps` from the caller's name→id maps (#2880). Called after
+     * this case's references are resolved and before it is compared: resolution
+     * is what LOADS a block's configs, so the comparison would otherwise read a
+     * reference the same push just learned how to read.
+     */
+    refreshLookupMaps?: () => void;
+    resolutionMaps?: PushResolutionMaps;
+    options?: {
+        force?: boolean;
+    };
+}): Promise<{
+    skipped: number;
+}>;
+/**
+ * Whether a sidecar and a live case say the same thing (#2896).
+ *
+ * The corroboration the adoption passes below need: identity nothing states can
+ * only be inferred from content, and only when the inference is unique. It is
+ * the SAME projection `config diff` compares with, memoized per file and per
+ * record, so pairing and the change verdict can never disagree. A file that
+ * cannot be read matches nothing — an unparseable sidecar fails its own push
+ * with a message that names it.
+ */
+export declare function testCaseContentMatcher(params: {
+    testsDir: string;
+    spec: ConfigDiffSpec;
+    extra?: any;
+}): (localSlug: string, live: any) => boolean;
+/**
+ * Which live test case each sidecar manages (#2880 behavior 16, #2896).
+ *
+ * The manifest id comes FIRST, then the identity the COMMITTED tree carries —
+ * the file's basename, matched against the case's stored `key`. Everything
+ * after that is adoption of a case whose identity nothing states: a rename the
+ * manifest still remembers under the old name, a legacy case matched by
+ * content, and finally the slug-of-name rule #2880 shipped.
+ *
+ * The order matters because every pass consumes its claims: identity that IS
+ * recorded always wins over a guess, and a guess is only made when it is
+ * unambiguous in BOTH directions. Where it is not, the file stays unpaired and
+ * is barred from the create path — push refusing to guess is the whole point,
+ * since the failure it replaces is a silently duplicated test case.
+ *
+ * Against a server with no keys the passes that depend on them are skipped
+ * entirely, so pairing is bit-for-bit what #2880 shipped.
+ *
+ * One function for both commands, because a diff row and a push decision that
+ * pair differently are two answers to the same question.
+ */
+export declare function pairTestCases(input: {
+    blockType: string;
+    blockKey: string;
+    localSlugs: string[];
+    liveCases: any[];
+    managed: Record<string, {
+        id?: string;
+        slug?: string;
+        blockKey?: string;
+    }> | undefined;
+    /** Whether the server carries identity keys at all (#2896). */
+    serverSupportsKeys?: boolean;
+    /** Whether a local sidecar's content equals a live case's projection. */
+    contentMatches?: (localSlug: string, live: any) => boolean;
+}): {
+    bySlug: Map<string, any>;
+    localOnly: string[];
+    remoteOnly: any[];
+    /** Files adopted from a stale manifest entry: basename → that entry's key. */
+    renamedFrom: Map<string, string>;
+    /** Files barred from the create path this run, with the reason to report. */
+    refused: Map<string, string>;
+};
+/**
+ * `config diff` for one block's test-case sidecar (#2769). A failed listing is
+ * an OUTCOME the caller reports as "not compared" — the old helper returned
+ * silently, so a block whose tests could not be fetched simply disappeared from
+ * a report that still read as exhaustive.
+ */
+export interface TestCaseDiffRow {
+    blockType: string;
+    blockKey: string;
+    slug: string;
+    status: string;
+    /** What a validation error or a degraded comparison has to say. */
+    hint?: string;
+    /** Attachments push would upload from this sidecar (#2880 behavior 19). */
+    attachmentUploads?: string[];
+    /** Managed attachments `push --prune` would delete (never a plain push). */
+    attachmentDeletions?: string[];
+}
+export declare function compareTestCasesForBlock(params: {
+    client: ApiClient;
+    appId: string;
+    blockType: TestBlockType;
+    blockId: string;
+    blockKey: string;
+    configDir: string;
+    /** The manifest — identity, and the attachment hashes the plan reads. */
+    syncState?: SyncState | null;
+    lookupMaps?: TestCaseLookupMaps;
+}): Promise<{
+    ok: true;
+    rows: TestCaseDiffRow[];
+} | {
+    ok: false;
+}>;
+/**
+ * Shape errors in an authored test-case sidecar, for the push preflight
+ * (#2769). The unknown-key check beside it says which keys may appear; this
+ * says whether the ones that are there can be pushed at all — a missing `name`
+ * is a 400 from the server, and malformed JSON text used to be silently dropped
+ * on the way to it, pushing a test case that tested something else.
+ */
+export declare function testCaseSidecarErrors(filePath: string, tomlData: any): string[];
+/**
+ * EVERY reason `config push` refuses one test-case sidecar (#2880 criterion 1).
+ *
+ * The four checks the push preflight ran inline: the document's shape, the keys
+ * the definition recognizes, the declared type of each value, and the sidecar's
+ * own authoring rules (#2769). Collected in one place because `config diff`
+ * runs the identical list — it used to run only the last of the four, so a
+ * sidecar with an unknown key or a mistyped ordinary field was reported Synced
+ * by the command whose whole promise is that a Synced file pushes.
+ */
+export declare function testCaseSidecarPreflightErrors(filePath: string, tomlData: any): string[];
+/** A managed test case whose authored file is gone (#2769). */
+export interface TestCaseDeletionCandidate {
+    stateKey: string;
+    blockType: string;
+    blockId: string;
+    blockKey: string;
+    slug: string;
+    /** Absent when the case was never successfully created server-side. */
+    id?: string;
+    /**
+     * The state entry — with a file still on disk — that holds this same id
+     * (#2896). Set when the missing file was RENAMED rather than deleted: the
+     * case is alive under another name, so the row is cleared and nothing is
+     * deleted server-side.
+     */
+    supersededBy?: string;
+}
+/** A managed attachment whose local file is gone (#2769). */
+export interface AttachmentDeletionCandidate extends TestCaseDeletionCandidate {
+    filename: string;
+}
+/**
+ * Managed test cases whose `<slug>.toml` the operator removed (#2769).
+ *
+ * Only under a block that is itself still managed: when the BLOCK's file is
+ * gone too, the block's own prune owns the whole sidecar (`removePrunedSidecar`)
+ * and listing its cases here would delete them twice over.
+ */
+export declare function collectTestCaseDeletions(params: {
+    configDir: string;
+    testCaseEntities: Record<string, any> | undefined;
+    blockExists?: (blockType: string, blockKey: string) => boolean;
+}): TestCaseDeletionCandidate[];
+/**
+ * Managed attachments whose local file is gone, for a test case that survives
+ * (#2769). An absent attachment DIRECTORY is the authored spelling of "no
+ * attachments" — Git cannot carry an empty directory — so its recorded files
+ * are candidates too. Still `--prune`-gated: plain push deletes nothing.
+ */
+export declare function collectAttachmentDeletions(params: {
+    configDir: string;
+    testCaseEntities: Record<string, any> | undefined;
+    blockExists?: (blockType: string, blockKey: string) => boolean;
+}): AttachmentDeletionCandidate[];
+/**
+ * What a plain `config push` says about the sidecar deletions it is NOT
+ * applying (#2769), one report for the whole push.
+ *
+ * Attachments belong here rather than in the per-block push: deleting only a
+ * fixture leaves its test-case TOML untouched, so that push skips the case by
+ * hash and never reaches a message of its own — exactly the case an operator
+ * needs told, since the test keeps running against a file the tree no longer
+ * has. Returns the lines to print; empty when nothing is pending.
+ */
+export declare function formatPendingTestDeletions(params: {
+    testCases: TestCaseDeletionCandidate[];
+    attachments: AttachmentDeletionCandidate[];
+}): string[];
+/**
+ * Apply the test-case half of `config push --prune` (#2769).
+ *
+ * Runs after the batch confirmation, alongside the entity prunes: deletes the
+ * cases and attachments whose authored files are gone, drops their state, and
+ * routes failures into the push's failure list. Under `--dry-run` it counts the
+ * same rows and calls nothing.
+ */
+export declare function applyTestCasePrune(params: {
+    client: ApiClient;
+    appId: string;
+    testCaseEntities: Record<string, any>;
+    candidates: TestCaseDeletionCandidate[];
+    attachmentCandidates: AttachmentDeletionCandidate[];
+    dryRun: boolean;
+    changes: Array<{
+        type: string;
+        action: string;
+        key: string;
+    }>;
+    failures: ApplyFailure[];
+    logger?: (message: string) => void;
+}): Promise<{
+    deleted: number;
+    deletedAttachments: number;
+}>;
+/**
+ * Attach the server-reconciling verbs to the `config` group (issue #2759).
+ *
+ * They used to be a top-level `sync` noun, which split one workflow — managing
+ * the TOML configuration tree — across two nouns by whether a verb happened to
+ * call the API. Users do not think in that distinction; every real workflow
+ * crosses it. So `config` owns both halves, and this function takes the group
+ * `registerConfigCommands` created rather than making one of its own.
+ *
+ * The module keeps its name and its ~50 exported helpers: `sync.ts`,
+ * `resolveSyncDir`, the sync-state baseline and `primitive/<env>/`
+ * are internal identifiers, deliberately left alone (#2759 scope).
+ */
+export declare function registerConfigSyncCommands(sync: Command): void;