@suluk/cockpit 0.1.12 → 0.1.14

package/package.json

@@ -1,36 +1,39 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "The pure cockpit core (cycle model · builder model · codegen · deploy planning · validate/audit/preview) shared by the vscode extension and the /superadmin web admin panel. CANDIDATE tooling.",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
-    "directory": "tooling/ts/packages/cockpit"
-  },
-  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
-  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "dependencies": {
-    "@suluk/core": "0.1.6",
-    "@suluk/hono": "0.1.1",
-    "@suluk/scalar": "0.1.1",
-    "@suluk/swagger": "0.1.1",
-    "@suluk/shadcn": "0.1.1",
-    "@suluk/builder": "0.1.9",
-    "@suluk/deploy": "0.1.1",
-    "@suluk/cost": "0.1.1",
-    "@suluk/visual": "0.1.1"
-  },
-  "devDependencies": {
-    "@types/bun": "latest"
-  },
-  "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit -p ."
-  }
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/cockpit"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+  "@suluk/core": "0.1.6",
+  "@suluk/hono": "0.1.1",
+  "@suluk/scalar": "0.1.1",
+  "@suluk/swagger": "0.1.1",
+  "@suluk/shadcn": "0.1.1",
+  "@suluk/builder": "0.1.9",
+  "@suluk/deploy": "0.1.1",
+  "@suluk/cost": "0.1.1",
+  "@suluk/visual": "0.1.1"
+},
+"devDependencies": {
+  "@types/bun": "latest"
+},
+"scripts": {
+  "test": "bun test",
+  "typecheck": "tsc --noEmit -p ."
+}
 }

package/src/converge.ts

@@ -8,9 +8,9 @@
  */
 import { buildAda } from "@suluk/core";
 import type { OpenAPIv4Document, Request, SchemaOrRef, SecurityRequirement } from "@suluk/core";
-import { schemaRefName } from "@suluk/builder";
+import { schemaRefName, PREVIEW_ONLY_MARKER } from "@suluk/builder";
 
-export type ConvergeCode = "dangling-ref" | "undeclared-scheme" | "orphan-scope" | "empty-path" | "unreferenced-entity";
+export type ConvergeCode = "dangling-ref" | "undeclared-scheme" | "orphan-scope" | "empty-path" | "unreferenced-entity" | "preview-op-exposed";
 
 export interface ConvergeFinding {
   code: ConvergeCode;
@@ -92,5 +92,21 @@ export function convergeContract(doc: OpenAPIv4Document): ConvergeReport {
   // unreferenced entities — a schema nothing $refs (dead weight; info, not an error)
   for (const name of Object.keys(schemas)) if (!referenced.has(name)) findings.push({ code: "unreferenced-entity", severity: "info", message: `entity "${name}" is referenced by no $ref`, where: name });
 
+  // preview-only operations — a `x-suluk-preview-only` op (the /preview/login backdoor) must NEVER silently sit
+  // in a contract that gets deployed to prod. WARN (not error) so its presence is always surfaced: it is only
+  // safe behind the deploy-time SULUK_PREVIEW gate; confirm this projection is a preview, not production. Walk
+  // BOTH path operations AND webhooks — a marker hidden on a webhook is exactly the same backdoor surface.
+  const previewMarked = (req: unknown): boolean => (req as Record<string, unknown> | null | undefined)?.[PREVIEW_ONLY_MARKER] === true;
+  for (const o of buildAda(doc).operations) {
+    if (previewMarked(o.request as unknown)) {
+      findings.push({ code: "preview-op-exposed", severity: "warn", message: `operation "${o.name}" is preview-only (a role-login backdoor) — it must reach prod ONLY behind the SULUK_PREVIEW gate; confirm this is a preview deployment, not production`, where: o.name });
+    }
+  }
+  for (const [name, req] of Object.entries((doc as { webhooks?: Record<string, Request> }).webhooks ?? {})) {
+    if (previewMarked(req as unknown)) {
+      findings.push({ code: "preview-op-exposed", severity: "warn", message: `webhook "${name}" is preview-only (a role-login backdoor) — it must reach prod ONLY behind the SULUK_PREVIEW gate; confirm this is a preview deployment, not production`, where: name });
+    }
+  }
+
   return { findings, clean: !findings.some((f) => f.severity === "error") };
 }

package/src/crosscut.ts

@@ -94,3 +94,64 @@ export function crossCut(doc: OpenAPIv4Document, viewers: Viewer[]): CrossCut {
   }
   return { operations: ops.map((o) => ({ name: o.name, detail: o.detail })), viewers: views, gated };
 }
