cabloy 5.1.210 → 5.1.211

package/.cabloy-version

@@ -1 +1 @@
-5.1.210
+5.1.211

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 5.1.211
+
+### Features
+
+- Add an OpenAPI SDK.
+- Add draft functionality.
+
 ## 5.1.210
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.210",
+  "version": "5.1.211",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -47,6 +47,7 @@
     "start:one": "cd vona && npm run start:one",
     "test": "cd vona && npm run test",
     "test:e2e": "node scripts/runIsolatedTest.ts e2e",
+    "contract:generate:isolated": "node scripts/generateOpenapiIsolated.ts",
     "test:docs:e2e": "npm run docs:build && playwright test --config repo-e2e/docs/playwright.config.ts",
     "db:reset": "cd vona && npm run db:reset",
     "tsc": "npm run tsc:zova && pnpm --dir vona run tsc",

package/repo-agent-governance/managed-assets.json

@@ -53,14 +53,14 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "004d81369d47f539092bf054cf5604f3185805391110553f349dd53247bed386",
+      "sha256": "bf8de5cbd1602d00aadaa1c1b91c15f4a2272fb03d88faa9a428d96e4486bbe4",
       "source": "skills/cabloy-contract-loop/references/verification-checklist.md",
       "target": ".agents/skills/cabloy-contract-loop/references/verification-checklist.md"
     },
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "897a2bda7df448cc2f8468c9e23a090f0bd16bcd49fbb30427c95b11340b64c8",
+      "sha256": "4aeb0477e3cb316b14bca7c4a3d1e277329be4a8f8e14ef31a3ceb858b6b0698",
       "source": "skills/cabloy-contract-loop/SKILL.md",
       "target": ".agents/skills/cabloy-contract-loop/SKILL.md"
     },
@@ -389,14 +389,14 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "004d81369d47f539092bf054cf5604f3185805391110553f349dd53247bed386",
+      "sha256": "bf8de5cbd1602d00aadaa1c1b91c15f4a2272fb03d88faa9a428d96e4486bbe4",
       "source": "skills/cabloy-contract-loop/references/verification-checklist.md",
       "target": ".claude/skills/cabloy-contract-loop/references/verification-checklist.md"
     },
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "897a2bda7df448cc2f8468c9e23a090f0bd16bcd49fbb30427c95b11340b64c8",
+      "sha256": "4aeb0477e3cb316b14bca7c4a3d1e277329be4a8f8e14ef31a3ceb858b6b0698",
       "source": "skills/cabloy-contract-loop/SKILL.md",
       "target": ".claude/skills/cabloy-contract-loop/SKILL.md"
     },
@@ -739,14 +739,14 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "004d81369d47f539092bf054cf5604f3185805391110553f349dd53247bed386",
+      "sha256": "bf8de5cbd1602d00aadaa1c1b91c15f4a2272fb03d88faa9a428d96e4486bbe4",
       "source": "skills/cabloy-contract-loop/references/verification-checklist.md",
       "target": ".cursor/skills/cabloy-contract-loop/references/verification-checklist.md"
     },
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "897a2bda7df448cc2f8468c9e23a090f0bd16bcd49fbb30427c95b11340b64c8",
+      "sha256": "4aeb0477e3cb316b14bca7c4a3d1e277329be4a8f8e14ef31a3ceb858b6b0698",
       "source": "skills/cabloy-contract-loop/SKILL.md",
       "target": ".cursor/skills/cabloy-contract-loop/SKILL.md"
     },

package/repo-agent-governance/skills/cabloy-contract-loop/SKILL.md

@@ -206,7 +206,7 @@ That may include:
 - confirming DTO and validation alignment
 - checking Swagger/OpenAPI output
 - confirming that the changed endpoint or schema now reflects the intended contract
-- if local OpenAPI generation depends on a running Swagger source, starting the backend service first — in Cabloy Basic, `npm run dev` is the normal path and exposes `http://localhost:7102/swagger/json?version=V31`
+- for AI-driven local OpenAPI generation, using the managed isolated service by default as described in Path A below; do not make a separately running development service a prerequisite
 
 If the backend contract output is wrong, frontend regeneration will only spread the mistake.
 
