akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/core/asset/frontmatter.js

@@ -10,7 +10,7 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import { assembleAsset } from "./asset-serialize.js";
+import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
  *
@@ -51,15 +51,11 @@ export function parseFrontmatter(raw) {
     };
 }
 /**
- * Normalize YAML-parsed values to match expected AKM frontmatter types.
+ * Normalize YAML dates to match expected AKM frontmatter types.
  *
- * Two conversions:
- * 1. `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
+ * `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
  *    scalars like `2026-06-18` as JS Date instances. AKM frontmatter treats
  *    `updated:` and similar fields as plain strings.
- * 2. `null` → `""`: the yaml library parses empty-value keys (`key:` with no
- *    value) as `null`, but AKM callers historically received `""` from the
- *    hand-rolled parser. Convert to preserve backward compatibility.
  */
 function normalizeYamlValues(value) {
     if (value instanceof Date) {
@@ -68,11 +64,9 @@ function normalizeYamlValues(value) {
         const d = String(value.getUTCDate()).padStart(2, "0");
         return `${y}-${m}-${d}`;
     }
-    if (value === null)
-        return "";
     if (Array.isArray(value))
         return value.map(normalizeYamlValues);
-    if (typeof value === "object") {
+    if (value !== null && typeof value === "object") {
         return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, normalizeYamlValues(v)]));
     }
     return value;