+
+/** A principal you can preview the running app AS — derived from the contract, never hardcoded. */
+export interface PreviewRole {
+  label: string;
+  /** the role token passed to the preview deploy's /preview/login?role=… (or "anonymous"). */
+  role: string;
+  /** the scopes this role implies in the cross-cut (here, just the role itself; the runtime maps role→scopes). */
+  scopes: string[];
+  authenticated: boolean;
+}
+
+/**
+ * The previewable principals for live role-preview (the LAST roadmap slice): anonymous, then ONE per role the
+ * contract's `User.role` enum declares (the auth module ships ["user","admin","superadmin"]). Pure; degrades
+ * HONESTLY to anonymous-only when there is no User.role enum — never a hardcoded role list. The extension turns
+ * each into a deep-link to the preview deploy's own login; the cockpit never mints or holds a session.
+ */
+// the safe identifier charset a previewable role name must match — it flows into a URL, into seed.sql, AND into
+// the deployed gate's allow-list, so all three agree on exactly this set. Anything else is not previewable.
+const SAFE_ROLE = /^[A-Za-z0-9_-]{1,40}$/;
+
+export function previewRoles(doc: OpenAPIv4Document): PreviewRole[] {
+  const anonymous: PreviewRole = { label: "anonymous", role: "anonymous", scopes: [], authenticated: false };
+  const user = (doc.components?.schemas as Record<string, unknown> | undefined)?.["User"] as
+    | { properties?: { role?: { enum?: unknown } } }
+    | undefined;
+  const raw = user?.properties?.role?.enum;
+  const seen = new Set<string>();
+  const roles = (Array.isArray(raw) ? raw : [])
+    .filter((r): r is string => typeof r === "string" && r.length > 0)
+    // exclude the RESERVED "anonymous" (it is never a mintable session — login-less by definition), apply the safe
+    // charset (URL + SQL + gate safety), and DEDUP — so the previewable set == the seeded set == the gate allow-list.
+    .filter((r) => r !== "anonymous" && SAFE_ROLE.test(r))
+    .filter((r) => (seen.has(r) ? false : (seen.add(r), true)));
+  return [anonymous, ...roles.map((r) => ({ label: r, role: r, scopes: [r], authenticated: true }))];
+}
+
+/**
+ * The roles a preview may be minted AS — the authenticated principals, EXCLUDING the login-less `anonymous`. This
+ * is the ONE source for the deployed gate's allow-list AND for which demo users seed.sql seeds; keeping them equal
+ * means a role can be previewed iff it is seeded iff the gate allows it (no allow-but-unseedable divergence).
+ */
+export function previewAllowedRoles(doc: OpenAPIv4Document): string[] {
+  return previewRoles(doc).filter((r) => r.authenticated).map((r) => r.role);
+}
+
+/**
+ * Resolve the browser deep-link for previewing AS a role — the security-critical guard, made PURE so it is
+ * unit-testable (the extension package has no test harness). Hard-REFUSES any non-preview env BEFORE producing
+ * a URL (INV-08: role-preview can never target prod/local). anonymous ⇒ just the app; a role ⇒ the preview
+ * deploy's own gated /preview/login. The extension calls this, then openExternal — it never builds the URL itself.
+ */
+export function previewLaunchUrl(
+  env: { baseUrl: string; isPreview: boolean },
+  role: string,
+): { refused: true; reason: string } | { refused: false; url: string } {
+  if (!env.isPreview) return { refused: true, reason: "not a preview deployment — role-preview is refused on prod/local" };
+  const base = env.baseUrl.replace(/\/+$/, "");
+  const url = role === "anonymous" ? base : `${base}/preview/login?role=${encodeURIComponent(role)}`;
+  return { refused: false, url };
+}

package/src/deploy.ts

@@ -7,6 +7,7 @@
 import type { OpenAPIv4Document } from "@suluk/core";
 import { cloudflare, type DeployPlan } from "@suluk/deploy";
 import { entitiesFromDoc } from "./builder";
+import { previewAllowedRoles } from "./crosscut";
 
 /** Build the Cloudflare deploy plan from a v4 document (its schemas → entities). */
 export function deployPlan(doc: OpenAPIv4Document): DeployPlan {
@@ -18,6 +19,22 @@ export function deployPlan(doc: OpenAPIv4Document): DeployPlan {
   });
 }
 
