create-ailk 0.6.1 → 0.8.0

package/dist/lib/extract-module-bundle.d.ts

@@ -1,3 +1,4 @@
+import { type ModulePatch } from "../module-architecture.js";
 import { type TemplateLayout } from "../site-chrome.js";
 import { type MarkerMap, type WorkspaceVersionMap } from "../substitute.js";
 /** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
@@ -44,6 +45,10 @@ export interface ExtractModuleBundleOptions {
     ownership?: LayerOwnership;
     /** The scaffold's marker map (#6460). See `InstallBundleTreeOptions`. */
     markers?: MarkerMap;
+    /** What to do with a destination that already exists (#6653 D3). See `InstallBundleTreeOptions`. */
+    existingFilePolicy?: ExistingFilePolicy;
+    /** A caller check on the manifest's `patches` (#6653 D3). See `InstallBundleTreeOptions`. */
+    checkPatches?: (patches: readonly ModulePatch[]) => void;
 }
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
@@ -108,8 +113,47 @@ export interface InstallBundleTreeOptions {
      * files; `substituteMarkers` leaves every other `{{KEY}}` alone.
      */
     markers?: MarkerMap;
+    /**
+     * What to do with a destination that already exists (#6653 D3). Default
+     * `"overwrite"` — the scaffold's layer-over-layer behaviour, unchanged.
+     * `"skip-existing"` — the `add-module` merge onto a tree a customer has
+     * lived in: an existing file is never written; when its bytes differ from
+     * what this install would write it is reported `skipped` with the change
+     * the bundle wanted, and when they are equal it is not reported at all.
+     * `patches` are NOT gated by it — they are the one mechanism designed to
+     * edit an existing file, and they are already idempotent.
+     */
+    existingFilePolicy?: ExistingFilePolicy;
+    /**
+     * Run against the manifest's `patches` after they validate and BEFORE any
+     * of them is computed or anything is written (#6653 D3) — a throw rejects
+     * the tree with `targetDir` untouched. `add-module` uses it to hold a
+     * bundle's patches to the plus-config allowlist.
+     */
+    checkPatches?: (patches: readonly ModulePatch[]) => void;
 }
-/** `installBundleTree`'s result — presently only the template-only `layout` knobs. */
+/** See `InstallBundleTreeOptions.existingFilePolicy`. */
+export type ExistingFilePolicy = "overwrite" | "skip-existing";
+/**
+ * One file this install landed, patched, or declined to land (#6653 D3). A
+ * destination whose bytes already equal the install's produces no row.
+ * `change` / `wanted` is a unified diff (`diffTwoStrings`) — for `skipped`,
+ * the exact edit the bundle wanted, so the row is a manual-review item and
+ * never a bare path.
+ */
+export type InstallReportRow = {
+    path: string;
+    action: "written";
+} | {
+    path: string;
+    action: "patched";
+    change: string;
+} | {
+    path: string;
+    action: "skipped";
+    wanted: string;
+};
+/** `installBundleTree`'s result. */
 export interface InstallBundleTreeResult {
     /**
      * The installed template's validated `layout` block (#5612 D1), unresolved
@@ -117,6 +161,8 @@ export interface InstallBundleTreeResult {
      * module install, or a template whose manifest declares no `layout`.
      */
     layout?: TemplateLayout;
+    /** One row per file written, patched or skipped, in install order (#6653 D3). */
+    report: InstallReportRow[];
 }
 /**
  * Apply one resolved manifest's `installMap`, plain content and `patches`
@@ -129,3 +175,12 @@ export interface InstallBundleTreeResult {
  * rejected tree leaves `targetDir` exactly as it was.
  */
 export declare function installBundleTree(options: InstallBundleTreeOptions): InstallBundleTreeResult;
+/**
+ * A unified diff of `before` → `after` for the report (#6653 D3) — the one
+ * helper behind both a `skipped` row's `wanted` and a `patched` row's
+ * `change`. Line-based LCS; the inputs are config and content files, small
+ * enough that the quadratic table is not a concern. `isText` false yields the
+ * binary summary instead, reading each string's length as its byte count
+ * (the caller decodes binary content as latin1).
+ */
+export declare function diffTwoStrings(path: string, before: string, after: string, isText: boolean): string;

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

@@ -100,6 +100,8 @@ const AILK_MODULE_JSON = "ailk-module.json";
  * Never copied into the scaffold either.
  */
 const AILK_TEMPLATE_JSON = "ailk-template.json";