@@ -218,17 +218,23 @@ Once the backend contract is correct, decide how the frontend should consume it.
 
 Use this when the frontend consumes generated API contracts.
 
-Typical Zova commands include:
+For AI development, **default to managed isolated generation**, even when a development Swagger service is currently reachable. An independently managed development service may stop at any time; owning the service lifecycle keeps the generation task continuous and its contract source consistent.
 
-- `npm run zova :openapi:config ...`
-- `npm run zova :openapi:generate ...`
+1. Detect the edition and verify the isolated entrypoint in the active root `package.json`. Cabloy Basic provides:
 
-Preflight reminder:
+   ```bash
+   npm run contract:generate:isolated -- <module-name>
+   ```
 
-- if `:openapi:generate` reads from a local Swagger endpoint, do not assume the generator itself is broken when fetch fails
-- first start the backend service, typically with `npm run dev`, and confirm `http://localhost:7102/swagger/json?version=V31` is reachable
+   For Cabloy Start or another version, verify the actual command and configuration support rather than assuming the Basic entrypoint exists.
 
-When the target is a module-local SDK, constrain `openapi.config.ts` with `operations.match` unless the module intentionally owns a broad API surface. This prevents unrelated APIs from being generated into the module.
+2. Initialize module configuration with `npm run zova :openapi:config <module-name>` when needed. Keep module ownership constrained with `operations.match` unless the module intentionally owns a broad API surface; the isolated command reuses the existing generator and ownership checks.
+3. Confirm the effective source uses the isolated service. The command supplies a child-scoped `OPENAPI_SOURCE_URL` to the project default source resolver; explicit module sources or project `modules` overrides retain their precedence. Inspect the project resolver and align conflicting sources deliberately before claiming isolated generation. Do not edit `.env` files or SDK runtime API targets to inject the temporary port.
+4. Coordinate shared output writes. The service and claim-backed test resources are isolated, but generated SDK/schema/metadata files remain shared workspace output: serialize generation and do not assume automatic rollback. Successful runs clean their owned resources after shutdown; failures retain evidence and must remain visible, not trigger a silent fallback to development Swagger.
+
+Use `npm run zova :openapi:generate <module-name>` only as a deliberate exception, such as an explicit user request or a contract source that must come from a specific external or development environment. Record the reason and verify the configured source and its availability; current reachability alone is not a reason to override the AI default. If isolated support is absent, report that limitation and establish an explicit alternative rather than silently relying on a development service.
+
+See [OpenAPI SDK Guide](../../../repo-docs/frontend/openapi-sdk-guide.md) for source precedence and configuration compatibility, and [Contract Loop Playbook](../../../repo-docs/fullstack/contract-loop-playbook.md#forward-chain-playbook) for the full forward-chain workflow.
 
 ### Path B: REST/type generation by flavor
 

package/repo-agent-governance/skills/cabloy-contract-loop/references/verification-checklist.md

@@ -15,7 +15,10 @@ After a contract-loop change, verify the branch that actually applies.
 - DTO and validation align
 - OpenAPI output reflects the intended shape
 - module ownership is constrained
-- regeneration commands completed successfully
+- AI-driven SDK generation used the source-confirmed isolated entrypoint by default, regardless of development-service reachability; any direct-source exception has an explicit reason
+- the effective project/module source resolves to the intended contract source; explicit source overrides did not silently bypass isolation
+- regeneration commands completed successfully; isolated failures remained visible rather than falling back silently to development Swagger
+- isolated resources were cleaned after success or retained as failure evidence, and shared SDK/schema/metadata writes were coordinated and inspected without assuming automatic rollback
 - generated SDK or schema outputs are updated
 - thin model facades and downstream consumers still align with the regenerated contract
 - `npm run tsc`

package/repo-agent-governance/tests/governance.test.mjs

@@ -211,6 +211,71 @@ test('initializer preserves a legacy-customized adapter during a staged upgrade'
   });
 });
 
