swallowkit 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/core/project/agent-templates/AGENTS.md

@@ -319,6 +319,20 @@ custom endpoints that derive the scoping key (e.g. `learnerId`) from the
 verified principal — never from the request body — and restrict the generated
 write endpoints to admin roles.
 
+Configure authentication with `plan auth` / `apply auth` **before** declaring
+`authPolicy`. Without authentication, an explicit policy
+blocks plan/apply/scaffold with `auth-policy-without-auth` before file writes;
+follow `nextActions`, then re-plan. Do not remove a required policy just to pass
+generation.
+An empty `authPolicy = {}` means no explicit policy; it does not enable authentication.
+
+With named `auth.schemes`, define `auth.authorization.policies` selecting the
+required schemes and roles, then use `authPolicy = { policy: 'adminOnly' }` (or
+read/write policy names). Role-only declarations do not select a named scheme
+and block with `auth-policy-requires-named-policy`. Conversely, single-provider
+`auth.provider` supports role lists only; a named policy (including a named
+`defaultPolicy`) blocks with `auth-named-policy-requires-named-scheme`.
+
 ## Verification Is a Completion Gate
 
 Before treating an agent-driven implementation as complete, run SwallowKit
@@ -330,8 +344,17 @@ verification:
 
 or the equivalent MCP operation.
 
-Verification covers SwallowKit structural correctness, drift, type correctness,
-and configured project checks.
+Default checks are `structure`, `drift`, `typecheck`, `backend-build`, plus
+configured project checks. `backend-build` checks standalone `functions/`:
+C# uses `dotnet build`, TypeScript uses the project's `tsc --noEmit`, and Python
+uses Python 3 `compileall` (syntax only, not imports or type checking), preferring
+`functions/.venv` over PATH. Missing toolchains are `skip` with an explanation;
+a skipped backend check is **not** evidence that the backend works. Restore the
+toolchain and re-run it before claiming backend validation.
+
+Root `build` scripts do not replace standalone backend verification. To include
+frontend production builds, use `--checks "structure,drift,typecheck,backend-build,build"`.
+Quote comma-separated values in PowerShell.
 
 When verification fails, use the structured failure explanation:
 
@@ -378,6 +401,24 @@ Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
 approval gate. A broad request to deploy does not itself grant the explicit
 approval required by that workflow.
 
+Provision applies Bicep once and tracks the original Azure deployment with a
+bounded wait. A local timeout/error, output truncation, or Ctrl+C is not proof
+that Azure failed. `in-progress` means Azure is Running/Accepted; `unknown`
+means its result could not be read; `partial` means Azure succeeded but
+tag/ledger completion is pending. Never re-submit Bicep, reconcile, adopt,
+cancel, or delete just to repair waiting or migration bookkeeping.
+
+Retain `.swallowkit/state/provision/` execution checkpoints. Use
+`{{runCmd}} swallowkit machine inspect provision --plan <runId> --wait-seconds 300`
+for read-only status/wait, and after explicit human approval use
+`{{runCmd}} swallowkit machine apply provision --plan <runId> --approve`
+to resume. `runId` equals the original `planId`; fingerprints, subscription,
+deployment identity and migration checks remain in force. Only
+`status: "complete"` / `outcome: "succeeded"` means Azure Succeeded plus verified
+tags and local ledger. Do not print deployment output secrets or raw `az --debug`.
+For older untracked baselines use `plan provision --resume-deployment <name>`
+with original target/regions; it blocks unless ARM/parameter evidence matches.
+
 ## SwallowKit Agent Skills and Runbooks
 
 SwallowKit installs task-specific Agent Skills under:
@@ -474,7 +515,9 @@ same generated structure.
 - Model schema files use `shared/models/{kebab-case}.ts`.
 - The Zod schema constant and inferred TypeScript type use the same PascalCase
   name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
