create-ailk 0.4.0 → 0.5.0

package/dist/cli.js

@@ -33,7 +33,7 @@ import { fileURLToPath } from "node:url";
 import { proCallout } from "./lib/pro-callout.js";
 import { helpText, parseCliArgs, parseModules } from "./parse-args.js";
 import { formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
-import { CORE_SURFACE_PATHS } from "./surfaces.js";
+import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_JSON = resolve(PKG_ROOT, "package.json");
@@ -41,6 +41,17 @@ function readPackageVersion() {
     const raw = readFileSync(PKG_JSON, "utf8");
     return JSON.parse(raw).version;
 }
+/** Raw value of a `--flag <value>` or `--flag=<value>` argv entry, if present. */
+function readRawFlagValue(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag)
+            return argv[i + 1];
+        if (arg?.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return undefined;
+}
 async function main() {
     const argv = process.argv.slice(2);
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
@@ -60,6 +71,23 @@ async function main() {
         process.exit(!args.apply && result.missing.length > 0 ? 1 : 0);
     }
     const opts = parseCliArgs(argv);
+    // Deprecation notice for a retired `--surfaces` id (#5563 D2). `surfaces.ts`
+    // stays pure — `canonicalizeSurface` only resolves the alias — so this is
+    // the one place that prints: compare the raw `--surfaces` argv token
+    // against SURFACE_ALIASES rather than diffing the (already-canonical)
+    // parsed result.
+    const rawSurfaces = readRawFlagValue(argv, "--surfaces");
+    if (rawSurfaces !== undefined) {
+        for (const token of rawSurfaces
+            .split(",")
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean)) {
+            const canonical = SURFACE_ALIASES[token];
+            if (canonical !== undefined) {
+                process.stdout.write(`[create-ailk] "--surfaces ${token}" is retired; using "${canonical}" (#5563).\n`);
+            }
+        }
+    }
     if (opts.help) {
         process.stdout.write(helpText + "\n" + SYNC_ROUTES_HELP);
         process.exit(0);

package/dist/derive-architecture.js

@@ -181,11 +181,14 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
             forbidden_patterns: ARCHITECTURE_BASE.web.forbidden_patterns.map(forbiddenToYaml),
         },
     };
-    // Additional apps (api, mcp, workspace) in canonical order.
+    // Additional apps (api, mcp, admin) in canonical order. `admin` was
+    // `workspace` until #5637 renamed the owner surface; the slice's key was
+    // renamed there and this list was not, which dropped the Admin app from
+    // every derived architecture without failing anything but its own test.
     const extraApps = {};
     for (const s of slices)
         Object.assign(extraApps, s.apps ?? {});