@@ -118,15 +112,37 @@ function parseFrontmatterLenient(frontmatter) {
  * or `null` to skip the write entirely (e.g. for idempotent no-ops). The body
  * content is preserved from the parse.
  *
+ * A frontmatter mutation is a METADATA edit, not a content edit: when the file
+ * already has a frontmatter block, only that block is replaced and the body
+ * bytes are kept verbatim (routing through `assembleAsset` would strip the
+ * body's leading blank lines and force a trailing newline, silently reshaping
+ * assets whose writer used a different separator style). A file gaining its
+ * FIRST frontmatter block goes through the canonical `assembleAsset` shape.
+ *
  * @returns `true` if a write occurred, `false` if the mutator returned `null`.
  */
 export function mutateFrontmatter(filePath, mutator) {
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = parseFrontmatter(raw);
+    if (parsed.frontmatter?.trim()) {
+        let strict;
+        try {
+            strict = yamlParse(parsed.frontmatter);
+        }
+        catch {
+            throw new Error(`Cannot mutate malformed YAML frontmatter in ${filePath}.`);
+        }
+        if (strict === null || typeof strict !== "object" || Array.isArray(strict)) {
+            throw new Error(`Cannot mutate non-mapping YAML frontmatter in ${filePath}.`);
+        }
+    }
     const nextFrontmatter = mutator(parsed);
     if (nextFrontmatter === null)
         return false;
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    const next = parsed.frontmatter !== null
+        ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
+        : assembleAsset(nextFrontmatter, parsed.content);
+    fs.writeFileSync(filePath, next, "utf8");
     return true;
 }
 export function parseFrontmatterBlock(raw) {
@@ -141,7 +157,7 @@ export function parseFrontmatterBlock(raw) {
         return {
             frontmatter,
             content,
-            bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
+            bodyStartLine: countLines(raw.slice(0, match[0].length - content.length)) + 1,
         };
     }
     // Empty frontmatter (---\n---): the content-bearing regex above requires at

package/dist/core/asset/markdown.js

@@ -2,6 +2,34 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { parseFrontmatter } from "./frontmatter.js";
+/** Stable GitHub-style selector for a Markdown heading. */
+export function markdownHeadingSlug(heading) {
+    return heading
+        .trim()
+        .toLowerCase()
+        .replace(/<[^>]*>/g, "")
+        .replace(/[^\p{L}\p{N}\s_-]+/gu, "-")
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function markdownFragmentSlugs(content) {
+    return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
+}
+function uniqueHeadingSlugs(headings) {
+    const used = new Set();
+    return headings.map((heading) => {
+        const base = markdownHeadingSlug(heading.text);
+        if (!base)
+            return "";
+        let slug = base;
+        let suffix = 0;
+        while (used.has(slug))
+            slug = `${base}-${++suffix}`;
+        used.add(slug);
+        return slug;
+    });
+}
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {
     const lines = content.split(/\r?\n/);
@@ -31,61 +59,22 @@ export function parseMarkdownToc(content) {
 // ── Extraction ──────────────────────────────────────────────────────────────
 export function extractSection(content, heading) {
     const lines = content.split(/\r?\n/);
-    const target = heading.toLowerCase();
-    let startIdx = -1;
-    let startLevel = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
-        if (!match)
-            continue;
-        const text = match[2].replace(/\s+#+\s*$/, "").trim();
-        if (text.toLowerCase() === target && startIdx === -1) {
-            startIdx = i;
-            startLevel = match[1].length;
-        }
-        else if (startIdx !== -1 && match[1].length <= startLevel) {
-            return {
-                content: lines.slice(startIdx, i).join("\n"),
-                startLine: startIdx + 1,
-                endLine: i,
-            };
-        }
-    }
-    if (startIdx === -1)
+    const headings = parseMarkdownToc(content).headings;
+    const fragment = heading.trim();
+    const slugIndex = uniqueHeadingSlugs(headings).indexOf(fragment);
+    const exact = slugIndex < 0 ? headings.find((candidate) => candidate.text.toLowerCase() === fragment.toLowerCase()) : undefined;
+    const selected = slugIndex >= 0 ? headings[slugIndex] : exact;
+    if (!selected)
         return null;
+    const next = headings.find((candidate) => candidate.line > selected.line && candidate.level <= selected.level);
+    const startIdx = selected.line - 1;
+    const endIdx = next ? next.line - 1 : lines.length;
     return {
-        content: lines.slice(startIdx).join("\n"),
-        startLine: startIdx + 1,
-        endLine: lines.length,
+        content: lines.slice(startIdx, endIdx).join("\n"),
+        startLine: selected.line,
+        endLine: endIdx,
     };
 }
-export function extractLineRange(content, start, end) {
-    const lines = content.split(/\r?\n/);
-    if (end < start)
-        return "";
-    const s = Math.max(1, Math.min(start, lines.length));
-    const e = Math.min(end, lines.length);
-    return lines.slice(s - 1, e).join("\n");
-}
-export function extractFrontmatterOnly(content) {
-    const parsed = parseFrontmatter(content);
-    return parsed.frontmatter;
-}
-// ── Formatting ──────────────────────────────────────────────────────────────
-export function formatToc(toc) {
-    if (toc.headings.length === 0) {
-        return `(no headings found — ${toc.totalLines} lines total)`;
-    }
-    const lineWidth = String(toc.totalLines).length;
-    const parts = toc.headings.map((h) => {
-        const lineNum = `L${String(h.line).padStart(lineWidth)}`;
-        const indent = "  ".repeat(h.level - 1);
-        const prefix = "#".repeat(h.level);
-        return `${lineNum}  ${indent}${prefix} ${h.text}`;
-    });
-    parts.push(`\n${toc.totalLines} lines total`);
-    return parts.join("\n");
-}
 // ── Fence stripping ──────────────────────────────────────────────────────────
 /**
  * Best-effort fence stripping. Strips `<think>` reasoning blocks emitted by

package/dist/core/asset/resolve-ref.js

@@ -0,0 +1,274 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Ref RESOLUTION layer — akm 0.9.0 Chunk-5 flip, stage F1 (ref-grammar decision
+ * D-R1 / D-R4).
+ *
+ * The 0.9.0 ref abstraction is `parse → resolve → serialize`:
+ *   - parse     — `parseBundleRef` (`asset-ref.ts`), pure syntax, no I/O.
+ *   - resolve   — {@link resolveRef} (this module): turn a maybe-short
+ *                 {@link BundleRef} into a fully-qualified {@link ResolvedRef}
+ *                 against an injected {@link RefContext}. This is the "the short
+ *                 form is input sugar" rule (§11.1) made structural: only a
+ *                 `ResolvedRef` ever crosses a storage boundary.
+ *   - serialize — `bundleRefToString` (`asset-ref.ts`); serializing a
+ *                 `ResolvedRef` always emits the fully-qualified form.
+ *
+ * ── Cycle-safety (HARD constraint) ──
+ *
+ * This is a PURE LEAF. It imports only sibling leaves (`asset-ref`,
+ * `asset-placement`) and the `core/errors` sink — nothing from the indexer-db
+ * SCC and no `Database`/config handle. The resolution surface is INJECTED via
+ * {@link RefContext}; callers build the context from their own db handle /
+ * installation list and hand it in. Keeping the resolver free of I/O is what
+ * lets it stay out of every import cycle.
+ *
+ * ── Input-boundary parser (new-grammar only) ──
+ *
+ * {@link parseRefInput} parses a RAW user/CLI/API ref in the 0.9.0
+ * `[bundle//]conceptId` grammar and returns an {@link AssetRef} value object via
+ * the permanent D-R2 reverse table {@link typeNameFromConceptId}. Post-Chunk-8
+ * every durable ref reaching a reader is already the new grammar, so this is the
+ * ONE ref parser outside the frozen migrator — there is no stored-ref dual
+ * grammar to bridge any more.
+ */
+import { NotFoundError, UsageError } from "../errors.js";
+import { placementSpecFor, stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
+/**
+ * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
+ * against `ctx`, implementing D-R4 exactly:
+ *
+ *   1. Already-qualified input (`bundle//…`) → that bundle (passthrough). When
+ *      `ctx.only` is set and disagrees, that is a not-found (the ref names a
+ *      bundle the caller scoped out).
+ *   2. Short input, `only` set → resolve to `only` iff it contains the concept.
+ *   3. Short input, no `only` → `defaultBundle` if it contains the concept,
+ *      otherwise the FIRST bundle (priority order) that contains it.
+ *   4. No match → {@link NotFoundError} naming the forms tried.
+ *
+ * The `#fragment` is carried through untouched.
+ */
+export function resolveRef(input, ctx) {
+    const ref = typeof input === "string" ? parseBundleRef(input) : input;
+    const { conceptId, fragment } = ref;
+    // 1. Qualified passthrough — an explicit bundle prefix wins.
+    if (ref.bundle !== undefined) {
+        if (ctx.only !== undefined && ref.bundle !== ctx.only) {
+            throw notFound(conceptId, [`${ref.bundle}//${conceptId}`], ctx);
+        }
+        return { bundle: ref.bundle, conceptId, fragment };
+    }
+    // `only` scoping restricts the candidate set to a single bundle.
+    const candidates = ctx.only !== undefined ? ctx.bundles.filter((b) => b.id === ctx.only) : ctx.bundles;
+    // 2/3. defaultBundle wins over priority order for a short ref (but only when
+    // not `only`-scoped; an `only` request never falls back to the default).
+    if (ctx.only === undefined && ctx.defaultBundle !== undefined) {
+        const def = ctx.bundles.find((b) => b.id === ctx.defaultBundle);
+        if (def?.hasConcept(conceptId))
+            return { bundle: def.id, conceptId, fragment };
+    }
+    // First candidate (priority order) that contains the concept.
+    for (const b of candidates) {
+        if (b.hasConcept(conceptId))
+            return { bundle: b.id, conceptId, fragment };
+    }
+    throw notFound(conceptId, [conceptId], ctx);
+}
+function notFound(conceptId, triedForms, ctx) {
+    const scope = ctx.only !== undefined ? ` in bundle "${ctx.only}"` : "";
+    const forms = triedForms.map((f) => `"${f}"`).join(", ");
+    return new NotFoundError(`No bundle contains concept "${conceptId}"${scope} (tried ${forms}).`, "ASSET_NOT_FOUND");
+}
+/**
+ * D-R2 conceptId derivation from an asset `type`/`name` pair
+ * (`stashDirFor(type)/name`; bare name for a foreign type with no placement
+ * stash-subdir). Kept self-contained so {@link displayRef} — a PERMANENT display
+ * rule remains independent of input parsing.
+ *
+ * Exported (Chunk-8 WI-8.5c) as the ONE conceptId derivation the improve
+ * correlation sites (`eligibility.ts` candidate refs, `salience.ts`
+ * last-use lookup, `collapse-detector.ts` canary mint/score) share with the
+ * display rule — the permanent successor to the retired transient
+ * `legacyConceptId`.
+ */
+export function conceptIdFromTypeName(type, name) {
+    const stashDir = stashDirFor(type);
+    return stashDir !== undefined ? `${stashDir}/${name}` : name;
+}
+/**
+ * Build the USER-FACING / envelope ref string for an indexed item, applying the
+ * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
+ * decision D-R2 / D-R3). This is the ONE place the rule lives — every emission
+ * site calls it instead of hand-building a ref from an entry.
+ *
+ * The rule mirrors TODAY'S origin-qualification UX, transposed to the 0.9.0
+ * grammar:
+ *
+ *   - An item in the **default/primary bundle** (`bundleId` undefined, or equal
+ *     to `defaultBundleId`) emits the SHORT conceptId (`knowledge/http-caching`)
+ *     — exactly where the pre-0.9.0 output emitted an un-qualified `type:name`.
+ *   - Any other **non-default bundle** emits the fully-qualified
+ *     `bundle//conceptId`. Post-Chunk-8 every bundle id is a legal slug (the
+ *     config migration assigned each source its D-R5 slug bundle key), so this
+ *     is always the new grammar — a non-slug registryId now displays under its
+ *     derived slug bundle id, never the retired `origin//type:name` spelling.
+ */
+export function displayRef(item, defaultBundleId) {
+    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
+    const { bundleId } = item;
+    // Default/primary bundle → SHORT conceptId (the flip).
+    if (bundleId === undefined || bundleId === defaultBundleId)
+        return conceptId;
+    // Non-default bundle → the new fully-qualified `bundle//conceptId` grammar.
+    return `${bundleId}//${conceptId}`;
+}
+/**
+ * Split a qualified conceptId (`<stash-subdir>/<name>`) into its asset
+ * `type`/`name`, or `undefined` when the leading segment is not a known stash
+ * subdir (a bare-name conceptId from a foreign type — no legacy predicate
+ * applies). The PERMANENT D-R2 reverse table: the input boundary uses it to map
+ * a new-grammar conceptId onto today's {@link AssetRef} shape. (The migrate home
+ * keeps a private transient copy for stored-ref parsing.)
+ */
+export function typeNameFromConceptId(conceptId) {
+    const slash = conceptId.indexOf("/");
+    if (slash <= 0)
+        return undefined;
+    const type = typeForStashDir(conceptId.slice(0, slash));
+    if (type === undefined)
+        return undefined;
+    return { type, name: conceptId.slice(slash + 1) };
+}
+/**
+ * D11 — the opaque-adapter-conceptId fallback. `typeNameFromConceptId` only
+ * ever answers for the PLACEMENT_SPECS stash-resident subset (D-R2); a
+ * conceptId whose leading segment is NOT a registered placement stashDir is
+ * still perfectly legal DATA per D11 — an OKF item (`tables/customers`), a
+ * website page, a wiki pageKind, an adapter `instruction` doc, … — and the
+ * ref-consuming commands must accept it rather than treat "not an AKM
+ * placement dir" as "malformed ref". This function draws the line: it accepts
+ * any well-formed `<segment>/<rest>` conceptId (so the shape is still
+ * anchored — a bare no-slash name stays the caller's job to pre-qualify with a
+ * default type, the existing env/secret/`akm mv` "bare name" convenience), and
+ * REJECTS anything shaped like the retired `type:name` colon grammar (Q-02):
+ * a `:` in the leading segment is that grammar smuggled through a conceptId
+ * string (e.g. `script:db/migrate/run.sh`, `workflow:release/train`), not a
+ * real adapter directory name, so it is refused rather than silently
+ * reinterpreted as opaque data.
+ *
+ * `name` deliberately carries the FULL original conceptId, not just the tail.
+ * This is what makes the pair round-trip through the UNCHANGED
+ * {@link conceptIdFromTypeName} (`stashDirFor(type)/name`, bare `name` when
+ * `type` has no placement stashDir): since an opaque `type` never owns a
+ * placement stashDir, `conceptIdFromTypeName(type, name)` falls to its bare-
+ * `name` branch and returns `name` verbatim — the original conceptId,
+ * unchanged — instead of losing the leading segment. `type` itself carries
+ * the leading segment (informational/behavioral use: `.type === "lesson"`
+ * checks correctly miss for opaque data) UNLESS that segment happens to
+ * collide with a real PLACEMENT_SPECS type key that merely uses a different
+ * stashDir spelling (e.g. a foreign top-level dir literally named "skill",
+ * singular) — that pathological case would make `stashDirFor` succeed on the
+ * "type" and corrupt the round-trip, so it falls back to the full conceptId as
+ * `type` too (never a placement key, since a placement key never contains
+ * `/`).
+ *
+ * This intentionally does NOT collapse the KNOWN_TYPES/PLACEMENT_SPECS split:
+ * `typeNameFromConceptId` (PLACEMENT_SPECS only) is untouched, and an opaque
+ * `type` returned here is never a {@link KnownType} — it is a passthrough
+ * label, not a claim that AKM recognizes or owns the concept.
+ */
+function opaqueRefParts(conceptId, allowRoot = false) {
+    const slash = conceptId.indexOf("/");
+    if (slash <= 0)
+        return allowRoot && !conceptId.includes(":") ? { type: conceptId, name: conceptId } : undefined;
+    const segment = conceptId.slice(0, slash);
+    if (segment.includes(":"))
+        return undefined; // retired `type:name` grammar, not opaque data (Q-02).
+    const type = placementSpecFor(segment) === undefined ? segment : conceptId;
+    return { type, name: conceptId };
+}
+/**
+ * Parse a RAW user / CLI / API ref string in the 0.9.0 `[bundle//]conceptId`
+ * grammar, returning it in today's {@link AssetRef} value-object shape
+ * (ref-grammar decision D-R1 / D-R4). All boundaries are NEW-GRAMMAR ONLY: a
+ * legacy `type:name` input now fails as an unknown-conceptId not-found. Post-
+ * Chunk-8 every durable ref is already the new grammar, so this parser also
+ * serves the (formerly dual-grammar) stored-ref readers.
+ *
+ * Mapping (new grammar → {@link AssetRef}):
+ *   - `conceptId` → `type`/`name` via {@link typeNameFromConceptId} (the D-R2
+ *     static stash-subdir table) when the leading segment is a known AKM
+ *     placement stashDir, else via {@link opaqueRefParts} (D11 — the ref-parser
+ *     seam accepts opaque adapter conceptIds, e.g. OKF items, website pages,
+ *     wiki pageKinds, adapter `instruction` docs) when it is merely a well-
+ *     formed but foreign `<segment>/<rest>` shape. A conceptId that is neither
+ *     — no slash at all, or a retired colon-grammar shape smuggled through —
+ *     has no type predicate: the same not-found outcome a genuine typo
+ *     produces today.
+ *   - `bundle`    → `origin`. A new-grammar bundle slug is a registryId-shaped
+ *     id by construction, so it flows straight into the legacy origin channel
+ *     that `resolveSourcesForOrigin` matches on `registryId`. The SHORT form (no
+ *     bundle) leaves `origin` undefined = search-all-sources.
+ *   - `#fragment` → rejected. No input boundary consumes an export fragment.
+ */
+export function parseRefInput(raw) {
+    const ref = parseBundleRef(raw);
+    if (ref.fragment !== undefined) {
+        throw new UsageError(`Export fragment "#${ref.fragment}" is not accepted here — drop it from "${raw.trim()}".`, "INVALID_FLAG_VALUE");
+    }
+    const parts = typeNameFromConceptId(ref.conceptId) ?? opaqueRefParts(ref.conceptId, ref.bundle !== undefined);
+    if (parts === undefined) {
+        throw new NotFoundError(`Unrecognized asset ref "${raw.trim()}": conceptId "${ref.conceptId}" has no known asset-type prefix.`, "ASSET_NOT_FOUND");
+    }
+    return { type: parts.type, name: parts.name, origin: ref.bundle };
+}
+/**
+ * Parse a CLI/API ref that MAY be qualified by a NON-slug origin — a registry
+ * ref (`github:owner/repo`, `npm:@scope/pkg`, `git:host/path`), a bare path, or
+ * a URL — as its `origin//conceptId` prefix. Such an origin carries `:`/`.`/`/`
+ * so it is not a legal bundle slug and the strict {@link parseRefInput} rejects
+ * it; but it is still a valid SOURCE origin that `resolveSourcesForOrigin`
+ * matches by registry-id / path and the remote-fetch fallback can install. The
+ * conceptId body is parsed under the strict new grammar; the raw origin is kept
+ * as-is — the symmetric input side of {@link displayRef}, which likewise keeps
+ * `origin//…` for exactly these non-slug origins (ref-grammar decision D-R5).
+ *
+ * A short ref (no origin) or a slug-origin ref is delegated verbatim to
+ * {@link parseRefInput}, so this is a safe superset for origin-accepting
+ * commands (`show`, `clone`, `graph`, `history`).
+ */
+export function parseQualifiedRefInput(raw) {
+    const trimmed = raw.trim();
+    const boundary = trimmed.indexOf("//");
+    if (boundary > 0) {
+        const origin = trimmed.slice(0, boundary);
+        if (!isBundleSlug(origin)) {
+            return { ...parseRefInput(trimmed.slice(boundary + 2)), origin };
+        }
+    }
+    return parseRefInput(trimmed);
+}
+/**
+ * Does `raw` already read as a COMPLETE new-grammar asset ref, as opposed to a
+ * bare asset name that a boundary would prefix with a default type (the
+ * `env`/`secret`/`akm mv` "bare name" convenience)?
+ *
+ * True when `raw` is a `[bundle//]conceptId` whose conceptId leads with a KNOWN
+ * stash subdir ({@link typeNameFromConceptId} resolves it). A bare name like
+ * `prod` or `projectA/new-note` is neither — its leading segment maps to no
+ * type — so it stays a bare name for the caller to qualify.
+ */
+export function isFullRefInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return false;
+    try {
+        const parsed = parseBundleRef(trimmed);
+        return parsed.bundle !== undefined || typeNameFromConceptId(parsed.conceptId) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/asset/stash-meta.js

@@ -7,7 +7,7 @@
  * A stash may carry an optional, human-authored `.meta/` directory at its
  * root holding orientation docs for the stash as a whole: purpose, key
  * assets, conventions, maintainer info. Because `.meta/` is a dot-directory,
- * the indexer's walker already skips it (see `src/indexer/walker.ts`), so
+ * the indexer's walker already skips it (see `src/indexer/walk/walker.ts`), so
  * these files never pollute the search corpus. They are surfaced on demand
  * via `akm show [<origin>//]meta[:<name>]`, which direct-reads the file
  * rather than going through the index.
@@ -54,7 +54,7 @@ export function parseMetaRef(ref) {
 }
 /**
  * Reject meta names that would escape the `.meta/` directory. Mirrors the
- * traversal guards in `parseAssetRef`'s `validateName`.
+ * traversal guards in the ref parser's `validateName`.
  */
 function assertSafeMetaName(name) {
     if (name.includes("\0")) {

package/dist/core/bundle-id.js

@@ -0,0 +1,51 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import crypto from "node:crypto";
+import path from "node:path";
+import { isBundleSlug } from "./asset/asset-ref.js";
+/** Deterministic, filesystem-safe bundle slug from a source path. */
+export function slugForPath(sourcePath) {
+    const resolved = path.resolve(sourcePath);
+    const base = path
+        .basename(resolved)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (base.length > 0)
+        return base;
+    return `bundle-${shortHash(resolved)}`;
+}
+/** Derive one batch-unique bundle id. */
+export function deriveBundleId(registryId, sourcePath, usedIds) {
+    const preferred = registryId && registryId.length > 0 && isBundleSlug(registryId) ? registryId : slugForPath(sourcePath);
+    const id = ensureUniqueId(preferred, sourcePath, usedIds);
+    usedIds.add(id);
+    return id;
+}
+/** Derive an ordered batch while reserving every explicit configured bundle id. */
+export function deriveBundleIds(sources) {
+    const usedIds = new Set();
+    const reservedIds = new Set(sources.flatMap((source) => (source.registryId && isBundleSlug(source.registryId) ? [source.registryId] : [])));
+    return sources.map((source) => {
+        const id = source.registryId && isBundleSlug(source.registryId)
+            ? deriveBundleId(source.registryId, source.path, usedIds)
+            : deriveBundleId(undefined, source.path, new Set([...usedIds, ...reservedIds]));
+        usedIds.add(id);
+        return id;
+    });
+}
+function ensureUniqueId(preferred, sourcePath, used) {
+    if (!used.has(preferred))
+        return preferred;
+    const suffixed = `${preferred}-${shortHash(path.resolve(sourcePath))}`;
+    if (!used.has(suffixed))
+        return suffixed;
+    let n = 2;
+    while (used.has(`${suffixed}-${n}`))
+        n++;
+    return `${suffixed}-${n}`;
+}
+function shortHash(input) {
+    return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}