-- Re-export models from `shared/index.ts`.
+- Re-export models from `shared/index.ts`. create-model and plan/apply scaffold
+  append missing exports, including manually authored models. Manual exports
+  are allowed; this file has no managed markers and existing content is preserved.
 - `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
   backend-managed fields.
 - Models may declare `partitionKey`, `authPolicy`, `displayName`,

package/src/core/project/agent-templates/CLAUDE.md

@@ -24,7 +24,16 @@ Always-on rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Inspect the original
+  execution checkpoint with `machine inspect provision --plan <runId>`; resume
+  `machine apply provision --plan <runId> --approve` only after explicit human
+  approval. Preserve checkpoints; never re-submit Bicep/reconcile/cancel/delete
+  to repair waiting or tag/ledger failures. Do not print deployment output secrets.
 - Run SwallowKit verification before considering implementation complete.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
 Equivalent agent-agnostic runbooks are available under

package/src/core/project/agent-templates/copilot-instructions.md

@@ -23,7 +23,17 @@ Key rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Read `status`, `outcome`,
+  and `nextActions`; inspect the original run with `machine inspect provision
+  --plan <runId>`, then resume `machine apply provision --plan <runId> --approve`
+  only after explicit human approval. Preserve execution checkpoints; never
+  re-submit Bicep or use reconcile/cancel/delete to repair waiting or tag/ledger
+  failures. Do not print deployment output secrets.
 - Run SwallowKit verification before completion.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills live under `.github/skills/`.
 Agent-agnostic equivalents live under `.swallowkit/workflows/`.

package/src/core/project/agent-templates/shared-models.instructions.md

@@ -18,8 +18,9 @@ source-of-truth models, subject to the current result of
 - `createdAt` and `updatedAt` are **optional** string fields
   (`z.string().optional()`). The backend manages their values.
 - Export a `displayName` string for UI display.
-- Re-export every model from `shared/index.ts`, outside managed markers where
-  applicable.
+- create-model and plan/apply scaffold append missing model exports to
+  `shared/index.ts`, including manually authored models. Manual exports are
+  allowed; there are no managed markers and existing content is preserved.
 - For relationships, use nested schemas rather than duplicating model shapes.
 
 ## Optional model declarations (exact formats)
@@ -30,7 +31,7 @@ These are the only declarations SwallowKit parses from a model file:
 // Cosmos DB partition key (default '/id'). Must reference a schema field.
 export const partitionKey = '/learnerId';
 
-// Role-based access control on generated CRUD.
+// Role-based access control on generated CRUD (requires plan/apply auth first).
 export const authPolicy = { roles: ['admin'] };
 // or: { read: ['user'], write: ['admin'] } or: { policy: 'adminOnly' }
 
@@ -48,6 +49,13 @@ export const connectorConfig = {
 The full machine-readable contract:
 `{{runCmd}} swallowkit machine inspect capabilities`
 
+An explicit `authPolicy` without authentication blocks plan/apply/scaffold with
+`auth-policy-without-auth` before writing files. Follow `nextActions` to configure
+auth, then re-plan. Do not drop a required guard to bypass the prerequisite.
+For named `auth.schemes`, use named authorization policies selecting schemes
+and roles, referenced by `policy` or read/write names. Role-only declarations
+block with `auth-policy-requires-named-policy` rather than emitting missing helpers.
+
 After changing a model, do not manually patch generated artifacts.
 
 ## After changing a model

package/src/core/project/boundaries.ts

@@ -86,7 +86,7 @@ export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
     zone: "shared",
     editPolicy: "edit-outside-markers",
     howToChange:
-      "SwallowKit appends only inside marked sections (e.g. `# SwallowKit scaffold registrations`). Edit anywhere outside the markers freely; do not remove the markers.",
+      "SwallowKit appends at the file-specific extension point: marked sections (e.g. `# SwallowKit scaffold registrations`) or append-only files such as shared/index.ts. Follow the path rule; preserve existing generated entries and any markers.",
   },
   {
     ownership: "metadata",
@@ -134,8 +134,8 @@ const COMMON_LEADING_RULES: BoundaryPathRule[] = [
   {
     pattern: "shared/index.ts",
     zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends model exports; other exports may be added freely.",
+    editPolicy: "free-edit",
+    description: "create-model and scaffold append missing model exports while preserving existing content. No managed markers; manual exports are allowed. Keep exports needed by generated code.",
   },
 ];
 

package/src/core/project/capabilities.ts

@@ -61,10 +61,19 @@ export interface CapabilitiesContract {
     notes: string[];
   };
   machineCommands: string[];
+  provisioning: {
+    execution: string;
+    completion: string;
+    tracking: string;
+    recovery: string;
+    diagnostics: string;
+    approval: string;
+  };
   verifyChecks: {
     defaultChecks: string[];
     optInChecks: string[];
     customChecks: string;
+    backendBuild: string;
   };
 }
 
