create-ailk 0.2.0 → 0.3.0

package/dist/lib/extract-module-bundle.js

@@ -28,23 +28,180 @@
  * `extractModuleBundle` therefore extracts into a throwaway temp dir first
  * (same validation, same guards), and ONLY on full success copies each
  * validated file into its place under `targetDir` — so a rejected or
- * partially-decompressed bundle never touches the scaffold at all.
+ * partially-decompressed bundle never touches the scaffold at all. This
+ * guarantee extends all the way through `patches` (below): NOTHING is
+ * written to `targetDir` — not the bundle's own plain content, not an
+ * `installMap` destination, not a patched file — until every patch target
+ * has been computed successfully in memory.
+ *
+ * `installMap` / `postInstall` (spec 5373 § D7): a bundle may carry an
+ * `ailk-module.json` at its root, `{name, version, installMap, postInstall}`.
+ * `installMap` remaps specific staged files to a different scaffold
+ * destination (e.g. the docs-blog `llms-route.ts` landing on
+ * `app/llms.txt/route.ts`) — every source must be a file the validated
+ * extraction produced in staging (an absolute path, a `..` segment, or a
+ * path absent from staging rejects the WHOLE bundle, nothing copied), and
+ * every destination gets the same fail-closed containment check as a tar
+ * entry. A mapped source is copied to its destination only, never also to
+ * its original path. `postInstall` is printed to stdout after a successful
+ * merge, with C0/C1 control characters (other than newline) stripped first
+ * so a bundle cannot inject terminal escape sequences. `ailk-module.json`
+ * itself is never copied into the scaffold.
+ *
+ * `patches` (spec 5418 § 3 D1-D6): a sibling manifest field naming
+ * declarative edits to files the buyer's scaffold already has (or that this
+ * SAME bundle is about to deliver — see below). Validated at the same
+ * fail-closed point as `installMap` (D6), then COMPUTED — every patch
+ * target's new content resolved in memory, throwing on the first conflict /
+ * missing-target / unparseable-target failure (D4) — before `copyTree` or
+ * the `installMap` copy loop runs at all. A patch target the bundle itself
+ * delivers (as plain content or as an `installMap` destination) is read
+ * from the STAGED tree for this computation, since `targetDir` would not
+ * have it yet; every other target is read from the already-scaffolded
+ * `targetDir` file. Only once every target computes successfully does
+ * `copyTree`/`installMap` run, followed by one write pass for the computed
+ * patches — so a patch failure leaves `targetDir` exactly as it was before
+ * this call, including files THIS bundle would otherwise have added.
  */