+/** A template's hand-and-generated roster document — never installed (#6658 D7). */
+const TEMPLATE_MANIFEST_MD = "TEMPLATE-MANIFEST.md";
 /** 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"]),
@@ -449,6 +451,12 @@ export async function extractModuleBundle(options) {
             ...(options.ownership !== undefined ? { ownership: options.ownership } : {}),
             ...(options.versions !== undefined ? { versions: options.versions } : {}),
             ...(options.markers !== undefined ? { markers: options.markers } : {}),
+            ...(options.existingFilePolicy !== undefined
+                ? { existingFilePolicy: options.existingFilePolicy }
+                : {}),
+            ...(options.checkPatches !== undefined
+                ? { checkPatches: options.checkPatches }
+                : {}),
         });
     }
     finally {
@@ -494,6 +502,7 @@ export function installBundleTree(options) {
         throw new Error(`${subject}: a template must not carry patches — content, never code (spec 5462 D9)`);
     }
     validatePatches(patches, targetAbs, subject);
+    options.checkPatches?.(patches);
     // The exclusion set copyTree/the content-only guard both use — built from
     // NORMALIZED installMap keys (#5514) so a "./x" key excludes the same
     // string `rel`'s traversal below computes, rather than colliding with it
@@ -506,6 +515,11 @@ export function installBundleTree(options) {
         ...Object.keys(installMap).map((key) => normalize(key).split(sep).join("/")),
     ]);
     if (isTemplate) {
+        // #6658 D7 — a template's roster of record lands as JSON, through its
+        // `installMap` (`TEMPLATE-MANIFEST.json` → `.ailk-site-manifest.json`).
+        // The Markdown is the template's own documentation: bundles still carry
+        // it, but it never reaches a scaffold's root.
+        excluded.add(TEMPLATE_MANIFEST_MD);
         validateTemplateContentOnly(sourceRoot, excluded, subject);
     }
     // #5618 D4 — the additive-overlap check, at the same seam as the
@@ -553,6 +567,20 @@ export function installBundleTree(options) {
         const targetAbsPath = resolve(targetAbs, target);
         return existsSync(targetAbsPath) ? readFileSync(targetAbsPath, "utf8") : undefined;
     };
+    // #6653 — under skip-existing, a patch target the tree ALSO delivers would be
+    // computed from the bundle's copy and written over the site's file, which
+    // the policy exists to leave alone. No slice does this today; refuse it.
+    if (options.existingFilePolicy === "skip-existing") {
+        for (const patch of patches) {
+            const target = toPosix(patch.target);
+            const staged = resolve(sourceRoot, patch.target);
+            const delivered = [...installMapDestinationToSource.keys()].some((d) => toPosix(d) === target) ||
+                (!excluded.has(target) && existsSync(staged) && statSync(staged).isFile());
+            if (delivered) {
+                throw new Error(`${subject}: patch target ${target} is also delivered by the bundle — refused, because it would replace the site's own file`);
+            }
+        }
+    }
     const computedPatches = computeModulePatches(patches, {
         versions: options.versions ?? {},
         readTarget: readPatchTarget,
@@ -564,7 +592,9 @@ export function installBundleTree(options) {
     // 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.
-    copyTree(sourceRoot, targetAbs, excluded, markers);
+    const report = [];
+    const policy = options.existingFilePolicy ?? "overwrite";
+    copyTree(sourceRoot, targetAbs, excluded, markers, policy, report);
     for (const [source, destination] of Object.entries(installMap)) {
         const destAbs = resolve(targetAbs, destination);
         mkdirSync(join(destAbs, ".."), { recursive: true });
@@ -575,14 +605,25 @@ export function installBundleTree(options) {
         // read as utf8 and rewritten, turning every invalid byte sequence into
         // U+FFFD — silent, unrecoverable corruption. Requiring both makes the
         // safe direction structural rather than a property of today's manifests.
-        writeOneFile(resolve(sourceRoot, source), destAbs, [source, destination], markers);
+        const row = writeOneFile(resolve(sourceRoot, source), destAbs, toPosix(destination), [source, destination], markers, policy);
+        if (row !== undefined)
+            report.push(row);
     }
     // patches write AFTER every file the tree 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.
+    // computeModulePatches already dropped every already-applied target, so an
+    // idempotent replay produces no `patched` row. Diffed before the write, while
+    // `readPatchTarget` still returns the pre-patch bytes.
+    const patchedRows = computedPatches.map(({ target, content }) => ({
+        path: toPosix(target),
+        action: "patched",
+        change: diffTwoStrings(toPosix(target), readPatchTarget(target) ?? "", content, true),
+    }));
     writeModulePatches(computedPatches, targetAbs);
+    report.push(...patchedRows);
     // #5618 D4 — record this layer's destinations only now that every one of
     // them is in place (a later layer's overwrite is judged against the layer
     // that actually wrote the bytes). Patch targets are NOT recorded: a patch
@@ -598,9 +639,12 @@ export function installBundleTree(options) {
     // validateTemplateLayout); returned as-is (defaults unfilled) for the
     // caller to resolve alongside whatever the code registry's own
     // `TemplateManifest.layout` says.
-    return isTemplate && manifest?.layout !== undefined
-        ? { layout: manifest.layout }
-        : {};
+    return {
+        report,
+        ...(isTemplate && manifest?.layout !== undefined
+            ? { layout: manifest.layout }
+            : {}),
+    };
 }
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
@@ -611,10 +655,15 @@ export function installBundleTree(options) {
  * path-safety check is needed here — `srcRoot` is our own staging tree, not
  * attacker-controlled input.
  *
+ * A directory is created only as the parent of a file actually copied, never
+ * for its own sake: a source directory whose every file is excluded (mapped
+ * away) leaves nothing behind at its original path (#6787 — an empty root
+ * `content/en/blog/` reads as an unregistered page type).
+ *
  * `markers`, when given, is substituted into every TEXT file on the way
  * through (#6460) — see `InstallBundleTreeOptions.markers`.
  */