@@ -109,6 +118,11 @@ export function inspectCapabilities(): CapabilitiesContract {
           "Role-based access control metadata applied to the generated CRUD Functions. `roles` guards all operations; `read`/`write` guard per-operation; `policy` references a named authorization policy from swallowkit.config auth.authorization.policies.",
         format:
           "export const authPolicy = { roles: ['admin'] };\n// or per-operation:\nexport const authPolicy = { read: ['user'], write: ['admin'] };\n// or a named policy:\nexport const authPolicy = { policy: 'adminOnly' };",
+        notes: [
+          "An explicit authPolicy without configured authentication blocks plan/apply/generate scaffold with auth-policy-without-auth before any artifacts are written. Run plan auth, apply auth, then re-plan scaffold. An empty {} declaration keeps the existing behavior: no explicit policy.",
+          "With named auth.schemes, define auth.authorization.policies selecting schemes and roles, then reference them via policy or read/write names. A role-only declaration cannot select a named scheme and blocks with auth-policy-requires-named-policy; it is supported by legacy single-provider authentication.",
+          "Conversely, single-provider authentication (auth.provider) supports role lists only. Referencing a named policy (authPolicy.policy, read/write names, or a named auth.authorization.defaultPolicy) blocks with auth-named-policy-requires-named-scheme; add a named scheme first.",
+        ],
       },
       {
         name: "references",
@@ -186,7 +200,7 @@ export function inspectCapabilities(): CapabilitiesContract {
         "Without authentication, plan scaffold reports user-scoped-data-without-auth when the partition key or an owner-like field (userId, learnerId, ownerId, ...) suggests per-user data.",
       ],
       guidance: [
-        "For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
+        "Configure authentication via plan/apply auth before declaring authPolicy. For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
       ],
     },
     sharedModels: {
@@ -200,7 +214,7 @@ export function inspectCapabilities(): CapabilitiesContract {
         "String formats (email/uuid/url), refinements, and transforms are not re-implemented natively; the BFF Zod schemas remain the authoritative validation.",
       ],
       buildNote:
-        "verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build the shared package first (errors like \"no exported member\" usually mean a stale dist).",
+        "create-model and plan/apply scaffold append missing model exports to shared/index.ts, including manually authored models. Manual exports are allowed (no markers); existing content is preserved. verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build shared first.",
     },
     seeding: {
       createTemplates: "swallowkit create-dev-seeds <environment> — writes dev-seeds/<environment>/<model>.json templates.",
@@ -208,20 +222,29 @@ export function inspectCapabilities(): CapabilitiesContract {
       notes: ["Editing dev-seeds/*.json alone does nothing; seeds are only applied via dev --seed-env."],
     },
     machineCommands: [
-      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities",
+      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities; inspect provision --plan <runId> [--wait-seconds <0-3600>]",
       "validate project",
       "generate model <names...> | generate scaffold <model>",
-      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if]",
-      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve",
+      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if] [--resume-deployment <name>]",
+      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve [--wait-seconds <0-3600>] (also resumes the same execution checkpoint)",
       "verify project [--checks <ids>] [--compact]",
       "explain failure [--check <id>]",
       "(regular CLI) migrations add-model <model> [--dry-run] — generate only the container migration after scaffold --skip-infra",
       "(regular CLI) configure-mcp [--version auto|latest|<semver>] — re-select the MCP launcher version in .mcp.json",
     ],