-    for (const key of ["api", "mcp", "workspace"]) {
+    for (const key of ["api", "mcp", "admin"]) {
         const a = extraApps[key];
         if (a)
             apps[key] = appToYaml(a);

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

@@ -1,4 +1,23 @@
+import { type TemplateLayout } from "../site-chrome.js";
 import type { WorkspaceVersionMap } from "../substitute.js";
+/** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
+export declare const MAX_TOTAL_SIZE_BYTES: number;
+/**
+ * The file-grain ownership registry (#5618 D4): scaffold-relative destination
+ * → the layer that wrote it (a `subject` string — `template "_base"`,
+ * `module "docs-blog"`, `template "marketing-site"`). Caller-owned and
+ * CALL-SCOPED: `scaffold()` constructs one per call and threads it through
+ * every `installBundleTree` of that scaffold, so two `scaffold()` calls in
+ * one process share no state (the frozen-registry posture of #5507). It is
+ * the third ownership view beside `ownedFiles` (which repo file a module
+ * physically owns) and `pageContributions` (which route+content it brings):
+ * which scaffold destination a LAYER wrote at install time.
+ *
+ * Layer 0 — the `templates/` snapshot — is deliberately outside it: the
+ * registry starts empty at the base-layer boundary, so a destination it does
+ * not hold is the snapshot's, which a module may freely add to and patch.
+ */
+export type LayerOwnership = Map<string, string>;
 export interface ExtractModuleBundleOptions {
     /** The fetched bundle bytes (a gzipped tar archive). */
     bytes: Uint8Array;
@@ -19,6 +38,10 @@ export interface ExtractModuleBundleOptions {
      * this list (record D10, DD4). See `InstallBundleTreeOptions`.
      */
     templateRequires?: readonly string[];
+    /** The registry's `extends` for this template (#5618 D2). See `InstallBundleTreeOptions`. */
+    templateExtends?: string;
+    /** The call-scoped ownership registry (#5618 D4). See `InstallBundleTreeOptions`. */
+    ownership?: LayerOwnership;
 }
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
@@ -28,7 +51,7 @@ export interface ExtractModuleBundleOptions {
  * those cases: validation AND patch computation both complete before any
  * file is copied or written into place.
  */
-export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<void>;
+export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<InstallBundleTreeResult>;
 export interface InstallBundleTreeOptions {
     /**
      * The validated tree whose files land in the scaffold. Two source roots,
@@ -48,9 +71,34 @@ export interface InstallBundleTreeOptions {
      * (record D10, DD4). Absent ⟹ a module bundle, read exactly as before.
      */
     templateRequires?: readonly string[];
+    /**
+     * Template trees only (#5618 D2): the client registry's `extends` for this
+     * template, which the tree's `ailk-template.json` must declare verbatim —
+     * the sibling of the `requires` cross-check above. Absent for the base
+     * layer itself (the chain's terminus declares no parent) and for a module.
+     */
+    templateExtends?: string;
+    /**
+     * The call-scoped ownership registry (#5618 D4) — destination → the layer
+     * that wrote it. Present ⟹ this install is one layer of a composed
+     * scaffold: a MODULE tree is refused (before its first write) for any
+     * destination an earlier layer owns unless it is a declared `patches`
+     * target, and every layer records its destinations on success. Absent ⟹
+     * the pre-#5618 single-tree behaviour, unchecked and unrecorded.
+     */
+    ownership?: LayerOwnership;
     /** Canonical `@working-theory/*` versions for `workspace:*` substitution in patch targets. */
     versions?: WorkspaceVersionMap;
 }
+/** `installBundleTree`'s result — presently only the template-only `layout` knobs. */
+export interface InstallBundleTreeResult {
+    /**
+     * The installed template's validated `layout` block (#5612 D1), unresolved
+     * (defaults NOT filled — `resolveSiteChrome` does that). `undefined` for a
+     * module install, or a template whose manifest declares no `layout`.
+     */
+    layout?: TemplateLayout;
+}
 /**
  * Apply one resolved manifest's `installMap`, plain content and `patches`
  * from `sourceRoot` into `targetDir`.
@@ -61,4 +109,4 @@ export interface InstallBundleTreeOptions {
  * patch computation both complete before the first byte is written, so a
  * rejected tree leaves `targetDir` exactly as it was.
  */
-export declare function installBundleTree(options: InstallBundleTreeOptions): void;
+export declare function installBundleTree(options: InstallBundleTreeOptions): InstallBundleTreeResult;

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

@@ -83,10 +83,13 @@ 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 { coOwnedModuleDestinations, } from "../module-architecture.js";
+import { validateTemplateLayout, } from "../site-chrome.js";
 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
+/** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
+export 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";
 /**
@@ -164,7 +167,7 @@ function readAilkModuleManifest(extractedRoot) {
  * is whatever the archive says. Compared as SETS, not as sequences — the
  * registry's declaration order is not part of the contract.
  */
-function readAilkTemplateManifest(sourceRoot, name, expectedRequires) {
+function readAilkTemplateManifest(sourceRoot, name, expectedRequires, expectedExtends) {
     const manifestPath = join(sourceRoot, AILK_TEMPLATE_JSON);
     if (!existsSync(manifestPath)) {
         throw new Error(`template "${name}": bundle carries no ${AILK_TEMPLATE_JSON} — a template manifest is mandatory`);
@@ -176,15 +179,44 @@ function readAilkTemplateManifest(sourceRoot, name, expectedRequires) {
     catch {
         throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} is not readable JSON`);
     }
-    const declared = manifest.requires;
-    if (!Array.isArray(declared)) {
+    const declaredRaw = manifest.requires;
+    if (!Array.isArray(declaredRaw)) {
         throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} declares no "requires" list`);
     }
+    // #5514: every element must be a string BEFORE the comparison below — a
+    // prior `join(",")` comparison would let a non-string element (or one
+    // containing a comma) defeat the disagreement check by colliding with an
+    // unrelated element-set on the joined string.
+    for (const item of declaredRaw) {
+        if (typeof item !== "string") {
+            throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} "requires" contains a non-string entry`);
+        }
+    }
+    const declared = declaredRaw;
     const expected = [...new Set(expectedRequires)].sort();
     const actual = [...new Set(declared)].sort();
-    if (expected.join(",") !== actual.join(",")) {
+    const disagrees = expected.length !== actual.length ||
+        expected.some((value, index) => value !== actual[index]);
+    if (disagrees) {
         throw new Error(`template "${name}": bundle requires [${actual.join(", ")}] but this create-ailk's registry requires [${expected.join(", ")}] — upgrade create-ailk`);
     }
+    // #5618 D2 — `extends` joins `requires` as the sibling cross-check, with
+    // the same "upgrade create-ailk" posture: the registry's value is the
+    // caller's compile-checked lineage, the bundle's is whatever the archive
+    // says. Compared exactly (a single parent, not a set). The base layer is
+    // the terminus and declares none — its caller passes none.
+    const declaredExtends = manifest.extends;
+    if (declaredExtends !== undefined && typeof declaredExtends !== "string") {
+        throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} "extends" is not a string`);
+    }
+    if (declaredExtends !== expectedExtends) {
+        const show = (value) => value === undefined ? "nothing" : `"${value}"`;
+        throw new Error(`template "${name}": bundle extends ${show(declaredExtends)} but this create-ailk's registry extends ${show(expectedExtends)} — upgrade create-ailk`);
+    }
+    // #5612 D1 — validated here (throws naming the field on an unrecognized
+    // value), never merely stored: a bundle's `layout` is untrusted JSON,
+    // unlike the code registry's compile-time-checked `TemplateManifest.layout`.
+    validateTemplateLayout(manifest.layout, `template "${name}"`);
     return manifest;
 }
 /**
@@ -193,7 +225,7 @@ function readAilkTemplateManifest(sourceRoot, name, expectedRequires) {
  * 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, subject) {
+function validateInstallMap(installMap, extractedRoot, targetAbs, subject, isTemplate) {
     for (const [source, destination] of Object.entries(installMap)) {
         if (hasUnsafeSegment(source)) {
             throw new Error(`${subject}: unsafe installMap source "${source}"`);
@@ -219,6 +251,13 @@ function validateInstallMap(installMap, extractedRoot, targetAbs, subject) {
         if (!isPathInside(targetAbs, destAbs)) {
             throw new Error(`${subject}: installMap destination "${destination}" resolves outside target`);
         }
+        // #5514 (Medium) — content, never code (spec 5462 D9/D16): a template's
+        // installMap can only ever ADD a file, so a code-extension destination
+        // is refused outright, same fail-closed point as the containment checks
+        // above.
+        if (isTemplate && hasTemplateForbiddenExtension(destination)) {
+            throw new Error(`${subject}: a template must not carry a code file — installMap destination "${destination}" (spec 5462 D9)`);
+        }
     }
 }
 /**
@@ -250,11 +289,130 @@ function validatePatches(patches, targetAbs, subject) {
         }
     }
 }
+/**
+ * TEMPLATE-only "content, never code" guard (spec 5462 § D9/D16; #5514). A
+ * template's manifest and tree are UNTRUSTED — fetched from the registry —
+ * so the rule that a template contributes content, never code, is enforced
+ * here, at the same fail-closed validation point as `installMap`/`patches`
+ * below, rather than only by the two jest cases that assert it against the
+ * `site-templates/` tree this create-ailk itself ships (those only prove
+ * OUR tree is honest, not that a hostile registry response is refused).
+ */
+const TEMPLATE_FORBIDDEN_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+function hasTemplateForbiddenExtension(p) {
+    return TEMPLATE_FORBIDDEN_EXTENSIONS.some((ext) => p.toLowerCase().endsWith(ext));
+}
+/**
+ * Walks `srcRoot` and throws on the first file (not in `excluded`) whose
+ * name ends in a code extension — before any copy, so a violation rejects
+ * the whole tree with nothing written to `targetDir` (same posture as
+ * `validateInstallMap`/`validatePatches`). `excluded` is the SAME
+ * POSIX-normalized set `copyTree` below will use, so the manifest itself and
+ * any installMap source never trip this guard a second time.
+ */
+function validateTemplateContentOnly(srcRoot, excluded, subject) {
+    const stack = [srcRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const srcPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(srcPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = relative(srcRoot, srcPath).split(sep).join("/");
+            if (excluded.has(rel))
+                continue;
+            if (hasTemplateForbiddenExtension(rel)) {
+                throw new Error(`${subject}: a template must not carry a code file — "${rel}" (spec 5462 D9)`);
+            }
+            // symlinks: never present — safeExtractTarGz rejects them outright.
+        }
+    }
+}
 /** 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, "");
 }
+/**
+ * The additive-overlap rule (#5618 D4), checked in the validation block
+ * before the first write so a refusal leaves `targetDir` exactly as it was:
+ *
+ *   | incoming layer | destination owned by          | outcome                     |
+ *   | base           | nothing (it is first)         | records                     |
+ *   | module         | base or an earlier module     | REFUSED — unless a declared |
+ *   |                |                               | `patches` target            |
+ *   | module         | nothing recorded              | allowed, records            |
+ *   | template       | anything                      | allowed, records            |
+ *
+ * The template layer may overwrite anything because it is the customer's
+ * copy — that is how a template overrides a module's seed page (D3), and
+ * refusing it would refuse `--template marketing-site` as shipped. The
+ * `patches` escape hatch is unambiguously module-only: a template carrying
+ * `patches` at all is refused outright above.
+ *
+ * The SECOND module-only escape hatch is DECLARED CO-OWNERSHIP
+ * (`coOwnedModuleDestinations()`): a repo file that more than one module's
+ * `ownedFiles` names. Both bundles stage it from the same source, so the
+ * second to land writes the bytes already there — no disagreement to
+ * resolve, which is the only thing this rule protects against. #5677 needs
+ * it: the review surface registers under `multi-tenant || signal-collectors`
+ * and so must ship in both bundles, and `saas-product` selects both. An
+ * overlap neither module declares is still refused.
+ *
+ * Mirrors `mergeRoster`'s `claimedBy` refusal one grain down: a collision is
+ * named with both claimants and the path, never resolved by a silent
+ * last-writer-wins.
+ */
+function validateLayerOwnership(destinations, ownership, subject, isTemplate, patchTargets, coOwned) {
+    if (isTemplate)
+        return;
+    for (const destination of destinations) {
+        const owner = ownership.get(destination);
+        if (owner !== undefined &&
+            !patchTargets.has(destination) &&
+            !coOwned.has(destination)) {
+            throw new Error(`${subject}: destination "${destination}" is already owned by ${owner} — a module's contribution to a file another layer wrote must be a declared patch, never an overwrite (#5618 D4)`);
+        }
+    }
+}
+/**
+ * Every scaffold-relative destination this tree will write: each unmapped
+ * staged file at its own path (exactly the set `copyTree` lands, same walk,
+ * same exclusions) plus every `installMap` destination. Computed before any
+ * write, for `validateLayerOwnership` and then for the record.
+ */
+function collectLayerDestinations(srcRoot, excluded, installMap) {
+    const out = [];
+    const stack = [srcRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const srcPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(srcPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = relative(srcRoot, srcPath).split(sep).join("/");
+            if (excluded.has(rel))
+                continue;
+            out.push(rel);
+        }
+    }
+    for (const destination of Object.values(installMap)) {
+        out.push(normalize(destination).split(sep).join("/"));
+    }
+    return out;
+}
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
  * the tree `copyTemplate` already wrote. Throws on any unsafe entry,
@@ -278,11 +436,15 @@ export async function extractModuleBundle(options) {
         await safeExtractTarGz(stagingTar, extractedRoot, templateRequires !== undefined
             ? `template "${moduleName}"`
             : `module "${moduleName}"`);
-        installBundleTree({
+        return installBundleTree({
             sourceRoot: extractedRoot,
             targetDir: targetAbs,
             name: moduleName,
             ...(templateRequires !== undefined ? { templateRequires } : {}),
+            ...(options.templateExtends !== undefined
+                ? { templateExtends: options.templateExtends }
+                : {}),
+            ...(options.ownership !== undefined ? { ownership: options.ownership } : {}),
             ...(options.versions !== undefined ? { versions: options.versions } : {}),
         });
     }
@@ -301,7 +463,7 @@ export async function extractModuleBundle(options) {
  * rejected tree leaves `targetDir` exactly as it was.
  */
 export function installBundleTree(options) {
-    const { sourceRoot, name, templateRequires } = options;
+    const { sourceRoot, name, templateRequires, templateExtends, ownership } = options;
     const targetAbs = resolve(options.targetDir);
     const isTemplate = templateRequires !== undefined;
     const subject = isTemplate ? `template "${name}"` : `module "${name}"`;
@@ -309,16 +471,51 @@ export function installBundleTree(options) {
     // whole tree with nothing written to targetDir (same posture as the
     // tar-entry validation in safeExtractTarGz).
     const manifest = isTemplate
-        ? readAilkTemplateManifest(sourceRoot, name, templateRequires)
+        ? readAilkTemplateManifest(sourceRoot, name, templateRequires, templateExtends)
         : readAilkModuleManifest(sourceRoot);
     const installMap = manifest?.installMap ?? {};
-    validateInstallMap(installMap, sourceRoot, targetAbs, subject);
+    validateInstallMap(installMap, sourceRoot, targetAbs, subject, isTemplate);
     // patches validation (spec 5418 § 3 D6) runs at the same point, before
     // any copy — a bad target/kind/op rejects the whole tree with nothing
     // written to targetDir, same posture as installMap and the tar-entry
     // validation above.
     const patches = manifest?.patches ?? [];
+    // #5514 (Medium) — content, never code (spec 5462 D9/D16): every `patches`
+    // kind either edits a code file directly (`next-config`, `jest-config`)
+    // or a manifest a template has no legitimate reason to touch
+    // (`package.json`/`tsconfig.json` belong to the scaffold, not to a
+    // content template) — no shipped template uses it, so the simplest
+    // fail-closed reading refuses it outright rather than enumerating an
+    // allowed subset that has no current user.
+    if (isTemplate && patches.length > 0) {
+        throw new Error(`${subject}: a template must not carry patches — content, never code (spec 5462 D9)`);
+    }
     validatePatches(patches, targetAbs, subject);
+    // 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
+    // only by accident. Both manifest filenames are excluded unconditionally
+    // (previously a ternary picked one) — a module bundle carrying a stray
+    // ailk-template.json, or vice versa, should never land either.
+    const excluded = new Set([
+        AILK_TEMPLATE_JSON,
+        AILK_MODULE_JSON,
+        ...Object.keys(installMap).map((key) => normalize(key).split(sep).join("/")),
+    ]);
+    if (isTemplate) {
+        validateTemplateContentOnly(sourceRoot, excluded, subject);
+    }
+    // #5618 D4 — the additive-overlap check, at the same seam as the
+    // installMap/patches/content-only validation above: BEFORE the first write
+    // at copyTree below, so a refused layer leaves targetDir exactly as it
+    // was. The destination set is what copyTree + the installMap loop will
+    // land; the record happens after writeModulePatches, once it has.
+    const layerDestinations = ownership !== undefined
+        ? collectLayerDestinations(sourceRoot, excluded, installMap)
+        : [];
+    if (ownership !== undefined) {
+        validateLayerOwnership(layerDestinations, ownership, subject, isTemplate, new Set(patches.map((patch) => normalize(patch.target).split(sep).join("/"))), coOwnedModuleDestinations());
+    }
     // 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
@@ -353,10 +550,6 @@ 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.
-    const excluded = new Set([
-        isTemplate ? AILK_TEMPLATE_JSON : AILK_MODULE_JSON,
-        ...Object.keys(installMap),
-    ]);
     copyTree(sourceRoot, targetAbs, excluded);
     for (const [source, destination] of Object.entries(installMap)) {
         const destAbs = resolve(targetAbs, destination);
@@ -369,9 +562,24 @@ export function installBundleTree(options) {
     // COMPUTED above, before either ran) overwrites rather than conflicts
     // with content copyTree/installMap just placed at the same path.
     writeModulePatches(computedPatches, targetAbs);
+    // #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
+    // edits a file another layer (or the snapshot) owns and does not claim it.
+    if (ownership !== undefined) {
+        for (const destination of layerDestinations)
+            ownership.set(destination, subject);
+    }
     if (manifest?.postInstall) {
         process.stdout.write(`${stripControlCharacters(manifest.postInstall)}\n`);
     }
+    // #5612 D1/D2 — already validated above (readAilkTemplateManifest calls
+    // 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 }
+        : {};
 }
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
@@ -470,7 +678,7 @@ async function safeExtractTarGz(tarGzPath, targetDir, subject) {
         },
     });
     try {
-        await pipeline(createReadStream(tarGzPath), createGunzip(), extractStream);
+        await pipeline(createReadStream(tarGzPath), createGunzip({ maxOutputLength: MAX_TOTAL_SIZE_BYTES }), extractStream);
     }
     catch (err) {
         if (captured.error !== null)

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

@@ -0,0 +1,28 @@
+/**
+ * Per-request timeout applied to every template/module registry fetch.
+ * 30s is generous for a small tarball fetch over a real network while still
+ * bounding a hung connection or slow-drip response.
+ */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` — one call site, one constant. */
+export declare function fetchTimeoutSignal(): AbortSignal;
+/**
+ * Reject a registry URL whose origin is not `https:`, unless its host is
+ * loopback (above) — the mock registry the test suite spawns is deliberately
+ * plain `http://127.0.0.1:<port>`. `ErrorCtor` lets each
+ * caller throw its own error class (`FetchTemplateError` / `FetchModuleError`)
+ * so this is a new FAILURE MODE, never a new error type from the caller's
+ * point of view — and never a licence error (`isLicenseError` stays false).
+ */
+export declare function assertHttpsRegistryUrl<E extends Error>(registryUrl: string, ErrorCtor: new (message: string) => E): void;
+/**
+ * Reject a `Response` whose `Content-Length` header declares a size larger
+ * than `MAX_TOTAL_SIZE_BYTES` — called by the caller right after its
+ * existing status-code checks succeed, BEFORE `.arrayBuffer()` ever runs, so
+ * an oversized body is never buffered into memory. A missing or unparseable
+ * `Content-Length` is not itself a violation (a chunked/streamed response may
+ * omit it) — this is defense in depth against a declared size, not a
+ * replacement for the tar-entry cumulative-size cap `extract-module-bundle.ts`
+ * still enforces downstream.
+ */
+export declare function assertContentLengthWithinLimit<E extends Error>(response: Response, ErrorCtor: new (message: string) => E): void;

package/dist/lib/fetch-guard.js

@@ -0,0 +1,101 @@
+/**
+ * Shared network-safety guards for `fetch-template.ts` / `fetch-module.ts`
+ * (issue #5514, Lows 2 and 5 — a post-merge backstop on #5510's
+ * `create-ailk --template` feature).
+ *
+ * A plain internal helper module, not a shared package: both callers already
+ * state at length (see their file docs) why `create-ailk` — the one package
+ * in this monorepo published to public npm — cannot take a runtime
+ * dependency on anything `restricted`-tier. A sibling file inside
+ * `packages/create-ailk/src/lib/` carries no such dependency and is exactly
+ * the right place for logic the two fetchers would otherwise duplicate a
+ * second time.
+ *
+ * Three guards live here:
+ *   - `REQUEST_TIMEOUT_MS` / `fetchTimeoutSignal()` — neither fetcher had a
+ *     request timeout before this; a hung or slow-drip response could block
+ *     `create-ailk` forever.
+ *   - `assertHttpsRegistryUrl()` — neither fetcher validated the scheme of
+ *     the registry URL (env-var-overridable) it was about to send a bearer
+ *     JWT to. Rejects any non-`https:` origin, UNLESS the test-mode seam
+ *     (`NODE_ENV === "test"`) is active — the same seam
+ *     `template-scaffold.test.ts`'s `run()` helper already relies on when it
+ *     spreads `process.env` into the CLI subprocess it spawns against the
+ *     loopback mock registry (`http://127.0.0.1:<port>`). Confirmed
+ *     empirically: Jest sets `NODE_ENV=test` for its own process (and thus
+ *     every child it spawns, since `run()` inherits `process.env`) whenever
+ *     the ambient environment does not already set it — there is no other
+ *     test-mode flag anywhere in this codebase (`AILK_ALLOW*`, `insecure`,
+ *     `__TEST__`, etc. do not exist).
+ *   - `assertContentLengthWithinLimit()` — neither fetcher checked a
+ *     response's declared size against `MAX_TOTAL_SIZE_BYTES` before buffering
+ *     the WHOLE body via `.arrayBuffer()`. That cap was previously enforced
+ *     only downstream, against tar entries, in
+ *     `extract-module-bundle.ts`'s `safeExtractTarGz` — too late to stop an
+ *     oversized response from being held in memory first.
+ */
+import { MAX_TOTAL_SIZE_BYTES } from "./extract-module-bundle.js";
+/**
+ * Per-request timeout applied to every template/module registry fetch.
+ * 30s is generous for a small tarball fetch over a real network while still
+ * bounding a hung connection or slow-drip response.
+ */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` — one call site, one constant. */
+export function fetchTimeoutSignal() {
+    return AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+}
+/**
+ * `true` iff `hostname` is a loopback host — the ONLY hosts a plain `http:`
+ * registry URL is accepted for. The test suite spawns its mock registry on
+ * `127.0.0.1`; nothing else needs cleartext. (An earlier revision keyed this
+ * on `NODE_ENV=test`, an ambient variable any environment can export — a
+ * security control in a public npm package must not carry a kill switch.)
+ */
+function isLoopbackHost(hostname) {
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]" || hostname === "::1";
+}
+/**
+ * Reject a registry URL whose origin is not `https:`, unless its host is
+ * loopback (above) — the mock registry the test suite spawns is deliberately
+ * plain `http://127.0.0.1:<port>`. `ErrorCtor` lets each
+ * caller throw its own error class (`FetchTemplateError` / `FetchModuleError`)
+ * so this is a new FAILURE MODE, never a new error type from the caller's
+ * point of view — and never a licence error (`isLicenseError` stays false).
+ */
+export function assertHttpsRegistryUrl(registryUrl, ErrorCtor) {
+    let scheme;
+    let hostname;
+    try {
+        const parsed = new URL(registryUrl);
+        scheme = parsed.protocol;
+        hostname = parsed.hostname;
+    }
+    catch {
+        throw new ErrorCtor(`refusing to use registry URL "${registryUrl}": not a valid URL`);
+    }
+    if (scheme !== "https:" && !isLoopbackHost(hostname)) {
+        throw new ErrorCtor(`refusing to use registry URL "${registryUrl}": scheme must be https:, got "${scheme}"`);
+    }
+}
+/**
+ * Reject a `Response` whose `Content-Length` header declares a size larger
+ * than `MAX_TOTAL_SIZE_BYTES` — called by the caller right after its
+ * existing status-code checks succeed, BEFORE `.arrayBuffer()` ever runs, so
+ * an oversized body is never buffered into memory. A missing or unparseable
+ * `Content-Length` is not itself a violation (a chunked/streamed response may
+ * omit it) — this is defense in depth against a declared size, not a
+ * replacement for the tar-entry cumulative-size cap `extract-module-bundle.ts`
+ * still enforces downstream.
+ */
+export function assertContentLengthWithinLimit(response, ErrorCtor) {
+    const header = response.headers.get("content-length");
+    if (header === null)
+        return;
+    const declared = Number(header);
+    if (!Number.isFinite(declared))
+        return;
+    if (declared > MAX_TOTAL_SIZE_BYTES) {
+        throw new ErrorCtor(`refusing response: declared Content-Length ${declared} exceeds the ${MAX_TOTAL_SIZE_BYTES}-byte limit`);
+    }
+}

package/dist/lib/fetch-module.js

@@ -36,6 +36,7 @@
  * exit uniformly.
  */
 import pkg from "../../package.json" with { type: "json" };
+import { assertContentLengthWithinLimit, assertHttpsRegistryUrl, fetchTimeoutSignal, } from "./fetch-guard.js";
 export const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
 /**
  * This package's own `package.json` `"version"`. Deliberately a static JSON
@@ -79,6 +80,7 @@ export async function fetchModule(options) {
     const registryUrl = options.registryUrl ??
         process.env["AILK_MODULE_REGISTRY_URL"] ??
         DEFAULT_AILK_MODULE_REGISTRY_URL;
+    assertHttpsRegistryUrl(registryUrl, FetchModuleError);
     const url = buildUrl(registryUrl, moduleName, version);
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     let response;
@@ -90,6 +92,7 @@ export async function fetchModule(options) {
                 Accept: "application/gzip, application/octet-stream",
             },
             redirect: "error",
+            signal: fetchTimeoutSignal(),
         });
     }
     catch (err) {
@@ -111,6 +114,7 @@ export async function fetchModule(options) {
         const body = await safeReadBody(response);
         throw new FetchModuleError(`module registry returned ${response.status} for "${moduleName}": ${body}`);
     }
+    assertContentLengthWithinLimit(response, FetchModuleError);
     const buf = await response.arrayBuffer();
     return new Uint8Array(buf);
 }