-import { copyFileSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { copyFileSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import * as tar from "tar";
+import { computeModulePatches, writeModulePatches } from "./apply-module-patches.js";
 /** Soft limits to prevent decompression-bomb / zip-bomb attacks. Same values as extractBundle. */
 const MAX_ENTRIES = 1000;
 const MAX_TOTAL_SIZE_BYTES = 50 * 1024 * 1024; // 50 MiB
+/** The bundle-root manifest file (spec § D7). Never copied into the scaffold. */
+const AILK_MODULE_JSON = "ailk-module.json";
+/** The op names valid for each patch `kind` (spec 5418 § 3 D1's ModulePatchOp union, partitioned). */
+const VALID_OPS_BY_KIND = {
+    json: new Set(["merge-keys", "append-unique"]),
+    "next-config": new Set(["add-transpile-package", "wrap-export-with"]),
+    "jest-config": new Set([
+        "add-module-name-mapper",
+        "add-transform-ignore-pattern",
+        "add-transform",
+    ]),
+};
+/** True iff `child` is the same path as `parent` or a descendant of it. */
+function isPathInside(parent, child) {
+    const rel = relative(parent, child);
+    if (rel === "")
+        return true;
+    if (rel.startsWith(".."))
+        return false;
+    if (isAbsolute(rel))
+        return false;
+    return true;
+}
+/**
+ * Reject an absolute path or any `..` segment — the same shape check
+ * `safeExtractTarGz` applies to tar entries, reused here for `installMap`
+ * keys/values, which come from bundle-controlled JSON rather than tar
+ * entries and so need the same fail-closed treatment.
+ */
+function hasUnsafeSegment(p) {
+    if (isAbsolute(p))
+        return true;
+    const normalized = normalize(p);
+    return (normalized === ".." ||
+        normalized.startsWith(`..${sep}`) ||
+        normalized.split(sep).includes(".."));
+}
+/**
+ * Read `ailk-module.json` from the validated staging tree, if present.
+ * Malformed JSON is treated as absent — the manifest is written by the
+ * producer (D7), never hand-authored, so a parse failure is a producer bug,
+ * not a security boundary to fail closed on with a rejected install.
+ */
+function readAilkModuleManifest(extractedRoot) {
+    const manifestPath = join(extractedRoot, AILK_MODULE_JSON);
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate every `installMap` entry against the staged tree and the target
+ * scaffold, throwing on the first violation — called BEFORE any copy, so a
+ * bad entry rejects the whole bundle with nothing written to `targetDir`.
+ * Returns the map unchanged (validation only) for the caller to apply.
+ */
+function validateInstallMap(installMap, extractedRoot, targetAbs, moduleName) {
+    for (const [source, destination] of Object.entries(installMap)) {
+        if (hasUnsafeSegment(source)) {
+            throw new Error(`module "${moduleName}": unsafe installMap source "${source}"`);
+        }
+        const sourceAbs = resolve(extractedRoot, source);
+        if (!isPathInside(extractedRoot, sourceAbs)) {
+            throw new Error(`module "${moduleName}": installMap source "${source}" resolves outside staging`);
+        }
+        let sourceStat;
+        try {
+            sourceStat = statSync(sourceAbs);
+        }
+        catch {
+            throw new Error(`module "${moduleName}": installMap source "${source}" is not a file the bundle produced`);
+        }
+        if (!sourceStat.isFile()) {
+            throw new Error(`module "${moduleName}": installMap source "${source}" is not a file the bundle produced`);
+        }
+        if (hasUnsafeSegment(destination)) {
+            throw new Error(`module "${moduleName}": unsafe installMap destination "${destination}"`);
+        }
+        const destAbs = resolve(targetAbs, destination);
+        if (!isPathInside(targetAbs, destAbs)) {
+            throw new Error(`module "${moduleName}": installMap destination "${destination}" resolves outside target`);
+        }
+    }
+}
+/**
+ * Validate every `patches` entry against `targetDir` — the same fail-closed
+ * point and containment guard `validateInstallMap` above uses, extended
+ * (spec 5418 § 3 D6): `target` must resolve inside `targetDir`; `kind` and
+ * every `op.op` must be a recognized vocabulary member. Any violation
+ * refuses the WHOLE bundle before `copyTree` runs — this is D4 class 4
+ * (unknown kind/op), resolved here at validation time, never inside
+ * `applyModulePatches` (which never sees an invalid kind/op).
+ */
+function validatePatches(patches, targetAbs, moduleName) {
+    for (const patch of patches) {
+        if (hasUnsafeSegment(patch.target)) {
+            throw new Error(`module "${moduleName}": unsafe patch target "${patch.target}"`);
+        }
+        const targetAbsPath = resolve(targetAbs, patch.target);
+        if (!isPathInside(targetAbs, targetAbsPath)) {
+            throw new Error(`module "${moduleName}": patch target "${patch.target}" resolves outside target`);
+        }
+        const validOps = VALID_OPS_BY_KIND[patch.kind];
+        if (!validOps) {
+            throw new Error(`invalid module manifest: unknown patch kind "${patch.kind}" for target ${patch.target}`);
+        }
+        for (const op of patch.ops) {
+            if (!validOps.has(op.op)) {
+                throw new Error(`invalid module manifest: unknown patch op "${op.op}" for target ${patch.target}`);
+            }
+        }
+    }
+}
+/** C0 (0x00-0x1F) and C1 (0x7F-0x9F) control characters, newline excepted. */
+function stripControlCharacters(text) {
+    // eslint-disable-next-line no-control-regex -- deliberately stripping control chars
+    return text.replace(/[\x00-\x09\x0B-\x1F\x7F-\x9F]/g, "");
+}
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
  * the tree `copyTemplate` already wrote. Throws on any unsafe entry,
- * decompress error, or limit overrun — `targetDir` is left untouched on
- * failure (validation completes in a throwaway staging dir before any file
- * is copied into place).
+ * decompress error, limit overrun, invalid `installMap`, or `patches`
+ * failure (D4) — `targetDir` is left untouched on failure in every one of
+ * those cases: validation AND patch computation both complete before any
+ * file is copied or written into place.
  */
 export async function extractModuleBundle(options) {
     const { bytes, targetDir, moduleName } = options;
@@ -59,10 +216,71 @@ export async function extractModuleBundle(options) {
         const extractedRoot = join(stagingDir, "extracted");
         mkdirSync(extractedRoot, { recursive: true });
         await safeExtractTarGz(stagingTar, extractedRoot, moduleName);
-        // Full validation passed — merge into targetDir. Copies only (never
-        // deletes anything): a fetched module's files ADD to the free scaffold,
-        // they never remove what the free copy already wrote.
-        copyTree(extractedRoot, targetAbs);
+        // installMap validation runs BEFORE any copy, so a bad entry rejects the
+        // whole bundle with nothing written to targetDir (same posture as the
+        // tar-entry validation above).
+        const manifest = readAilkModuleManifest(extractedRoot);
+        const installMap = manifest?.installMap ?? {};
+        validateInstallMap(installMap, extractedRoot, targetAbs, moduleName);
+        // patches validation (spec 5418 § 3 D6) runs at the same point, before
+        // any copy — a bad target/kind/op rejects the whole bundle with nothing
+        // written to targetDir, same posture as installMap and the tar-entry
+        // validation above.
+        const patches = manifest?.patches ?? [];
+        validatePatches(patches, targetAbs, moduleName);
+        // Compute every patch target's new content BEFORE any write to
+        // targetDir — including before copyTree/installMap below, not only
+        // before the patch step's own write (spec 5418 § 3 D4/§ 6.2): a
+        // conflict, missing-target, or unparseable-target failure must leave
+        // the scaffold exactly as it was, which includes the bundle's own
+        // plain content and installMap destinations never landing either. A
+        // patch target the bundle itself delivers (as plain content or as an
+        // installMap destination) is read from the STAGED tree here, since
+        // targetDir would not have it yet at this point.
+        const installMapDestinationToSource = new Map(Object.entries(installMap).map(([source, destination]) => [destination, source]));
+        const readPatchTarget = (target) => {
+            const mappedSource = installMapDestinationToSource.get(target);
+            if (mappedSource !== undefined) {
+                const sourceAbs = resolve(extractedRoot, mappedSource);
+                return existsSync(sourceAbs) ? readFileSync(sourceAbs, "utf8") : undefined;
+            }
+            const stagedAbs = resolve(extractedRoot, target);
+            if (existsSync(stagedAbs) && statSync(stagedAbs).isFile()) {
+                return readFileSync(stagedAbs, "utf8");
+            }
+            const targetAbsPath = resolve(targetAbs, target);
+            return existsSync(targetAbsPath) ? readFileSync(targetAbsPath, "utf8") : undefined;
+        };
+        const computedPatches = computeModulePatches(patches, {
+            versions: options.versions ?? {},
+            readTarget: readPatchTarget,
+        });
+        // Full validation AND patch computation passed — only now does anything
+        // get written to targetDir. Copies only (never deletes anything): a
+        // fetched module's files ADD to the free scaffold, they never remove
+        // what the free copy already wrote. ailk-module.json and every
+        // installMap source are excluded from the whole-tree copy — the
+        // manifest never lands in the scaffold, and a mapped source lands ONLY
+        // at its mapped destination, never also at its original path.
+        const excluded = new Set([
+            AILK_MODULE_JSON,
+            ...Object.keys(installMap),
+        ]);
+        copyTree(extractedRoot, targetAbs, excluded);
+        for (const [source, destination] of Object.entries(installMap)) {
+            const destAbs = resolve(targetAbs, destination);
+            mkdirSync(join(destAbs, ".."), { recursive: true });
+            copyFileSync(resolve(extractedRoot, source), destAbs);
+        }
+        // patches write AFTER every file the bundle brought is in place (D5) —
+        // after installMap, before postInstall — so a patch can never race a
+        // file its own ownedFiles/installMap just delivered, and (since it was
+        // COMPUTED above, before either ran) overwrites rather than conflicts
+        // with content copyTree/installMap just placed at the same path.
+        writeModulePatches(computedPatches, targetAbs);
+        if (manifest?.postInstall) {
+            process.stdout.write(`${stripControlCharacters(manifest.postInstall)}\n`);
+        }
     }
     finally {
         rmSync(stagingDir, { recursive: true, force: true });
@@ -70,11 +288,14 @@ export async function extractModuleBundle(options) {
 }
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
- * directories as needed. Runs ONLY after `safeExtractTarGz` has validated
- * every entry, so no additional path-safety check is needed here — `srcRoot`
- * is our own staging tree, not attacker-controlled input.
+ * directories as needed, except any path in `excluded` (relative to
+ * `srcRoot`, POSIX-normalized) — the bundle manifest and any `installMap`
+ * source, which land only at their mapped destination. Runs ONLY after
+ * `safeExtractTarGz` has validated every entry, so no additional
+ * path-safety check is needed here — `srcRoot` is our own staging tree, not
+ * attacker-controlled input.
  */
-function copyTree(srcRoot, destRoot) {
+function copyTree(srcRoot, destRoot, excluded = new Set()) {
     const stack = [srcRoot];
     while (stack.length > 0) {
         const dir = stack.pop();
@@ -89,6 +310,8 @@ function copyTree(srcRoot, destRoot) {
                 stack.push(srcPath);
             }
             else if (entry.isFile()) {
+                if (excluded.has(rel.split(sep).join("/")))
+                    continue;
                 mkdirSync(join(destPath, ".."), { recursive: true });
                 copyFileSync(srcPath, destPath);
             }
@@ -171,14 +394,3 @@ async function safeExtractTarGz(tarGzPath, targetDir, moduleName) {
         throw captured.error;
     }
 }
-/** True iff `child` is the same path as `parent` or a descendant of it. */
-function isPathInside(parent, child) {
-    const rel = relative(parent, child);
-    if (rel === "")
-        return true;
-    if (rel.startsWith(".."))
-        return false;
-    if (isAbsolute(rel))
-        return false;
-    return true;
-}

package/dist/lib/fetch-module.d.ts

@@ -1,47 +1,12 @@
-/**
- * Authenticated paid-module-bundle fetch (K1, #5089 — Flavor 3).
- *
- * Posture lifted verbatim from `packages/cli/src/lib/fetch-bundle.ts`
- * (`fetchBundle`, the skill-registry twin of this function):
- *   - Bearer-JWT auth on every request.
- *   - `redirect: "error"` so a maliciously redirected response can't drop us
- *     onto an unintended host — the CLI must hit the configured module
- *     distribution only.
- *   - Empty-token guard before any network call (defense in depth — the
- *     caller should already have gated on an empty/absent key).
- *   - Status-code mapping: 401 → license invalid/revoked/lapsed, 404 →
- *     module content not yet available, other 4xx/5xx → upstream body.
- *
- * Deliberately DOES NOT depend on `@working-theory/license` or
- * `@working-theory/cli` — both are `publishConfig.access: "restricted"` and
- * `create-ailk` is the one package in this monorepo published to PUBLIC npm
- * (Apache-2.0, A1 disposed it `oss`). A runtime dependency on a restricted
- * package would break `pnpm install` for every free-tier consumer, not just
- * gate the paid modules — so this file re-states fetchBundle's POSTURE
- * rather than importing it. Named in the K1 PR body as the public-package
- * boundary this card had to draw.
- *
- * Also deliberately skips fetchBundle's caller-side `checkLicense()` local
- * JWT pre-check (install-skill.ts's step 2): that local verification lives
- * in `@working-theory/license`, which for the same publish-boundary reason
- * above cannot be a runtime dependency here. Instead the module distribution
- * endpoint's own 401 response IS the license verdict — exactly the signal
- * `fetchBundle` already surfaces via `isLicenseError`. This trades one local,
- * no-network check for one authoritative, server-verified one; the caller-
- * visible contract (present-but-invalid key ⟹ the honest "does not cover
- * this" message) is unchanged.
- *
- * Returns the response body bytes on 200; throws a descriptive
- * `FetchModuleError` on any failure path so the caller can map to an honest
- * exit uniformly.
- */
 export declare const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
 export interface FetchModuleOptions {
     moduleName: string;
     /** JWT used as `Authorization: Bearer <token>`. Must be non-empty. */
     token: string;
-    /** Registry root; the module name is appended as a single path segment. */
+    /** Registry root; `<name>/<version>` is appended as two path segments. */
     registryUrl?: string;
+    /** The module version to request. Defaults to this package's own version. */
+    version?: string;
     /** Override for tests; defaults to `globalThis.fetch`. Never a live call in CI. */
     fetchImpl?: typeof fetch;
 }

package/dist/lib/fetch-module.js

@@ -35,7 +35,20 @@
  * `FetchModuleError` on any failure path so the caller can map to an honest
  * exit uniformly.
  */
+import pkg from "../../package.json" with { type: "json" };
 export const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
+/**
+ * This package's own `package.json` `"version"`. Deliberately a static JSON
+ * import (`resolveJsonModule`), not `import.meta.url` + `fileURLToPath` (the
+ * technique `cli.ts:56-58`'s `readPackageVersion` uses) — `fetch-module.ts`
+ * is loaded directly by `fetch-module.test.ts`, and `import.meta` is a
+ * SyntaxError under ts-jest's CommonJS transform (the same reason
+ * `module-architecture.ts`'s `paidModuleTemplateExclusions` doc gives for
+ * avoiding it in any jest-reachable file). A bundle overlays the scaffold
+ * `create-ailk` just copied from its own `templates/`, so the default
+ * version request must be the running package's own.
+ */
+const CREATE_AILK_VERSION = pkg.version;
 export class FetchModuleError extends Error {
     isLicenseError;
     constructor(message, 
@@ -47,25 +60,26 @@ export class FetchModuleError extends Error {
     }
 }
 /**
- * Build the fetch URL by joining `registryUrl` with `moduleName` as a single
- * trailing path segment. `encodeURIComponent` on the module name is defense
- * in depth — `parse-args.ts`'s `parseModules` already restricts the value to
- * `RECOGNIZED_MODULES`, but a hostile value can never smuggle a path
- * separator or query string here regardless.
+ * Build the fetch URL by joining `registryUrl` with `moduleName` and
+ * `version` as two trailing path segments. `encodeURIComponent` on each is
+ * defense in depth — `parse-args.ts`'s `parseModules` already restricts
+ * `moduleName` to `RECOGNIZED_MODULES`, but a hostile value can never smuggle
+ * a path separator or query string here regardless.
  */
-function buildUrl(registryUrl, moduleName) {
+function buildUrl(registryUrl, moduleName, version) {
     const trimmed = registryUrl.replace(/\/+$/, "");
-    return `${trimmed}/${encodeURIComponent(moduleName)}`;
+    return `${trimmed}/${encodeURIComponent(moduleName)}/${encodeURIComponent(version)}`;
 }
 export async function fetchModule(options) {
     const { moduleName, token } = options;
     if (token.length === 0) {
         throw new FetchModuleError("internal error: fetchModule called without a token");
     }
+    const version = options.version ?? CREATE_AILK_VERSION;
     const registryUrl = options.registryUrl ??
         process.env["AILK_MODULE_REGISTRY_URL"] ??
         DEFAULT_AILK_MODULE_REGISTRY_URL;
-    const url = buildUrl(registryUrl, moduleName);
+    const url = buildUrl(registryUrl, moduleName, version);
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     let response;
     try {
@@ -86,6 +100,10 @@ export async function fetchModule(options) {
         throw new FetchModuleError(`your licence does not cover the "${moduleName}" module (invalid, revoked, or lapsed)`, 
         /* isLicenseError */ true);
     }
+    if (response.status === 403) {
+        throw new FetchModuleError(`your licence does not include the "${moduleName}" module, or its term ended before create-ailk ${version} was released — use a create-ailk version released during your term`, 
+        /* isLicenseError */ true);
+    }
     if (response.status === 404) {
         throw new FetchModuleError(`"${moduleName}" module content not yet available — ping us at hello@ailaunchkit.ai`);
     }

package/dist/lib/module-license-gate.d.ts

@@ -35,6 +35,8 @@ export interface ResolvePaidModulesOptions {
     licenseKey?: string | undefined;
     /** Forwarded to `fetchModule`; defaults to `AILK_MODULE_REGISTRY_URL` / the built-in default. */
     registryUrl?: string;
+    /** Forwarded to `fetchModule`; defaults to this package's own version. */
+    version?: string;
     /** Forwarded to `fetchModule`; defaults to `globalThis.fetch`. Never a live call in tests. */
     fetchImpl?: typeof fetch;
 }

package/dist/lib/module-license-gate.js

@@ -39,6 +39,7 @@ export async function resolvePaidModules(options) {
                 ...(options.registryUrl !== undefined
                     ? { registryUrl: options.registryUrl }
                     : {}),
+                ...(options.version !== undefined ? { version: options.version } : {}),
                 ...(options.fetchImpl !== undefined
                     ? { fetchImpl: options.fetchImpl }
                     : {}),

package/dist/lib/paid-paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The derived set of scaffold-relative paths a keyless scaffold must not
+ * contain — sorted, deduped.
+ *
+ * Throws if the result is empty: `PAID_MODULES` is never empty (it is
+ * `RECOGNIZED_MODULES` minus `FREE_MODULES`) and every paid module registered
+ * today owns at least one file under `apps/` or a whole app, so an empty
+ * result means the derivation itself broke — not that there is nothing to
+ * check (DEF-007: a silent `[]` must fail loudly, not pass the gate).
+ */
+export declare function derivePaidScaffoldPaths(): string[];
+/**
+ * Every derived paid path that exists under `scaffoldDir` — the leaked set,
+ * sorted. Empty means the scaffold is clean.
+ */
+export declare function findLeakedPaidPaths(scaffoldDir: string): string[];

package/dist/lib/paid-paths.js

@@ -0,0 +1,90 @@
+/**
+ * Derived paid-path list (R2-5374 — the no-paid-code CI gate, D-44).
+ *
+ * The set of scaffold-relative paths a keyless (Free) `create-ailk` scaffold
+ * must never contain, computed from `MODULE_SLICES` / `PAID_MODULES` at call
+ * time — never hand-maintained, so it grows automatically once commerce
+ * (D-47) and signal-collectors (D-48) gain their own `MODULE_SLICES` entries.
+ *
+ * Only two of `ModuleSlice`'s shapes name a path that can actually appear in a
+ * scaffold's own output tree (`build-templates.mjs`'s `SNAPSHOT_DIRS` is
+ * `["apps", "database"]` — see its own header comment; `packages/*` is never
+ * copied into a scaffold, it is consumed as an npm dependency):
+ *
+ *   - `ownedFiles` entries that already sit under `apps/` — the scaffold
+ *     copies that tree verbatim, so the path is identical on both sides.
+ *   - `apps[name].path` — a paid module's OWN app directory. Multi-tenant's
+ *     `workspace` app has been extracted out of this repo's own `apps/` tree
+ *     into a sibling paid-apps root (its `ownedFiles` entry is a
+ *     whole-directory glob naming that monorepo-internal location, not a
+ *     scaffold one), so the app it introduces into a SCAFFOLD is named here
+ *     instead, via the slice's own declared path. `api` / `mcp` / `web` are
+ *     excluded: they are base apps present in
+ *     EVERY scaffold regardless of licence — a module only ever grants
+ *     import permissions into them, never introduces the directory, and the
+ *     paid FILES inside them are already covered by the `ownedFiles` branch
+ *     above.
+ *
+ * `ownedFiles` entries under `packages/` are excluded for the reason above.
+ * `namespaces` (database/*) are excluded too: each slice's own doc comment
+ * (see multi-tenant's in `module-architecture.ts`) records that a namespace
+ * directory mixes base and paid Prisma models in one `schema.prisma` file, so
+ * the DIRECTORY itself is not paid-owned even though some models inside it
+ * are — asserting it absent would be wrong on every scaffold, paid or free.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { MODULE_SLICES } from "../module-architecture.js";
+import { PAID_MODULES } from "./module-tier.js";
+/** Base app paths present in every scaffold regardless of the selected modules. */
+const BASE_APP_PATHS = new Set([
+    "apps/web",
+    "apps/api",
+    "apps/mcp",
+]);
+/** A slice's `ownedFiles` entries that live under `apps/` — copied verbatim into a scaffold. */
+function ownedFilesUnderApps(slice) {
+    return (slice.ownedFiles ?? [])
+        .filter((entry) => entry.startsWith("apps/"))
+        .map((entry) => entry.endsWith("/**") ? entry.slice(0, -"/**".length) : entry);
+}
+/** A slice's own app directories, excluding the base apps every scaffold ships. */
+function introducedAppPaths(slice) {
+    return Object.values(slice.apps ?? {})
+        .map((app) => app.path)
+        .filter((path) => !BASE_APP_PATHS.has(path));
+}
+/**
+ * The derived set of scaffold-relative paths a keyless scaffold must not
+ * contain — sorted, deduped.
+ *
+ * Throws if the result is empty: `PAID_MODULES` is never empty (it is
+ * `RECOGNIZED_MODULES` minus `FREE_MODULES`) and every paid module registered
+ * today owns at least one file under `apps/` or a whole app, so an empty
+ * result means the derivation itself broke — not that there is nothing to
+ * check (DEF-007: a silent `[]` must fail loudly, not pass the gate).
+ */
+export function derivePaidScaffoldPaths() {
+    const paths = new Set();
+    for (const moduleName of PAID_MODULES) {
+        const slice = MODULE_SLICES[moduleName];
+        for (const p of ownedFilesUnderApps(slice))
+            paths.add(p);
+        for (const p of introducedAppPaths(slice))
+            paths.add(p);
+    }
+    const sorted = [...paths].sort();
+    if (sorted.length === 0) {
+        throw new Error("derivePaidScaffoldPaths() computed an empty list — MODULE_SLICES and " +
+            "PAID_MODULES have drifted out of sync (DEF-007: this must never " +
+            "silently pass the no-paid-code gate)");
+    }
+    return sorted;
+}
+/**
+ * Every derived paid path that exists under `scaffoldDir` — the leaked set,
+ * sorted. Empty means the scaffold is clean.
+ */
+export function findLeakedPaidPaths(scaffoldDir) {
+    return derivePaidScaffoldPaths().filter((relPath) => existsSync(join(scaffoldDir, relPath)));
+}