+    provisioning: {
+      execution: "Submit Bicep once with az deployment group create --no-wait, then bounded state polling (default 300 seconds, configurable 0-3600). Azure CLI invocations are bounded separately. Warning-only stderr with exit 0 is not a failure; output capture limits do not terminate az.",
+      completion: "status complete/outcome succeeded requires Azure Succeeded plus verified migration tags and local ledger completion. Running/Accepted -> in-progress; unreadable/not-found state -> blocked/outcome unknown; bookkeeping interruption after Azure Succeeded -> blocked/outcome partial; Failed/Canceled -> failed with Azure causes.",
+      tracking: "Approved runs persist before Azure writes under .swallowkit/state/provision/. runId equals the original planId and preserves the subscription, RG, deployment ID/correlation, fingerprints and migration state. inspect provision is read-only; apply provision --plan resumes without re-submitting attempted deployments. Ctrl+C/termination may leave Azure running; never cancel/delete without explicit consent.",
+      recovery: "For an older untracked baseline, plan provision --resume-deployment <name> compares the existing ARM template and non-secure parameters to the local Bicep/parameters. It observes that deployment and only tags/records it after Succeeded. Mismatches, unreadable evidence, secure parameters or non-baseline migrations block; do not use reconcile just to repair bookkeeping.",
+      diagnostics: "Results include bounded/redacted stdout/stderr, omitted-output flags, exit code, signal, failure kind, elapsed time and deployment identity. Deployment output values are not returned. Never print --debug output, keys, tokens or connection strings.",
+      approval: "Initial apply and every resume require explicit human approval. A passing local command or an ok envelope is not proof of completed Azure provisioning; inspect status, outcome and nextActions.",
+    },
     verifyChecks: {
-      defaultChecks: ["structure", "drift", "typecheck"],
+      defaultChecks: ["structure", "drift", "typecheck", "backend-build"],
       optInChecks: ["build", "lint", "test"],
       customChecks: "swallowkit.config verify.checks: [{ id, command, title?, timeoutMs? }]",
+      backendBuild: "Runs dotnet build in functions/ (C#), the project tsc --noEmit (TypeScript), or Python 3 compileall (syntax only, using functions/.venv before PATH). Missing toolchains are skip with a reason, not proof of validation. Root build scripts do not replace backend-build; use --checks \"structure,drift,typecheck,backend-build,build\" for both.",
     },
   };
 }

package/src/core/project/react-project.ts