+for (const scenario of [
+  { name: 'adopts a missing command', incoming: true },
+  {
+    name: 'leaves a matching command byte-identical',
+    incoming: true,
+    command: 'node scripts/generateOpenapiIsolated.ts',
+  },
+  {
+    name: 'reports and preserves a customized command',
+    incoming: true,
+    command: 'node project-contract.mjs',
+  },
+  { name: 'reports and preserves an empty customized command', incoming: true, command: '' },
+  { name: 'tolerates an older staged package without the command', incoming: false },
+]) {
+  test(`staged initializer isolated contract bridge ${scenario.name}`, () => {
+    withFixture(root => {
+      const name = 'contract:generate:isolated';
+      const incomingCommand = 'node scripts/generateOpenapiIsolated.ts';
+      const fixtureBootstrap = resolve(root, 'scripts/bootstrapAgentGovernance.mjs');
+      mkdirSync(dirname(fixtureBootstrap));
+      cpSync(resolve(ROOT_DIR, 'scripts/bootstrapAgentGovernance.mjs'), fixtureBootstrap);
+
+      const upgradeRoot = resolve(root, 'node_modules/.cabloy-upgrade');
+      cpSync(GOVERNANCE_DIR, resolve(upgradeRoot, 'repo-agent-governance'), { recursive: true });
+      const sourcePackage = JSON.parse(readFileSync(resolve(ROOT_DIR, 'package.json'), 'utf8'));
+      delete sourcePackage.scripts[name];
+      const projectPackage = structuredClone(sourcePackage);
+      projectPackage.scripts['project:custom'] = 'node project-owned.mjs';
+      if (Object.hasOwn(scenario, 'command')) projectPackage.scripts[name] = scenario.command;
+      if (scenario.incoming) sourcePackage.scripts[name] = incomingCommand;
+      writeFileSync(resolve(upgradeRoot, 'package.json'), JSON.stringify(sourcePackage));
+      const projectPackagePath = resolve(root, 'package.json');
+      const before = `${JSON.stringify(projectPackage)}\n`;
+      writeFileSync(projectPackagePath, before);
+
+      const result = runNode(root, fixtureBootstrap);
+      assert.equal(result.status, 0, result.output);
+      const customized = Object.hasOwn(scenario, 'command') && scenario.command !== incomingCommand;
+      const adopted = scenario.incoming && !Object.hasOwn(scenario, 'command');
+      const updated = JSON.parse(readFileSync(projectPackagePath, 'utf8'));
+      if (adopted) {
+        assert.match(result.output, /Added missing.*contract:generate:isolated/);
+        assert.deepEqual(updated, {
+          ...projectPackage,
+          scripts: { ...projectPackage.scripts, [name]: incomingCommand },
+        });
+      } else {
+        assert.equal(readFileSync(projectPackagePath, 'utf8'), before);
+      }
+      if (customized) {
+        assert.match(result.output, /Preserved customized.*contract:generate:isolated/);
+        assert.ok(result.output.includes(incomingCommand), result.output);
+      } else {
+        assert.doesNotMatch(result.output, /Preserved customized.*contract:generate:isolated/);
+      }
+      const first = readFileSync(projectPackagePath, 'utf8');
+      const second = runNode(root, fixtureBootstrap);
+      assert.equal(second.status, 0, second.output);
+      assert.equal(readFileSync(projectPackagePath, 'utf8'), first);
+      assert.doesNotMatch(second.output, /Added missing.*contract:generate:isolated/);
+    });
+  });
+}
+
 test('governance adoption adopts byte-identical legacy outputs', () => {
   withFixture(root => {
     assert.equal(runGovernance(root, 'render').status, 0);

package/repo-docs/ai/playbook-contract-regeneration.md

@@ -54,6 +54,8 @@ Before regenerating frontend artifacts:
 
 Use the Zova OpenAPI and REST-generation path rather than manually updating request code first. Follow the canonical [Contract Loop Playbook](/fullstack/contract-loop-playbook#forward-chain-playbook) for the active edition’s complete generation and verification sequence.
 
+In Cabloy Basic, if no development Swagger service should be started or reused, use `npm run contract:generate:isolated -- <module-name>`. It verifies a fresh test-mode Vona service's signed readiness response and invokes the existing Zova generator against its Swagger source; generated SDK output remains shared workspace output and concurrent generation must be serialized.
+
 Do not treat `build:rest:*` as a standalone current command recipe. Resolve the active edition’s full build path from the canonical playbook and current root scripts so SSR bundle and REST output stay synchronized.
 
 For Start, resolve Start-specific flavor paths from that repository.

package/repo-docs/frontend/openapi-sdk-guide.md

@@ -59,20 +59,39 @@ Representative use case:
 
 Example: generate OpenAPI-based frontend services for module `training-student`.
 
+The direct command is the fast path when a development Swagger service is already available:
+
+```bash
+npm run zova :openapi:generate training-student
+```
+
+In Cabloy Basic, when generation should use a fresh isolated test-mode Vona service instead:
+
 ```bash
+npm run contract:generate:isolated -- training-student
+```
+
+The isolated command uses the same generator and preserves module ownership validation, but manages a disposable service, claim, and test resources without starting Playwright. Generated files under `zova/src/**` are shared workspace output, not run-owned temporary files; serialize concurrent SDK generation and do not expect automatic rollback.
+
+The project-level source resolver accepts `OPENAPI_SOURCE_URL` as a complete OpenAPI document URL. It takes precedence over `API_BASE_URL` for generation only and does not change runtime `OPENAPI_BASE_URL_*` request targets:
+
+```bash
+OPENAPI_SOURCE_URL=https://example.test/swagger/json?version=V31 \
 npm run zova :openapi:generate training-student
 ```
 
+The override changes the project default source. Explicit module sources in module config or project `modules` config retain their existing precedence; remove or align those overrides when the module must use the isolated service. Do not commit source URLs containing credentials or access tokens. Existing project `openapi.config.ts` files are not overwritten by `:openapi:config`; merge the resolver when upgrading an older project manually.
+
 ## Build the rest-contract output
 
-For Cabloy Basic, representative contract-build commands include:
+SDK generation and flavor builds are separate steps. When refreshed frontend output must be handed back to Vona, use the paired SSR/REST build for each affected flavor, then synchronize dependencies. For Cabloy Basic Admin:
 
 ```bash
-cd zova && npm run build:rest:cabloyBasicAdmin
-cd zova && npm run build:rest:cabloyBasicWeb
+npm run build:zova:admin
+npm run deps:vona
 ```
 
-This matters because SDK generation and rest-contract build steps are related, but not identical.
+Also run `npm run build:zova:web` before dependency synchronization when Web is affected. Do not use `build:rest:*` alone for this reverse handoff; the SSR bundle and REST output must move together. See [Contract Loop Playbook](/fullstack/contract-loop-playbook#reverse-chain-playbook).
 
 ## Important convention
 

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -221,6 +221,14 @@ npm run zova :openapi:config <module-name>
 npm run zova :openapi:generate <module-name>
 ```
 
+The direct command is the fast path when a development Swagger service is already available. In Cabloy Basic, when the workflow should own a fresh test-mode service instead, use:
+
+```bash
+npm run contract:generate:isolated -- <module-name>
+```
+
+This isolated path reuses the existing Zova generator and module ownership checks, but starts Vona in an isolated test run without Playwright. Its claim-backed test resources are cleaned after success and retained on failure; generated SDK files remain shared workspace output, so serialize concurrent generation and do not assume rollback.
+
 When the target is a module-local SDK, keep ownership constrained with `operations.match` so the module only generates the API surface it actually owns.
 
 ### Stage 4: Thin frontend follow-up

package/repo-docs/fullstack/openapi-to-sdk.md

@@ -135,18 +135,24 @@ Representative frontend-side contract-generation commands include:
 ```bash
 npm run zova :openapi:config training-student
 npm run zova :openapi:generate training-student
-cd zova && npm run build:rest:cabloyBasicAdmin
-cd zova && npm run build:rest:cabloyBasicWeb
 ```
 
+When no development service should be started or reused, use the isolated contract path instead:
+
+```bash
+npm run contract:generate:isolated -- training-student
+```
+
+This starts a disposable test-mode Vona service, verifies its signed readiness response and OpenAPI document, runs the same Zova generator, and cleans its claim-backed test resources after success. The generated SDK output is still shared workspace output; serialize concurrent generation and inspect or repair it explicitly rather than expecting rollback.
+
 A practical forward-chain sequence is:
 
 1. author or change the backend contract
 2. emit or inspect backend OpenAPI output
-3. if the frontend generator reads from a local Swagger endpoint, start the backend service first so the endpoint is reachable — in this repo, `npm run dev` is the normal path and exposes Swagger at `http://localhost:7102/swagger/json?version=V31`
+3. choose the source lifecycle: reuse a reachable development Swagger service for the direct command (`npm run dev` normally exposes `http://localhost:7102/swagger/json?version=V31`), or let the isolated command own a fresh test-mode service
 4. configure frontend module ownership if needed
-5. generate module-level OpenAPI SDK output
-6. run the rest build for the active flavor when needed
+5. generate module-level OpenAPI SDK output with the selected command
+6. when frontend output must be handed back to Vona, run the paired flavor build (`npm run build:zova:admin`, plus `npm run build:zova:web` when affected), then `npm run deps:vona`; REST-only builds are not sufficient for this handoff
 7. consume the generated contract from frontend code instead of re-declaring it manually
 8. keep frontend follow-up thin by wrapping generated consumers with semantic facades instead of re-declaring the contract
 9. when the custom API still belongs to an existing resource, reuse the existing resource-owner instead of creating a competing cache owner
@@ -162,7 +168,7 @@ If both `operations.match` and `operations.ignore` are empty, frontend SDK gener
 A practical regeneration rule is:
 
 - if the backend contract changed, prefer regenerating the SDK/rest layer before hand-editing frontend request code
-- if `npm run zova :openapi:generate ...` fails because the local Swagger source is unavailable, first start the backend service and confirm `http://localhost:7102/swagger/json?version=V31` is reachable before treating generation as broken
+- if `npm run zova :openapi:generate ...` fails because the local Swagger source is unavailable, start the backend service and confirm the configured source is reachable, or use `npm run contract:generate:isolated -- <module-name>` instead
 - if the generated consumer path is already correct, but frontend behavior still looks stale, stop patching generated files and diagnose consumer drift or local dependency drift instead
 
 ## `training-student` as a compact forward-chain specimen

package/repo-docs/reference/repo-scripts.md

@@ -41,6 +41,7 @@ Cabloy Basic exposes these shared root scripts:
 - `npm run start:one`
 - `npm run test`
 - `npm run test:e2e`
+- `npm run contract:generate:isolated`
 - `npm run db:reset`
 - `npm run tsc`
 - `npm run docs:dev`
@@ -79,6 +80,8 @@ Judge preflight conflicts by actual resource overlap, not process names:
 
 A process-list match or a free port alone is not proof of either a conflict or safe ownership. Use the managed root entrypoints and retain normal execution-authorization checks; isolation is not a blanket reset or cleanup authorization.
 
+`npm run contract:generate:isolated -- <module-name>` starts a fresh test-mode Vona service on a run-owned loopback port, verifies its signed readiness response, fetches the Swagger document, and invokes the existing Zova OpenAPI generator without Playwright. The run owns its disposable test resources and claim-backed local roots; successful runs clean them after the service drains, while failures retain the claim and evidence for inspection. The generated SDK files under `zova/src/**` remain shared checkout output, so serialize concurrent generation for the same workspace/module and do not treat this command as an automatic rollback boundary.
+
 For Vona integrated SSR, the allocated E2E origin is supplied to Zova at runtime as server `SSR_API_BASE_URL` and browser `API_BASE_URL`. Do not edit Zova `.env` files or rebuild solely to match the test port. The current root `npm run test:e2e` consumes prebuilt frontend artifacts; refresh affected SSR/REST output and synchronize dependencies when their inputs change. See [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr) for configuration overrides and scope.
 
 For deliberate **dev-mode** database preparation, `npm run db:reset` is a separate, destructive command: in a single process, it clears validated application-owned Redis keys, drops and recreates managed disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` and `npm run dev:one` only reuse existing managed databases; if any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`. They do not create databases, perform creation-time Redis cleanup, or seed. Never run `db:reset` against development data you need to retain. Upgrades do not reset existing development data or repeat its seeds. See [Development database preparation](#development-database-preparation) and [Migration and Changes](/backend/migration-and-changes#local-development-workflow).

package/scripts/bootstrapAgentGovernance.mjs

@@ -35,6 +35,24 @@ function reconcileGovernancePackageJson(sourceRoot) {
     projectPackage.scripts[name] = command;
     changed = true;
   }
+  // An older upgrader is already running when it installs this bootstrap, so adopt
+  // the new root command here too without replacing project-owned customizations.
+  const contractScriptName = 'contract:generate:isolated';
+  const contractCommand = sourcePackage.scripts?.[contractScriptName];
+  if (contractCommand) {
+    if (!Object.hasOwn(projectPackage.scripts ?? {}, contractScriptName)) {
+      projectPackage.scripts ??= {};
+      projectPackage.scripts[contractScriptName] = contractCommand;
+      changed = true;
+      // eslint-disable-next-line no-console
+      console.log(`[init] Added missing package.json scripts.${contractScriptName}`);
+    } else if (projectPackage.scripts[contractScriptName] !== contractCommand) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[init] Preserved customized package.json scripts.${contractScriptName}; incoming command: ${contractCommand}`,
+      );
+    }
+  }
   if (changed) {
     writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
     // eslint-disable-next-line no-console

package/scripts/generateOpenapiIsolated.test.ts

@@ -0,0 +1,207 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { createServer } from 'node:http';
+import { test } from 'node:test';
+
+import type { GuardianResult, OwnedProcess } from './runIsolatedTest.ts';
+
+import {
+  getOpenapiGeneratorCommand,
+  getOpenapiSource,
+  validateOpenapiSource,
+} from './generateOpenapiIsolated.ts';
+import { getIsolatedVonaCommand, ROOT_DIR, withIsolatedVona } from './runIsolatedTest.ts';
+
+test('builds the isolated Swagger source from the allocated port', () => {
+  assert.equal(getOpenapiSource(7123), 'http://127.0.0.1:7123/swagger/json?version=V31');
+});
+
+test('forwards OpenAPI module arguments to the existing Zova generator', () => {
+  assert.deepEqual(getOpenapiGeneratorCommand(['training-student', '--nometadata']), {
+    command: process.execPath,
+    args: [
+      './zova/packages-cli/cli/src/bin/zova.ts',
+      '--projectPath=zova',
+      ':openapi:generate',
+      'training-student',
+      '--nometadata',
+    ],
+    cwd: ROOT_DIR,
+  });
+});
+
+test('rejects project overrides before provisioning isolated resources', () => {
+  for (const args of [['--projectPath=other'], ['--projectPath', 'other']]) {
+    assert.throws(() => getOpenapiGeneratorCommand(args), /projectPath overrides are unsupported/);
+  }
+});
+
+test('launches only a loopback single-worker test-mode Vona service', () => {
+  const command = getIsolatedVonaCommand(7123, { CUSTOM: 'keep' }, 'test-key');
+  assert.equal(command.command, process.execPath);
+  assert.deepEqual(command.args, [
+    './packages-cli/cli/src/bin/vona.ts',
+    ':bin:dev',
+    '--workers=1',
+    '--flavor=normal',
+    '--mode=test',
+  ]);
+  assert.equal(command.cwd, `${ROOT_DIR}/vona`);
+  assert.deepEqual(command.env, {
+    CUSTOM: 'keep',
+    VONA_TEST_READY_KEY: 'test-key',
+    VONA_TEST_SERVER_ORIGIN: 'true',
+    SERVER_SERVE_PROTOCOL: 'http',
+    SERVER_SERVE_HOST: '127.0.0.1:7123',
+  });
+});
+
+function lifecycleFixture(options: { readyFailure?: boolean; stopFailure?: boolean } = {}) {
+  const events: string[] = [];
+  let finish!: (result: GuardianResult) => void;
+  const closed = new Promise<GuardianResult>(resolve => {
+    finish = resolve;
+  });
+  const result: GuardianResult = {
+    type: 'drained',
+    failed: false,
+    result: { code: 0, signal: null },
+  };
+  const server: OwnedProcess = {
+    wait: () => closed,
+    stop: async () => {
+      events.push('stop');
+      if (options.stopFailure) throw new Error('shutdown failed');
+      finish(result);
+      return result;
+    },
+  };
+  return {
+    events,
+    finish,
+    result,
+    dependencies: {
+      start: async () => {
+        events.push('start');
+        return server;
+      },
+      ready: async () => {
+        events.push('ready');
+        if (options.readyFailure) throw new Error('readiness failed');
+      },
+    },
+  };
+}
+
+test('stops Vona after generation succeeds or fails and removes signal handlers', async () => {
+  for (const fail of [false, true]) {
+    const f = lifecycleFixture();
+    const listeners = process.listenerCount('SIGINT');
+    const run = withIsolatedVona(
+      7123,
+      {},
+      async () => {
+        f.events.push('generate');
+        if (fail) throw new Error('generator failed');
+        return 'generated';
+      },
+      f.dependencies,
+    );
+    if (fail) await assert.rejects(run, /generator failed/);
+    else assert.equal(await run, 'generated');
+    assert.deepEqual(f.events, ['start', 'ready', 'generate', 'stop']);
+    assert.equal(process.listenerCount('SIGINT'), listeners);
+  }
+});
+
+test('readiness failure stops Vona without invoking the generator', async () => {
+  const f = lifecycleFixture({ readyFailure: true });
+  await assert.rejects(
+    withIsolatedVona(
+      7123,
+      {},
+      async () => {
+        f.events.push('generate');
+      },
+      f.dependencies,
+    ),
+    /readiness failed/,
+  );
+  assert.deepEqual(f.events, ['start', 'ready', 'stop']);
+});
+
+test('preserves both generation and shutdown errors', async () => {
+  const f = lifecycleFixture({ stopFailure: true });
+  await assert.rejects(
+    withIsolatedVona(
+      7123,
+      {},
+      async () => {
+        throw new Error('generator failed');
+      },
+      f.dependencies,
+    ),
+    (error: unknown) => {
+      assert.ok(error instanceof AggregateError);
+      assert.deepEqual(
+        error.errors.map(item => item.message),
+        ['generator failed', 'shutdown failed'],
+      );
+      return true;
+    },
+  );
+});
+
+test('an interrupted run or an early server exit cannot succeed', async () => {
+  for (const interrupt of [false, true]) {
+    const f = lifecycleFixture();
+    await assert.rejects(
+      withIsolatedVona(
+        7123,
+        {},
+        async () => {
+          if (interrupt) {
+            process.emit('SIGINT');
+          } else {
+            f.finish(f.result);
+            await Promise.resolve();
+          }
+        },
+        f.dependencies,
+      ),
+      /exited early, or run was interrupted/,
+    );
+  }
+});
+
+test('preflight distinguishes HTTP, JSON and OpenAPI shape failures', async () => {
+  let status = 200;
+  let body = JSON.stringify({ openapi: '3.1.0', info: {}, paths: {} });
+  const server = createServer((_req, res) => {
+    res.writeHead(status, status === 302 ? { location: '/redirect-target' } : {});
+    res.end(body);
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+  const source = getOpenapiSource(address.port);
+  try {
+    await validateOpenapiSource(source);
+    status = 302;
+    await assert.rejects(validateOpenapiSource(source), /source request failed/);
+    status = 503;
+    await assert.rejects(validateOpenapiSource(source), /HTTP 503/);
+    status = 200;
+    body = 'not-json';
+    await assert.rejects(validateOpenapiSource(source), /invalid JSON/);
+    for (const value of [null, [], {}, { openapi: '3.1.0', paths: [] }]) {
+      body = JSON.stringify(value);
+      await assert.rejects(validateOpenapiSource(source), /invalid document/);
+    }
+  } finally {
+    await new Promise<void>((resolve, reject) =>
+      server.close(error => (error ? reject(error) : resolve())),
+    );
+  }
+});