Model a Quota Burn step as a scheduled-task reference plus per-invocation overrides

[atomantic]

Problem / Goal

A Quota Burn step today is a copied prompt plus a free-form params bag: normalizeQuotaBurnJob in server/lib/quotaBurnConfig.js keys on a jobType from the QUOTA_BURN_JOB_TYPE enum and stores prompt text, so a step has no durable link to the scheduled task it was cloned from. #6372 replaces that with a reference to an existing scheduled task plus per-invocation overrides.

This child lands the data model, normalization, and validation only — no new execution path, no UI replacement, no migration.

Scope

• Define a discriminated task reference on a burn step: either a built-in scheduled type (plus a validated target app where the type requires one) or a custom scheduled job ID (whose own app scope is authoritative). Extend normalizeQuotaBurnJob / normalizeQuotaBurnFamily / normalizeQuotaBurnConfig in server/lib/quotaBurnConfig.js and the Zod schemas in server/lib/quotaBurnValidation.js (quotaBurnJobSchema / quotaBurnFamilySchema / quotaBurnConfigUpdateSchema, all .strict(), re-exported through server/lib/validation.js and used by PUT /api/quota-burn in server/routes/quotaBurn.js).
• Preserve the step's identity and settings: stable step id, family order, enabled, label, runOnce state, and family-level settings all survive normalization untouched.
• Per-invocation overrides: provider / model / effort and the supported run parameters, stored explicitly on the step. Unset values inherit the source task's saved settings. Overrides never write back to the schedule. A provider pin must belong to the selected burn family; an absent pin resolves inside that family and must never fall back to another family's subscription.
• Unavailable steps: a deleted, disabled, wrong-scope, or incompatible reference normalizes to a retained-but-unavailable step carrying an actionable reason. Its settings are never dropped, and it is not dispatchable.
• Legacy compatibility: old jobType payloads still load. Freeze QUOTA_BURN_JOB_TYPE, QUOTA_BURN_JOB_CATALOG, and server/lib/quotaBurnPresets.js as compatibility/migration inputs only — readable, never the canonical definition of new work. A legacy payload that has not yet been converted normalizes to unavailable with a migration reason rather than silently downgrading a reference or duplicating an automation.
• Preset identity is currently never persisted. Both the server (upgradeStoredAuditPrompt, server/lib/quotaBurnPresets.js) and the client (matchedPreset in client/src/components/quotaBurn/JobRow.jsx) re-derive it by comparing prompt text, which is exactly the fragility this reference model exists to remove. A reference must record identity durably, not re-derive it.
• Config lives in data/cos/quota-burn.json via server/services/quotaBurnStore.js and stays machine-local and unfederated (see the store's header comment and docs/STORAGE.md).

Acceptance criteria

• Round-trip tests: a reference-shaped config saves and reloads with step id, order, enabled, label, run-once state, family settings, and overrides byte-identical.
• Zod rejects a reference missing a required target app, a custom job id that is not a string, and a provider pin outside the step's family; each rejection names the offending field.
• An absent provider pin resolves within the step's own family — a test proves it cannot resolve to another family's provider.
• Dangling / disabled / wrong-scope references normalize to unavailable with a reason and retain every stored setting.
• An un-migrated legacy jobType payload normalizes to unavailable-with-migration-reason; it is never rewritten into a bogus reference and never duplicated.
• saveQuotaBurnConfig's shallow family merge and the client mirror client/src/lib/quotaBurnPatch.js#mergeQuotaBurnPatch stay line-for-line consistent (the store comment asserts this) — extend both or neither.

Notes

Foundation for the invocation-path, accounting, migration, and editor children. Ship this first among the burn-side children.

---

Part of #6372

When this ships, tick its box in the ## Decomposed into checklist on #6372. If it is the last unchecked box, close #6372.

[atomantic]

Claiming this. Recording the readings I settled on where the body left room, so the sibling children build on the same assumptions.

1. A legacy step is "not dispatchable" for the REFERENCE path only — the existing executor keeps running.
The body asks an un-migrated jobType payload to normalize to unavailable-with-a-migration-reason, but retiring JOB_MODULES is #6381 and the editor rewrite is #6382. Flipping every existing step to "unavailable" and cutting execution here would stop quota burn dead on every install for the length of the epic. So normalization stamps unavailable: { code: 'legacy-unmigrated' } and quotaBurnStepIsDispatchable() reports false, while quotaBurnRunner.js / JOB_MODULES are untouched and keep dispatching exactly as today. #6378's reference path is gated on the new predicate from the start, so it never inherits a legacy step.

2. overrides is canonical; the top-level providerId/model/effort/params stay as derived compat mirrors.
The shipped editor (JobRow.jsx) reads and writes those at the top level and moves to overrides in #6382. Emitting only overrides now would break the live page. Both are emitted and normalization derives one from the other on every read, so they cannot drift. Tie-break is key presence, not truthiness: a payload that carries a top-level key wins with it (including a deliberate null clear); only a payload with no top-level key at all falls through to overrides. Truthiness would resurrect a stale pin every time the user cleared a model.

3. Zod rejects a cross-family provider pin only when the ID unambiguously names another family.
The binary is what really decides a family (familyForProvider), and a schema cannot read the live provider list. So familyForProviderId() (new, in providerFamilies.js) answers claude/codex/agy/grok for a self-identifying id and null for anything else; a pin that resolves to a different family than the plan it sits in is a 400 naming families.<id>.jobs.<n>.overrides.providerId, and everything else falls through to dispatch-time resolution. Rejecting more would 400 a user's legitimately-named wrapper.

4. Availability resolution takes the catalog as an argument.
normalizeQuotaBurnConfig is pure and total, so it cannot ask the schedule store whether a task exists. Dangling/disabled/wrong-scope/incompatible resolution is resolveQuotaBurnStepAvailability(step, catalog) / applyQuotaBurnAvailability(config, catalog) — pure, non-mutating, and deliberately not persisted (the verdict is a fact about the catalog right now). #6378 wires it into the status read and the invocation path. An empty catalog resolves nothing, so a caller that has not loaded the schedule yet cannot mass-orphan a plan.

5. The store's shallow family merge and mergeQuotaBurnPatch are unchanged — "extend both or neither", and this change needs neither: jobs still replaces wholesale.

One supporting refactor rolled in: INSTALL_WIDE_TASK_TYPES / MANAGED_APP_TARGET_TASK_TYPES / requiresManagedAppTarget / requiresInstallWideTarget moved down to a new server/lib/taskTargetScope.js (re-exported from taskScheduleRegistry.js, so every existing caller is unchanged). server/lib may not import upward into server/services (lib/layering.test.js), and the reference schemas need the scope contract.