@@ -407,7 +407,7 @@ live in \`functions/local.settings.json\`. Keep their secrets out of source cont
 \`\`\`sh
 ${pm} run build
 ${cmd.exec} swallowkit machine verify project
-${cmd.exec} swallowkit machine verify project --checks structure,drift,typecheck,build
+${cmd.exec} swallowkit machine verify project --checks "structure,drift,typecheck,backend-build,build"
 \`\`\`
 
 The build compiles shared schemas, checks the SPA, builds static assets, and

package/src/core/project/state.ts

@@ -57,6 +57,76 @@ export function deletePlanState(planId: string, projectRoot: string = process.cw
   }
 }
 
+function provisionRunPath(runId: string, projectRoot: string): string {
+  if (!/^[a-f0-9]{12}$/.test(runId)) throw new Error("Invalid provision run ID.");
+  return path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision", `${runId}.json`);
+}
+
+export function saveProvisionRun<T extends { runId: string }>(run: T, projectRoot: string = process.cwd()): void {
+  ensureStateDir(projectRoot);
+  const file = provisionRunPath(run.runId, projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(run, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+export function loadProvisionRun<T>(runId: string, projectRoot: string = process.cwd()): T | null {
+  const file = provisionRunPath(runId, projectRoot);
+  if (!fs.existsSync(file)) return null;
+  // Unlike a preview, discarding a corrupt execution checkpoint could replay Azure writes.
+  return JSON.parse(fs.readFileSync(file, "utf-8")) as T;
+}
+
+export function listProvisionRuns<T>(projectRoot: string = process.cwd()): T[] {
+  const directory = path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory).filter((name) => /^[a-f0-9]{12}\.json$/.test(name))
+    .map((name) => loadProvisionRun<T>(name.slice(0, -5), projectRoot)!);
+}
+
+/** A live local executor must not share an Azure target with another executor. */
+export function lockProvisionTarget(key: string, projectRoot: string = process.cwd()): () => void {
+  if (!/^[a-f0-9]{64}$/.test(key)) throw new Error("Invalid provision lock key.");
+  const directory = path.join(ensureStateDir(projectRoot), "provision");
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, `${key}.lock`);
+  const create = () => {
+    const descriptor = fs.openSync(file, "wx", 0o600);
+    try { fs.writeFileSync(descriptor, String(process.pid)); } finally { fs.closeSync(descriptor); }
+  };
+  try {
+    create();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const recoveryFile = `${file}.recovery`;
+    let descriptor: number;
+    try {
+      descriptor = fs.openSync(recoveryFile, "wx", 0o600);
+    } catch (recoveryError) {
+      if ((recoveryError as NodeJS.ErrnoException).code !== "EEXIST") throw recoveryError;
+      throw new Error("Provision lock recovery is already in progress. Inspect the checkpoint before retrying.");
+    }
+    fs.closeSync(descriptor);
+    try {
+      const pid = Number(fs.readFileSync(file, "utf-8"));
+      if (!Number.isInteger(pid) || pid < 1) throw new Error("Invalid provision lock; inspect the checkpoint before removing the lock.");
+      try {
+        process.kill(pid, 0);
+      } catch (probeError) {
+        if ((probeError as NodeJS.ErrnoException).code !== "ESRCH") throw probeError;
+        fs.unlinkSync(file);
+        create();
+        return () => fs.unlinkSync(file);
+      }
+      throw new Error("Another local provision executor is using this Azure target. Inspect its run; do not start a second deployment.");
+    } finally {
+      fs.unlinkSync(recoveryFile);
+    }
+  }
+  return () => fs.unlinkSync(file);
+}
+
 const LAST_VERIFY_FILE = "last-verify.json";
 
 export function saveLastVerifyState(result: unknown, projectRoot: string = process.cwd()): void {

package/src/core/project/workflows.ts

@@ -62,6 +62,13 @@ Goal: add a data model and derive CRUD/BFF/UI/infra deterministically.
      the plan warns \`infra-skipped\`; later run \`${runCmd} swallowkit migrations add-model <name>\` to add only the container migration.
    - Read \`data.warnings\`. \`user-scoped-data-without-auth\` means generated CRUD would expose every user's documents;
      add auth (\`swallowkit-add-auth\`) and owner-scoped ai-authored endpoints before exposing the model.
+   - \`auth-policy-without-auth\` blocks generation before file writes: configure authentication with plan/apply auth,
+     then re-plan. Do not remove a required policy to bypass this prerequisite.
+     For named \`auth.schemes\`, define named authorization policies selecting schemes/roles and reference them from
+     \`authPolicy.policy\` or read/write names; role-only declarations block with \`auth-policy-requires-named-policy\`.
+     Single-provider \`auth.provider\` supports role lists only; named policies block with \`auth-named-policy-requires-named-scheme\`.
+   - Scaffold appends missing exports to \`shared/index.ts\` for hand-authored models too.
+     Manual exports are allowed; no managed markers exist in that file.
 4. Apply:
    \`${runCmd} swallowkit machine apply scaffold --plan <planId>\`
 5. Verify:
@@ -160,7 +167,7 @@ the scoping key from the verified principal, never from the request body.
     title: "Verify and repair loop",
     skillName: "swallowkit-verify-repair",
     skillDescription:
-      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
+      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck/backend-build (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
     content: `# Workflow: Verify and repair
 
 Goal: converge the project to a verified state after any change.