+/**
+ * Build the PREVIEW deploy plan (charter-bounded role-preview): a `${slug}-preview` Worker with the two
+ * fail-closed locks + a seed.sql for the contract's roles. Terminal-gated identically to prod — Suluk holds no
+ * infra token; the USER runs wrangler. The seeded roles come from the contract (previewRoles), never hardcoded.
+ */
+export function previewDeployPlan(doc: OpenAPIv4Document): DeployPlan {
+  return cloudflare.generate({
+    name: doc.info?.title ?? "suluk-app",
+    entities: entitiesFromDoc(doc),
+    appModule: "./src/app",
+    assetsDir: "./dist/client",
+    preview: true,
+    previewRoles: previewAllowedRoles(doc), // the seedable, non-anonymous set — equals the gate's allow-list
+  });
+}
+
 /** Render the deploy plan as a DEPLOY.md the user can follow step by step. */
 export function deployMarkdown(plan: DeployPlan): string {
   const steps = plan.steps.map((s, i) => `${i + 1}. \`${s.cmd}\`\n   - ${s.note}`).join("\n");
@@ -42,3 +59,16 @@ ${notes}
 > consequential. The deployment target is swappable: this is the \`cloudflare\` provider.
 `;
 }
+
+/** Render a PREVIEW deploy plan as a PREVIEW-DEPLOY.md — same steps, but headed with the role-preview safety. */
+export function previewDeployMarkdown(plan: DeployPlan): string {
+  const body = deployMarkdown(plan).replace(
+    "# Deploy to Cloudflare — CANDIDATE (generated by Suluk)",
+    "# Deploy a PREVIEW (role-preview) — CANDIDATE (generated by Suluk)\n\n" +
+      "> This is an EPHEMERAL preview deployment. It mounts a `/preview/login?role=…` backdoor that logs you in\n" +
+      "> as a seeded demo user — gated, fail-closed, behind TWO independent locks (the `SULUK_PREVIEW` var AND the\n" +
+      "> `PREVIEW_DB` binding). A production deploy sets neither, so the backdoor is inert there. **Tear the preview\n" +
+      "> down when finished** (`wrangler delete`) — a standing preview is a live credentialed surface.",
+  );
+  return body;
+}

package/src/index.ts

@@ -8,12 +8,12 @@ export { validateSource, auditSource, previewHtml, looksLikeV4, type Diagnostic
 export { buildCycle, docChecks, cycleSummary, type CycleModel, type CycleLayer, type CycleItem, type LayerStatus, type Principal, type DocCheck } from "./cycle";
 export { buildBuilderModel, builderTree, entitiesFromDoc, generateAppFiles, generateRegistryJson, type BuilderModel, type BuilderNode, type GeneratedFile } from "./builder";
 export { entityNames, generateForm, generateTable, generateStoresModule, exportV4Json } from "./codegen";
-export { deployPlan, deployMarkdown } from "./deploy";
+export { deployPlan, deployMarkdown, previewDeployPlan, previewDeployMarkdown } from "./deploy";
 export type { DeployPlan, DeployStep, DeployProvider } from "@suluk/deploy";
 // drift (OBSERVE): compare a LOCAL contract against a DEPLOYED one — the "what's drifted in prod" view (C020).
 export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef, type ProviderDelta, type ProviderChange } from "./drift";
 // cross-cut (M1): one contract refracted through every viewer — the scope-gated surface, the moat.
-export { crossCut, documentScopes, defaultViewers, type Viewer, type ViewerView, type GatedOp, type CrossCut } from "./crosscut";
+export { crossCut, documentScopes, defaultViewers, previewRoles, previewAllowedRoles, previewLaunchUrl, type Viewer, type ViewerView, type GatedOp, type CrossCut, type PreviewRole } from "./crosscut";
 // converge: a coherence audit over a whole contract — the cross-cutting contradictions a clean merge leaves behind.
 export { convergeContract, type ConvergeReport, type ConvergeFinding, type ConvergeCode } from "./converge";
 // diagrams: D2 source for views of the contract (ERD / the declarative cycle / the operation surface) — another projection.