-function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
+function copyTree(srcRoot, destRoot, excluded, markers, policy, report) {
     const stack = [srcRoot];
     while (stack.length > 0) {
         const dir = stack.pop();
@@ -625,14 +674,15 @@ function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
             const rel = relative(srcRoot, srcPath);
             const destPath = join(destRoot, rel);
             if (entry.isDirectory()) {
-                mkdirSync(destPath, { recursive: true });
                 stack.push(srcPath);
             }
             else if (entry.isFile()) {
                 if (excluded.has(rel.split(sep).join("/")))
                     continue;
                 mkdirSync(join(destPath, ".."), { recursive: true });
-                writeOneFile(srcPath, destPath, [rel], markers);
+                const row = writeOneFile(srcPath, destPath, toPosix(rel), [rel], markers, policy);
+                if (row !== undefined)
+                    report.push(row);
             }
             // symlinks: never present — safeExtractTarGz rejects them outright.
         }
@@ -663,15 +713,121 @@ function copyTree(srcRoot, destRoot, excluded = new Set(), markers) {
  * `S_IFREG` type bits too, which `open(2)` ignores but which have no business
  * being passed. Like `copyFileSync`, this only sets the mode when the file is
  * CREATED: an overwrite (the layer-over-layer case) keeps the existing one.
+ *
+ * `policy` (#6653 D3) is checked here, once, so `copyTree` and the installMap
+ * loop cannot diverge. Under `"skip-existing"` an existing destination is
+ * compared against the bytes this call WOULD write (post-substitution): equal
+ * → no row, nothing written; different → a `skipped` row carrying the diff.
+ * `path` is the scaffold-relative name the returned row carries.
  */
-function writeOneFile(srcAbs, destAbs, relsForType, markers) {
-    if (markers === undefined || !relsForType.every(isTextFile)) {
+function writeOneFile(srcAbs, destAbs, path, relsForType, markers, policy) {
+    const isText = relsForType.every(isTextFile);
+    const substitute = markers !== undefined && isText;
+    if (policy === "skip-existing" && existsSync(destAbs)) {
+        const wanted = substitute
+            ? Buffer.from(substituteMarkers(readFileSync(srcAbs, "utf8"), markers))
+            : readFileSync(srcAbs);
+        const existing = readFileSync(destAbs);
+        if (existing.equals(wanted))
+            return undefined;
+        // latin1 keeps one char per byte, so a binary pair's lengths stay byte counts.
+        const encoding = isText ? "utf8" : "latin1";
+        return {
+            path,
+            action: "skipped",
+            wanted: diffTwoStrings(path, existing.toString(encoding), wanted.toString(encoding), isText),
+        };
+    }
+    if (!substitute) {
         copyFileSync(srcAbs, destAbs);
-        return;
     }
-    writeFileSync(destAbs, substituteMarkers(readFileSync(srcAbs, "utf8"), markers), {
-        mode: statSync(srcAbs).mode & 0o777,
-    });
+    else {
+        writeFileSync(destAbs, substituteMarkers(readFileSync(srcAbs, "utf8"), markers), {
+            mode: statSync(srcAbs).mode & 0o777,
+        });
+    }
+    return { path, action: "written" };
+}
+function toPosix(rel) {
+    return normalize(rel).split(sep).join("/");
+}
+/** Lines of context around each change in `diffTwoStrings`'s hunks. */
+const DIFF_CONTEXT = 3;
+/**
+ * A unified diff of `before` → `after` for the report (#6653 D3) — the one
+ * helper behind both a `skipped` row's `wanted` and a `patched` row's
+ * `change`. Line-based LCS; the inputs are config and content files, small
+ * enough that the quadratic table is not a concern. `isText` false yields the
+ * binary summary instead, reading each string's length as its byte count
+ * (the caller decodes binary content as latin1).
+ */
+export function diffTwoStrings(path, before, after, isText) {
+    if (!isText) {
+        return `binary content differs (${before.length} bytes existing vs ${after.length} bytes bundle)`;
+    }
+    // A final newline terminates the last line; it is not an empty line after it.
+    const lines = (text) => (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+    const a = before === "" ? [] : lines(before);
+    const b = after === "" ? [] : lines(after);
+    // lcs[i][j] = LCS length of a[i..] and b[j..].
+    const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lcs[i][j] =
+                a[i] === b[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            ops.push({ kind: " ", line: a[i], ai: i + 1, bi: j + 1 });
+            i++;
+            j++;
+        }
+        else if (i < a.length && (j === b.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
+            ops.push({ kind: "-", line: a[i], ai: i + 1, bi: j });
+            i++;
+        }
+        else {
+            ops.push({ kind: "+", line: b[j], ai: i, bi: j + 1 });
+            j++;
+        }
+    }
+    const out = [`--- a/${path}`, `+++ b/${path}`];
+    if (ops.every((op) => op.kind === " ")) {
+        out.push("(the files differ only in their final newline)");
+        return out.join("\n");
+    }
+    let k = 0;
+    while (k < ops.length) {
+        if (ops[k].kind === " ") {
+            k++;
+            continue;
+        }
+        // Grow a hunk from this change until DIFF_CONTEXT*2 unchanged lines separate it from the next.
+        const start = Math.max(0, k - DIFF_CONTEXT);
+        let end = k;
+        let unchanged = 0;
+        while (end < ops.length && unchanged <= DIFF_CONTEXT * 2) {
+            unchanged = ops[end].kind === " " ? unchanged + 1 : 0;
+            end++;
+        }
+        end = Math.min(ops.length, end - Math.max(0, unchanged - DIFF_CONTEXT));
+        const hunk = ops.slice(start, end);
+        const oldLines = hunk.filter((op) => op.kind !== "+").length;
+        const newLines = hunk.filter((op) => op.kind !== "-").length;
+        const oldStart = hunk.find((op) => op.kind !== "+")?.ai ?? hunk[0].ai;
+        const newStart = hunk.find((op) => op.kind !== "-")?.bi ?? hunk[0].bi;
+        out.push(`@@ -${oldStart},${oldLines} +${newStart},${newLines} @@`);
+        for (const op of hunk)
+            out.push(`${op.kind}${op.line}`);
+        k = end;
+    }
+    return out.join("\n");
 }
 /**
  * `extractBundle`'s validating-filter tar extraction, ported verbatim (see

package/dist/lib/license-key-files.d.ts

@@ -0,0 +1,15 @@
+export declare const LICENSE_KEY_FILE = "ailk.key";
+export declare const LICENSE_ENV_FILE: string;
+export declare const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
+/**
+ * Throws unless `key` is 1–4096 characters of `[A-Za-z0-9._-]`. The message
+ * describes the rule, never the value.
+ */
+export declare function assertLicenseKeyShape(key: string): void;
+/**
+ * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
+ * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for
+ * `ailk.key` when no existing line covers it. Idempotent — a second call with
+ * the same key changes no byte.
+ */
+export declare function writeLicenseKeyFiles(dir: string, key: string): void;

package/dist/lib/license-key-files.js

@@ -0,0 +1,102 @@
+/**
+ * Where a scaffold keeps its licence key (#6683 § 3 D9).
+ *
+ * Two copies, both owner-only and both gitignored:
+ *
+ *   - `ailk.key` at the scaffold root — the key on its own, for a person or a
+ *     tool that needs it again (`license set` re-pushes it to Vercel);
+ *   - `apps/api/.env` — one `AILK_LICENSE_KEY=<key>` line, because `apps/api`
+ *     is the scaffold's runtime reader and loads `.env` from its own directory.
+ *
+ * `assertLicenseKeyShape` is the ONE validator every entry point calls
+ * (`--license`, `license set <key>`, `license set -`): a compact JWS is
+ * base64url segments joined by dots, so anything else — whitespace, a newline
+ * that would inject a second `.env` line — is refused, and the refusal never
+ * repeats the value (it may be a real key in a shell history or a CI log).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const LICENSE_KEY_FILE = "ailk.key";
+export const LICENSE_ENV_FILE = join("apps", "api", ".env");
+export const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
+const KEY_SHAPE = /^[A-Za-z0-9._-]{1,4096}$/;
+/** `.gitignore` lines that already ignore a root `ailk.key`. */
+const KEY_IGNORE_LINES = new Set([
+    "ailk.key",
+    "/ailk.key",
+    "**/ailk.key",
+    "*.key",
+    "/*.key",
+    "**/*.key",
+]);
+/** A line assigning the variable, with or without `export`. */
+const ENV_LINE = new RegExp(`^\\s*(?:export\\s+)?${LICENSE_ENV_VAR}\\s*=`);
+/**
+ * Throws unless `key` is 1–4096 characters of `[A-Za-z0-9._-]`. The message
+ * describes the rule, never the value.
+ */
+export function assertLicenseKeyShape(key) {
+    if (!KEY_SHAPE.test(key)) {
+        throw new Error("the licence key is malformed: expected 1-4096 characters of A-Z a-z 0-9 . _ - (a compact JWS, no whitespace or newline). Copy it again from your welcome page.");
+    }
+}
+/**
+ * Write `content` only when it differs, with mode 0600 either way. An existing
+ * file is tightened BEFORE the write — `mode` applies only on creation, so a
+ * looser pre-existing `.env` would otherwise hold the key for a moment at its
+ * old permissions.
+ */
+function writeOwnerOnly(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path))
+        chmodSync(path, 0o600);
+    if (!existsSync(path) || readFileSync(path, "utf8") !== content) {
+        writeFileSync(path, content, { mode: 0o600 });
+    }
+    chmodSync(path, 0o600);
+}
+/** `text` plus `line`, starting on a fresh line. */
+function appendLine(text, line) {
+    const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+    return `${text}${sep}${line}\n`;
+}
+/** Replace the first assignment line, drop any later duplicate, else append. */
+function upsertEnvLine(existing, key) {
+    const line = `${LICENSE_ENV_VAR}=${key}`;
+    const lines = existing.split("\n");
+    let seen = false;
+    const out = [];
+    for (const l of lines) {
+        if (ENV_LINE.test(l)) {
+            if (!seen)
+                out.push(line);
+            seen = true;
+        }
+        else {
+            out.push(l);
+        }
+    }
+    return seen ? out.join("\n") : appendLine(existing, line);
+}
+/**
+ * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
+ * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for
+ * `ailk.key` when no existing line covers it. Idempotent — a second call with
+ * the same key changes no byte.
+ */
+export function writeLicenseKeyFiles(dir, key) {
+    assertLicenseKeyShape(key);
+    writeOwnerOnly(join(dir, LICENSE_KEY_FILE), `${key}\n`);
+    const envPath = join(dir, LICENSE_ENV_FILE);
+    const env = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    writeOwnerOnly(envPath, upsertEnvLine(env, key));
+    const ignorePath = join(dir, ".gitignore");
+    const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+    const covered = ignore
+        .split("\n")
+        .some((l) => KEY_IGNORE_LINES.has(l.trim()));
+    if (!covered)
+        writeFileSync(ignorePath, appendLine(ignore, LICENSE_KEY_FILE));
+}

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

@@ -16,8 +16,14 @@
  * `resolvePaidModules` returns immediately, before touching `process.env` or
  * the network, so a bare/all-Free scaffold is provably unaffected by this
  * gate (K1's regression floor).
+ *
+ * Also carries the design gate (#6760): `assertDesignAllowed` refuses a
+ * non-`standard` design at the `free` level, naming the design and the
+ * run's level, before `scaffold()`'s first disk write.
  */
 import type { ModuleName } from "../parse-args.js";
+import type { StarterDesign } from "../template-manifest.js";
+import { type Level } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
  * `/pro` route and there will not be one (#6439, operator decision OD-2) —
@@ -33,6 +39,18 @@ export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 export declare class LicenseRequiredError extends Error {
     constructor(message: string);
 }
+/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+export declare const FREE_DESIGNS: readonly StarterDesign[];
+/** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
+export declare const DESIGN_LEVELS: readonly Level[];
+/**
+ * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
+ * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
+ * resolved; never reads a key or derives a level itself (D2, fail-closed:
+ * both checks below are allow-lists, so an unrecognized `level` refuses
+ * rather than granting it).
+ */
+export declare function assertDesignAllowed(design: StarterDesign | undefined, level: Level): void;
 export interface ResolvePaidModulesOptions {
     /** The requested module set's paid subset (see `module-tier.ts`). */
     paidModules: ModuleName[];
@@ -52,7 +70,20 @@ export interface ResolvePaidModulesOptions {
      * to do. Absent ⟹ a plain `--modules` run, whose messages are unchanged.
      */
     templateName?: string;
+    /**
+     * The key's derived level (#6759 D5), when one was derived on this call's
+     * path. Absent on the `--modules`-keep branch, where no level is derived
+     * (NFR-2) — the refusal then names only the module and its own level,
+     * never the caller's.
+     */
+    level?: Level;
 }
+/**
+ * The message phrase for one module (D5): what level includes it, or that it
+ * is an add-on. Pure — derived from `levelOf`, never from the current run's
+ * own derived level.
+ */
+export declare function levelPhrase(m: ModuleName): string;
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw
  * `LicenseRequiredError` naming exactly why the run cannot proceed. Never
@@ -61,3 +92,51 @@ export interface ResolvePaidModulesOptions {
  * BEFORE the scaffold copy — see `programmatic.ts`'s `scaffold()`).
  */
 export declare function resolvePaidModules(options: ResolvePaidModulesOptions): Promise<Map<ModuleName, Uint8Array>>;
+/** Inputs shared by `deriveLevel` and `resolveModuleSet` (D4/D5). */
+export interface GateOptions {
+    /** Defaults to `process.env["AILK_LICENSE_KEY"]`. Injectable for tests. */
+    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;
+}
+/**
+ * Derive the key's level from what the registry actually answers (D4) — the
+ * level only chooses which modules to ASK FOR; every byte is still
+ * authorized by the registry per module. Nothing client-side is an
+ * entitlement claim: the JWT is never parsed here.
+ *
+ * No key ⟹ `"free"`, zero network. A present key is shape-checked first,
+ * whichever source it came from (SEC-2). Then: probe every paid member of
+ * `LEVEL_MODULES.pro`, in order — a licence error on any of them is refused
+ * (a key that does not unlock all of Pro is not silently downgraded); any
+ * other failure (404, 5xx, unreachable) is wrapped so the caller sees it
+ * could not determine the level, and is told the escape hatch (`--modules`).
+ * Then probe `multi-tenant` (what Pro Plus adds beyond Pro): a licence error
+ * there is the expected "this key is Pro, not Pro Plus" answer, not a
+ * refusal.
+ */
+export declare function deriveLevel(options: GateOptions): Promise<{
+    level: Level;
+    bundles: Map<ModuleName, Uint8Array>;
+}>;
+/**
+ * The one entry point that turns `--modules` + the key into the effective
+ * module set and its resolved bundles (D5) — `programmatic.ts`'s `scaffold()`
+ * calls this for every run except a named `--template` alias (NFR-4).
+ *
+ * A named list with a non-addition (the KEEP branch, D2) resolves it exactly
+ * as today, with no level derived and no extra request (NFR-2). Otherwise the
+ * level is derived first, the set composed from it, and any named addition
+ * not already fetched during the level probe is resolved on top.
+ */
+export declare function resolveModuleSet(options: GateOptions & {
+    named?: readonly ModuleName[] | undefined;
+}): Promise<{
+    modules: ModuleName[];
+    bundles: Map<ModuleName, Uint8Array>;
+    level?: Level;
+}>;