@@ -168,14 +175,16 @@ Goal: converge the project to a verified state after any change.
 ## Loop
 
 1. \`${runCmd} swallowkit machine verify project\`
-   - default checks: structure, drift, typecheck (+ project-specific checks from swallowkit.config \`verify.checks\`)
-   - opt-in heavier checks: \`--checks structure,drift,typecheck,build,lint,test\`
+   - default checks: structure, drift, typecheck, backend-build (+ project-specific checks from swallowkit.config \`verify.checks\`)
+   - backend-build: standalone C# \`dotnet build\`, TypeScript \`tsc --noEmit\`, Python 3 \`compileall\` (syntax only).
+     Missing toolchains are skipped with a reason, not proof of a working backend. Restore them and re-run.
+   - opt-in heavier checks: \`--checks "structure,drift,typecheck,backend-build,build,lint,test"\` (quote CSV in PowerShell)
 2. If \`summary.done\` is false:
    - \`${runCmd} swallowkit machine explain failure\` → evidence (logTail, findings, violations) and suggestedActions per check.
    - Repair:
      - \`drift\` failures → follow each finding's \`repairAction\` (usually re-run plan/apply scaffold).
      - \`structure\` failures → follow \`suggestedFix\` per violation.
-     - \`typecheck\`/\`build\`/\`lint\`/\`test\` failures → fix the code in ai-authored files.
+     - \`typecheck\`/\`backend-build\`/\`build\`/\`lint\`/\`test\` failures → fix the source code, not generated artifacts.
 3. Repeat until \`summary.done: true\`.
 
 ## Exit criteria
@@ -205,6 +214,9 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
 - Inspect infra locally first — no \`az\` calls are needed for inspection.
 - Never edit an applied migration. Create a corrective migration instead.
 - Never use \`--reconcile\` for an ordinary model or resource addition.
+- A local az error/timeout or Ctrl+C does not prove Azure failed. Never
+  re-submit, cancel, or delete a deployment to repair a wait or bookkeeping failure.
+- Respect \`status\`, \`outcome\`, and \`nextActions\`, not just \`ok\`.
 
 ## Steps
 
@@ -212,7 +224,7 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
    \`${runCmd} swallowkit machine inspect infra\`
    - review parameters, modules, outputs, and container wiring warnings.
 2. Compute the provisioning plan (no resources are created):
-   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region>\`
+   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region> --swa-location <swa-region>\`
   - the plan reports \`bootstrap\`, \`migrate\`, \`noop\`, or \`adoption-required\`.
   - it lists only pending migrations and the exact \`az\` commands that would run.
   - for an older untagged environment, first run \`${runCmd} swallowkit migrations init --legacy-baseline\`, then plan with \`--adopt-existing --baseline 0 --what-if\`.
@@ -220,12 +232,35 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
 3. Present the plan to the human and wait for explicit approval.
 4. Only after approval:
    \`${runCmd} swallowkit machine apply provision --plan <planId> --approve\`
-5. Verify the deployment outputs and report them.
+5. If \`in-progress\`, \`unknown\`, or \`partial\`, retain the execution
+   checkpoint and read/wait for the original deployment:
+   \`${runCmd} swallowkit machine inspect provision --plan <runId> --wait-seconds 300\`.
+   Inspection never writes Azure tags or the local ledger.
+6. After fresh explicit human approval, resume:
+   \`${runCmd} swallowkit machine apply provision --plan <runId> --approve\`.
+   Attempted deployments are not re-submitted; remaining reviewed steps and
+   tags/ledger finish only after Azure \`Succeeded\`.
+7. Report completion only when \`status: "complete"\` and
+   \`outcome: "succeeded"\`. Never report deployment output secrets.
+
+For an older untracked bootstrap, plan with \`--resume-deployment <name>\`
+and the original RG, subscription and regions. Recovery compares its ARM
+template and non-secure parameters to local Bicep before approval. Mismatch,
+unreadable evidence or secure parameters block; do not work around this by
+using reconcile/adoption or replacing the migration manifest.
 
 ## Terminal states
 
 \`apply provision\` without \`--approve\` fails with \`approval-required\` —
 this is the guardrail working as intended, not an error to work around.
+
+Azure \`Running\`/\`Accepted\` means \`in-progress\`. An unreadable or missing
+deployment means \`unknown\`, not Azure failure. Azure \`Failed\`/\`Canceled\`
+returns sanitized Azure and operation causes. Azure \`Succeeded\` with incomplete
+tag/ledger writes means \`partial\`; resume bookkeeping without redeploying.
+The default wait is 300 seconds (0-3600 via \`--wait-seconds\`), not unlimited.
+Warning-only stderr with exit 0 is accepted. Diagnostics report local exit,
+signal, elapsed time and truncated/redacted output separately from Azure state.
 `,
   };
 