@@ -21,6 +21,8 @@ export { contractToD2, diagramViews, type DiagramView } from "./diagram";
 // component preview + pixel-confidence (surfaces @suluk/visual): decompose generated UI into primitives, check vs a baseline.
 export { componentReport, approveComponents, type ComponentReport } from "./visual";
 export { type Baseline, primitiveCss } from "@suluk/visual";
+// lifecycle / ship-readiness (L3): the round-trip loop as one checklist — authored → coherent → confident → generated → deployed.
+export { contractGates, shipSummary, type Gate, type GateStatus } from "./lifecycle";
 // cost formatting, re-exported so the extension shell can render a live /cost ledger without a direct @suluk/cost dep.
 export { formatMicroUsd, summarize, type CostSummary } from "@suluk/cost";
 // modules (C021): install a contract fragment into the hub doc — the cockpit then re-projects it for free.

package/src/lifecycle.ts

@@ -0,0 +1,94 @@
+/**
+ * Lifecycle / ship-readiness (L3) — the round-trip loop made legible. One contract walks: authored → coherent →
+ * pixel-confident → generated → deployed. contractGates computes the CONTRACT-level gates here (pure: valid /
+ * coherent / confident), each with a status + the cheapest next action; the extension adds the host gates
+ * (generated-in-sync, deployed-in-sync, health) it can only see with fs + network. The whole thing is one
+ * "are you ready to ship?" checklist that aggregates the cockpit's own audits. Pure (no host) → unit-tested.
+ */
+import { validateDocument, buildAda, type OpenAPIv4Document } from "@suluk/core";
+import { convergeContract } from "./converge";
+import { componentReport } from "./visual";
+import type { Baseline } from "@suluk/visual";
+
+// "info" is the non-blocking status: a gate that is honestly n/a (no env configured, no workspace open) — it
+// is shown for transparency but NEVER counts against readiness. Distinct from "warn"/"todo", which DO block.
+export type GateStatus = "ok" | "warn" | "error" | "todo" | "info";
+export interface Gate {
+  id: string;
+  title: string;
+  status: GateStatus;
+  detail: string;
+  /** the command to run to advance this gate (undefined ⇒ nothing to do) */
+  action?: string;
+}
+
+/** The CONTRACT-level ship gates — everything decidable from the document itself (no host needed). */
+export function contractGates(doc: OpenAPIv4Document, baseline: Baseline): Gate[] {
+  const gates: Gate[] = [];
+
+  // 0. non-empty — a contract with zero operations has nothing to ship, however valid/coherent it is in isolation.
+  const ops = buildAda(doc).operations.length;
+  gates.push({
+    id: "operations", title: "Has operations",
+    status: ops ? "ok" : "todo",
+    detail: ops ? `${ops} operation${ops === 1 ? "" : "s"}` : "no operations — nothing to ship",
+  });
+
+  // 1. valid v4
+  const v = validateDocument(doc);
+  gates.push({
+    id: "valid", title: "Valid v4 contract",
+    status: v.valid ? "ok" : "error",
+    detail: v.valid ? "passes the meta-schema" : `${v.errors.length} schema error${v.errors.length === 1 ? "" : "s"}`,
+    action: v.valid ? undefined : "suluk.validate",
+  });
+
+  // 2. coherent (converge)
+  const conv = convergeContract(doc);
+  const errs = conv.findings.filter((f) => f.severity === "error").length;
+  gates.push({
+    id: "coherent", title: "Coherent (no contradictions)",
+    status: errs ? "error" : "ok",
+    detail: errs ? `${errs} contradiction${errs === 1 ? "" : "s"} (dangling ref / orphan scope / …)` : "converges clean",
+    action: errs ? "suluk.convergeContract" : undefined,
+  });
+
+  // 2b. no preview backdoor — a contract carrying an x-suluk-preview-only op (a role-login backdoor) must be
+  // deployed ONLY as a preview, never prod. WARN-status so it counts against ready (shipSummary blocks on warn):
+  // a clean contract reads ready; one with the backdoor reads NOT ready until the user confirms it is a preview.
+  // (Fixes the supply-chain hole where a smuggled preview op was hard-filtered out of the error-only coherent gate.)
+  const previewOps = conv.findings.filter((f) => f.code === "preview-op-exposed");
+  gates.push({
+    id: "noBackdoor", title: "No preview backdoor in prod",
+    status: previewOps.length ? "warn" : "ok",
+    detail: previewOps.length ? `${previewOps.length} preview-only op${previewOps.length === 1 ? "" : "s"} (${previewOps.map((f) => f.where).filter(Boolean).join(", ")}) — deploy ONLY as a preview, never to production` : "no preview-only operations",
+    action: previewOps.length ? "suluk.convergeContract" : undefined,
+  });
+
+  // 3. pixel-confident components
+  const cr = componentReport(doc, baseline);
+  const pending = cr.confidence.missing.length + cr.confidence.drifted.length;
+  gates.push({
+    id: "confident", title: "Components pixel-confident",
+    status: cr.used.length === 0 ? "ok" : pending ? "todo" : "ok",
+    detail: cr.used.length === 0 ? "no generated components" : pending ? `${pending} primitive${pending === 1 ? "" : "s"} to verify once` : "every primitive approved + unchanged",
+    action: pending ? "suluk.previewComponents" : undefined,
+  });
+
+  return gates;
+}
+
+/** A one-line readiness summary over a set of gates (contract + host). "info" gates never count against ready. */
+export function shipSummary(gates: Gate[]): { ready: boolean; line: string } {
+  const errors = gates.filter((g) => g.status === "error").length;
+  const todos = gates.filter((g) => g.status === "todo" || g.status === "warn").length;
+  const ok = gates.filter((g) => g.status === "ok").length;
+  const info = gates.filter((g) => g.status === "info").length;
+  const ready = errors === 0 && todos === 0;
+  return {
+    ready,
+    line: ready
+      ? `ready to ship — ${ok} gate${ok === 1 ? "" : "s"} pass${info ? ` · ${info} n/a` : ""}`
+      : `${errors} blocker${errors === 1 ? "" : "s"} · ${todos} to do · ${ok}/${gates.length} pass`,
+  };
+}