@@ -254,7 +289,8 @@ under \`.github/skills/\` so skills-aware agents load them automatically.
 
 - **ai-authored** (write freely): \`shared/models/\`, business logic, custom pages/components, tests.
 - **deterministic** (never hand-edit): artifacts generated by SwallowKit (see \`.swallowkit/artifacts.json\`) and \`.swallowkit/\` metadata. Change models/config and regenerate via plan/apply.
-- **shared** (edit outside markers): \`shared/index.ts\`, plus backend registration files for the configured language (Python: \`functions/function_app.py\`).
+- **shared**: \`shared/index.ts\` allows manual exports (no markers; SwallowKit appends missing entries).
+  For Python \`functions/function_app.py\`, edit outside the registration marker.
 - **infrastructure**: baseline \`infra/\` files are checksum-locked by \`infra/migrations/manifest.json\`; add resources as new migrations (\`swallowkit create-migration <slug>\`, \`swallowkit migrations add-model <model>\`).
 
 Full machine-readable contract: \`${runCmd} swallowkit machine inspect boundaries\`

package/src/core/scaffold/auth-generator.ts

@@ -117,8 +117,7 @@ export function generateNamedAuthRouterCSharp(config: NormalizedAuthConfig): str
 using System.Text;
 using System.Text.Json;
 using Microsoft.Azure.Functions.Worker.Http;
-using Functions.Auth.Schemes;
-namespace Functions.Auth;
+${externalCases ? "using Functions.Auth.Schemes;\n" : ""}namespace Functions.Auth;
 public record AuthPrincipal(string Subject, string Scheme, string Issuer, string[] Roles, IReadOnlyDictionary<string, object?> Claims)
 {
     [Obsolete("Use Subject")] public string UserId => Subject;
@@ -171,15 +170,15 @@ ${externalCases}
 export function generateNamedAuthRouterPython(config: NormalizedAuthConfig): string {
   const external = Object.entries(config.schemes).filter(([,s])=>s.provider === "external-token");
   const imports = external.map(([n])=>`from auth.schemes.${schemeSlug(n).replace(/-/g,"_")}.verifier import verify_external_token as verify_${safeIdentifier(n)}, ExternalTokenVerificationError as Error_${safeIdentifier(n)}`).join("\n");
-  const cases = external.map(([n], index)=>`        ${index === 0 ? "if" : "elif"} scheme == ${JSON.stringify(n)}:
-            try:
-                value = verify_${safeIdentifier(n)}(bearer)
-            except Error_${safeIdentifier(n)} as exc:
-                raise AuthError(503 if exc.identity_provider_unavailable else 401, "Identity provider unavailable" if exc.identity_provider_unavailable else "Invalid token")
-            except Exception:
-                raise AuthError(503, "External token verifier unavailable")
-            if not value.get("subject") or not isinstance(value.get("roles"), list): raise AuthError(401, "Invalid external principal")
-            principal = {"subject": value["subject"], "scheme": scheme, "issuer": value.get("issuer", scheme), "roles": value["roles"], "claims": value.get("claims", {}), "userId": value["subject"]}`).join("\n");
+  const cases = external.map(([n], index)=>`    ${index === 0 ? "if" : "elif"} scheme == ${JSON.stringify(n)}:
+        try:
+            value = verify_${safeIdentifier(n)}(bearer)
+        except Error_${safeIdentifier(n)} as exc:
+            raise AuthError(503 if exc.identity_provider_unavailable else 401, "Identity provider unavailable" if exc.identity_provider_unavailable else "Invalid token")
+        except Exception:
+            raise AuthError(503, "External token verifier unavailable")
+        if not value.get("subject") or not isinstance(value.get("roles"), list): raise AuthError(401, "Invalid external principal")
+        principal = {"subject": value["subject"], "scheme": scheme, "issuer": value.get("issuer", scheme), "roles": value["roles"], "claims": value.get("claims", {}), "userId": value["subject"]}`).join("\n");
   return `import base64
 import json
 import azure.functions as func
@@ -199,14 +198,14 @@ def require_auth(req: func.HttpRequest, policy_name: str):
     if len(candidates) != 1: raise AuthError(401, "Authentication required" if not candidates else "Ambiguous credentials")
     scheme = candidates[0]
 ${cases}
-        ${external.length ? "elif" : "if"} PROVIDERS[scheme] == "swa":
-            try:
-                value=json.loads(base64.b64decode(swa).decode("utf-8")); roles=[r for r in value.get("userRoles",[]) if isinstance(r,str)]
-                if not value.get("userId") or "authenticated" not in roles: raise ValueError()
-                if ALLOWED_PROVIDERS[scheme] and value.get("identityProvider") not in ALLOWED_PROVIDERS[scheme]: raise ValueError()
-                principal={"subject":value["userId"],"scheme":scheme,"issuer":"swa:"+value.get("identityProvider", "unknown"),"roles":roles,"claims":value,"userId":value["userId"]}
-            except Exception: raise AuthError(401,"Invalid SWA client principal")
-        else: raise AuthError(401,"Authentication adapter is not configured")
+    ${external.length ? "elif" : "if"} PROVIDERS[scheme] == "swa":
+        try:
+            value=json.loads(base64.b64decode(swa).decode("utf-8")); roles=[r for r in value.get("userRoles",[]) if isinstance(r,str)]
+            if not value.get("userId") or "authenticated" not in roles: raise ValueError()
+            if ALLOWED_PROVIDERS[scheme] and value.get("identityProvider") not in ALLOWED_PROVIDERS[scheme]: raise ValueError()
+            principal={"subject":value["userId"],"scheme":scheme,"issuer":"swa:"+value.get("identityProvider", "unknown"),"roles":roles,"claims":value,"userId":value["userId"]}
+        except Exception: raise AuthError(401,"Invalid SWA client principal")
+    else: raise AuthError(401,"Authentication adapter is not configured")
     require_roles(principal, policy.get("roles", [])); return principal
 def require_roles(principal, roles):
     if roles and not any(role in principal.get("roles",[]) for role in roles): raise AuthError(403,"Insufficient permissions")

package/src/core/scaffold/native-schema-generator.ts

@@ -939,6 +939,21 @@ function ensurePythonCodegenProjectFiles(
   return requirementsPath;
 }
 
+/** Generated backend_models import pydantic v2 at runtime, so the deployed Functions app must install it. */
+export const PYTHON_SCHEMA_RUNTIME_REQUIREMENT = "pydantic>=2.6,<3";
+
+function ensurePythonRuntimeRequirement(functionsRoot: string, session: FileOperationSession): void {
+  const requirementsPath = path.join(functionsRoot, "requirements.txt");
+  const current = session.fileExists(requirementsPath) ? session.readFile(requirementsPath) : "";
+  const declared = current.split(/\r?\n/).some((line) => line.trim().split(/[<>=!~;[ ]/)[0].toLowerCase() === "pydantic");
+  if (declared) return;
+  const prefix = current && !current.endsWith("\n") ? `${current}\n` : current;
+  session.writeFile(requirementsPath, `${prefix}${PYTHON_SCHEMA_RUNTIME_REQUIREMENT}\n`, {
+    ownership: "extension-point",
+    generator: "native-schema",
+  });
+}
+
 async function ensureProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
   const uvEnv = { ...process.env };
   const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
@@ -1082,6 +1097,7 @@ async function generatePythonSchemaArtifacts(
   sourceModel: string
 ): Promise<void> {
   ensurePythonCodegenProjectFiles(functionsRoot, session, sourceModel);
+  ensurePythonRuntimeRequirement(functionsRoot, session);
 
   const packageRoot = path.join(outputDir, "backend_models");
   const modelsRoot = path.join(packageRoot, "models");