package/test/lifecycle.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import type { Baseline } from "@suluk/visual";
+import { componentReport, approveComponents } from "../src/visual";
+import { contractGates, shipSummary } from "../src/lifecycle";
+
+const good = () => parseDocument(`openapi: 4.0.0-candidate
+info: { title: Shop, version: 1.0.0 }
+paths:
+  "pet":
+    requests:
+      listPets: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Pet" } } } }
+components: { schemas: { Pet: { type: object, properties: { name: { type: string } } } } }`);
+
+const gate = (gates: ReturnType<typeof contractGates>, id: string) => gates.find((g) => g.id === id)!;
+
+describe("contractGates — the contract-level ship gates", () => {
+  test("a valid, coherent contract passes valid + coherent; confidence is 'todo' against an empty baseline", () => {
+    const gates = contractGates(good(), {});
+    expect(gate(gates, "valid").status).toBe("ok");
+    expect(gate(gates, "coherent").status).toBe("ok");
+    expect(gate(gates, "confident").status).toBe("todo"); // never verified
+    expect(gate(gates, "confident").action).toBe("suluk.previewComponents");
+  });
+  test("a contradiction (a dangling $ref) makes the coherent gate an error with a fix action", () => {
+    const broken = parseDocument(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "p": { requests: { g: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Ghost" } } } } } } }
+components: { schemas: {} }`);
+    const g = gate(contractGates(broken, {}), "coherent");
+    expect(g.status).toBe("error");
+    expect(g.action).toBe("suluk.convergeContract");
+  });
+  test("after approving the components, the confidence gate passes", () => {
+    const doc = good();
+    const baseline: Baseline = approveComponents(componentReport(doc, {}), {}, 1);
+    expect(gate(contractGates(doc, baseline), "confident").status).toBe("ok");
+  });
+  test("an empty contract (zero operations) is NOT ship-ready — the operations gate is 'todo'", () => {
+    const empty = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Empty, version: 1.0.0 }
+paths: {}`);
+    const gates = contractGates(empty, {});
+    expect(gate(gates, "operations").status).toBe("todo"); // nothing to ship
+    expect(shipSummary(gates).ready).toBe(false); // even though valid + coherent are clean
+  });
+});
+
+describe("shipSummary", () => {
+  test("all-ok gates ⇒ ready", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "ok", detail: "" }]);
+    expect(r.ready).toBe(true);
+    expect(r.line).toContain("ready to ship");
+  });
+  test("an error gate ⇒ NOT ready, counted as a blocker", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "error", detail: "" }, { id: "c", title: "C", status: "todo", detail: "" }]);
+    expect(r.ready).toBe(false);
+    expect(r.line).toContain("1 blocker");
+    expect(r.line).toContain("1 to do");
+  });
+  test("an 'info' gate is non-blocking — it never makes a clean contract read as not-ready", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "info", detail: "n/a — no environment configured" }]);
+    expect(r.ready).toBe(true);
+    expect(r.line).toContain("ready to ship");
+    expect(r.line).toContain("1 n/a"); // surfaced for transparency, but not counted against ready
+  });
+});

package/test/preview.test.ts

@@ -0,0 +1,135 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { installModule, PREVIEW } from "@suluk/builder";
+import { previewRoles, previewAllowedRoles, previewLaunchUrl } from "../src/crosscut";
+import { convergeContract } from "../src/converge";
+import { contractGates, shipSummary } from "../src/lifecycle";
+import { previewDeployPlan, deployPlan } from "../src/deploy";
+
+const docWithRoles = (): OpenAPIv4Document => ({
+  openapi: "4.0.0-candidate",
+  info: { title: "Shop", version: "1.0.0" },
+  paths: { user: { requests: { listUser: { method: "get", responses: { ok: { status: 200, contentType: "application/json", contentSchema: { $ref: "#/components/schemas/User" } } } } } } },
+  components: { schemas: { User: { type: "object", properties: { id: { type: "integer" }, role: { type: "string", enum: ["user", "admin", "superadmin"] } } } } },
+});
+
+describe("previewRoles — contract-sourced principals (never hardcoded)", () => {
+  test("derives anonymous + one per User.role enum value", () => {
+    const roles = previewRoles(docWithRoles());
+    expect(roles.map((r) => r.role)).toEqual(["anonymous", "user", "admin", "superadmin"]);
+    expect(roles[0]).toMatchObject({ role: "anonymous", authenticated: false });
+    expect(roles[2]).toMatchObject({ role: "admin", authenticated: true, scopes: ["admin"] });
+  });
+  test("degrades HONESTLY to anonymous-only when there is no User.role enum", () => {
+    const noRole: OpenAPIv4Document = { openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {}, components: { schemas: {} } };
+    expect(previewRoles(noRole).map((r) => r.role)).toEqual(["anonymous"]);
+    // and when there's no User at all it does not throw
+    const bare: OpenAPIv4Document = { openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {} };
+    expect(previewRoles(bare).map((r) => r.role)).toEqual(["anonymous"]);
+  });
+  test("a reserved/unsafe/duplicate enum is reconciled — anonymous appears exactly once, unsafe roles dropped", () => {
+    const messy: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {},
+      components: { schemas: { User: { type: "object", properties: { role: { type: "string", enum: ["admin", "anonymous", "admin", "ev:il", "x".repeat(50), 42 as unknown as string] } } } } },
+    };
+    expect(previewRoles(messy).map((r) => r.role)).toEqual(["anonymous", "admin"]); // dedup + reserved + unsafe/long/non-string all dropped
+    expect(previewRoles(messy).filter((r) => r.role === "anonymous")).toHaveLength(1);
+  });
+  test("previewAllowedRoles is the seedable set — authenticated only, NEVER anonymous (the gate's allow-list)", () => {
+    expect(previewAllowedRoles(docWithRoles())).toEqual(["user", "admin", "superadmin"]);
+    expect(previewAllowedRoles(docWithRoles())).not.toContain("anonymous");
+  });
+});
+
+describe("previewLaunchUrl — the preview-only guard + deep-link (INV-08, pure & testable)", () => {
+  test("REFUSES a non-preview env before producing any URL", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://prod.example.com", isPreview: false }, "admin");
+    expect(r.refused).toBe(true);
+    if (r.refused) expect(r.reason).toContain("refused");
+  });
+  test("a preview env + a role ⇒ the deploy's own gated /preview/login, role URL-encoded", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://app-preview.example.com/", isPreview: true }, "super admin");
+    expect(r.refused).toBe(false);
+    if (!r.refused) expect(r.url).toBe("https://app-preview.example.com/preview/login?role=super%20admin");
+  });
+  test("anonymous ⇒ just the app, no login route, no query", () => {
+    const r = previewLaunchUrl({ baseUrl: "https://app-preview.example.com", isPreview: true }, "anonymous");
+    expect(r.refused).toBe(false);
+    if (!r.refused) expect(r.url).toBe("https://app-preview.example.com");
+  });
+});
+
+describe("converge — surfaces the preview-only backdoor (it must never sit silently in a projection)", () => {
+  test("a contract carrying the preview op gets a preview-op-exposed WARN", () => {
+    const installed = installModule(docWithRoles(), PREVIEW);
+    expect(installed.installed).toBe(true);
+    const report = convergeContract(installed.doc);
+    const f = report.findings.find((x) => x.code === "preview-op-exposed");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("warn");
+    expect(f!.where).toBe("previewLogin");
+    expect(report.clean).toBe(true); // a WARN is not an error — it does not fail coherence, only flags
+  });
+  test("a contract WITHOUT the preview op has no such finding", () => {
+    expect(convergeContract(docWithRoles()).findings.some((x) => x.code === "preview-op-exposed")).toBe(false);
+  });
+  test("a marker hidden on a WEBHOOK is ALSO surfaced (no false negative)", () => {
+    const wh: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "X", version: "1.0.0" }, paths: {},
+      webhooks: { sneaky: { method: "post", responses: { ok: { status: 200, description: "x" } }, "x-suluk-preview-only": true } },
+    } as unknown as OpenAPIv4Document;
+    const f = convergeContract(wh).findings.find((x) => x.code === "preview-op-exposed");
+    expect(f).toBeDefined();
+    expect(f!.where).toBe("sneaky");
+  });
+});
+
+describe("ship gate — a contract carrying the backdoor is NOT 'ready to ship' (supply-chain fix)", () => {
+  test("contractGates adds a 'noBackdoor' warn that blocks readiness when a preview op is present", () => {
+    const installed = installModule(docWithRoles(), PREVIEW).doc;
+    const gates = contractGates(installed, {});
+    const g = gates.find((x) => x.id === "noBackdoor")!;
+    expect(g.status).toBe("warn");
+    expect(g.detail).toContain("previewLogin");
+    expect(shipSummary(gates).ready).toBe(false); // the smuggled-backdoor contract can no longer read 'ready'
+  });
+  test("a clean contract has noBackdoor 'ok'", () => {
+    const gates = contractGates(docWithRoles(), {});
+    expect(gates.find((x) => x.id === "noBackdoor")!.status).toBe("ok");
+  });
+});
+
+describe("previewDeployPlan — the two locks + the seed, terminal-gated", () => {
+  const plan = previewDeployPlan(docWithRoles());
+  const wrangler = plan.files.find((f) => f.path === "wrangler.jsonc")!.content;
+  test("names a -preview Worker with BOTH locks: the SULUK_PREVIEW var and a PREVIEW_DB binding", () => {
+    expect(wrangler).toContain("-preview");
+    expect(wrangler).toContain('"SULUK_PREVIEW": "1"');
+    expect(wrangler).toContain('"binding": "PREVIEW_DB"');
+  });
+  test("seeds one throwaway demo user per non-anonymous role", () => {
+    const seed = plan.files.find((f) => f.path === "seed.sql")!.content;
+    expect(seed).toContain("preview-admin");
+    expect(seed).toContain("preview-superadmin");
+    expect(seed).not.toContain("preview-anonymous"); // anonymous is never seeded
+  });
+  test("includes a teardown step (a standing preview is a live credentialed surface)", () => {
+    expect(plan.steps.some((s) => s.cmd.includes("wrangler delete"))).toBe(true);
+  });
+  test("a hostile role enum value never reaches seed.sql (filtered at previewAllowedRoles — no SQL injection)", () => {
+    const evil: OpenAPIv4Document = {
+      openapi: "4.0.0-candidate", info: { title: "Evil", version: "1.0.0" }, paths: {},
+      components: { schemas: { User: { type: "object", properties: { role: { type: "string", enum: ["admin", "x'); DROP TABLE user;--"] } } } } },
+    };
+    const seed = previewDeployPlan(evil).files.find((f) => f.path === "seed.sql")!.content;
+    expect(seed).toContain("preview-admin");          // the safe role is seeded
+    expect(seed).not.toContain("DROP TABLE");          // the hostile role is filtered out upstream, never emitted
+  });
+  test("the PROD plan sets NO preview flag — the backdoor is inert there", () => {
+    const prod = deployPlan(docWithRoles());
+    const prodWrangler = prod.files.find((f) => f.path === "wrangler.jsonc")!.content;
+    expect(prodWrangler).not.toContain("SULUK_PREVIEW");
+    expect(prodWrangler).not.toContain("PREVIEW_DB");
+    expect(prod.files.some((f) => f.path === "seed.sql")).toBe(false);
+  });
+});