rcf-lite 0.13.0 → 0.15.0

package/src/blueprint/library-registry.js

@@ -0,0 +1,341 @@
+// Project-config external-library registry, at
+// `rcf/blueprint-libraries.json`. Written and read only by the
+// `rcf define blueprint library` verb family; the manifest walker does
+// not touch it (per spec 4.1 rationale: adding a required cross-cutting
+// section into `manifest.json` ripples through every downstream
+// validator, so the registry sits as a discrete file next to the
+// manifest, exactly like `rcf/.identity/` sits next to it).
+//
+// Phase 2b (this file) covers registry CRUD + band-overlap gates.
+// Phase 2c layers the network fetchers on top and populates the
+// `resolvedSha` / `tarballSha256` provenance fields; a `local` source
+// bypasses both and carries a `local` provenance tag.
+//
+// Spec: external-blueprint-libraries-spec-2026-08-31.md sections 4, 7, 8.3.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { rcfError } from '../core/errors/index.js';
+
+export const REGISTRY_VERSION = 1;
+export const REGISTRY_PATH = 'rcf/blueprint-libraries.json';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// packages/rcf-lite/src/blueprint -> packages/rcf-lite -> data/
+const CORE_BAND_RESERVATIONS_PATH = join(here, '..', '..', 'data', 'core-band-reservations.json');
+
+/**
+ * @typedef {object} RegistryEntry
+ * @property {string} libraryPrefix
+ * @property {'local' | 'git' | 'tarball'} sourceKind
+ * @property {string} sourceRef
+ * @property {string} [resolvedSha]
+ * @property {string} displayName
+ * @property {{ id: string, displayName: string, contact?: string }} publisher
+ * @property {string} libraryRef
+ * @property {{ ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> }} bands
+ * @property {Array<{ slug: string, path: string }>} [blueprints]
+ *   Snapshot of the library's `blueprints[]` at add-time. The resolver
+ *   consults this to locate a blueprint by slug without re-reading
+ *   `library.json` on every `blueprint add`. Absent snapshot falls back
+ *   to the conventional `blueprints/<slug>/` layout (see shelf-resolver
+ *   findBlueprintEntry).
+ * @property {string} addedAt              RFC 3339
+ * @property {'operator'} reviewedBy
+ * @property {{ tier: 'local' | 'git' | 'tarball', shaVerifiedAt?: string, tarballSha256?: string }} provenance
+ * @property {string} cachePath
+ */
+
+/**
+ * @typedef {object} LibraryRegistry
+ * @property {number} registryVersion
+ * @property {RegistryEntry[]} libraries
+ */
+
+/**
+ * Read the registry from a project. Absent file is not an error: a
+ * project that has never added a library returns an empty registry.
+ *
+ * @param {string} projectRoot - absolute path
+ * @returns {Promise<LibraryRegistry | import('../core/errors/index.js').RcfError>}
+ */
+export async function readLibraryRegistry(projectRoot) {
+  const path = join(projectRoot, REGISTRY_PATH);
+  if (!existsSync(path)) {
+    return { registryVersion: REGISTRY_VERSION, libraries: [] };
+  }
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `library registry: read failed: ${err.message}`, filePath: path });
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return rcfError({ kind: 'parseFailure', message: `library registry: JSON parse failed: ${err.message}`, filePath: path });
+  }
+  const err = validateRegistryShape(doc, path);
+  if (err) return err;
+  return doc;
+}
+
+/**
+ * Persist a registry to disk. Overwrites the whole file (registry
+ * writes are always full-file for legibility; the file is small).
+ *
+ * @param {string} projectRoot
+ * @param {LibraryRegistry} registry
+ * @param {object} [opts]
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{ written: boolean, path: string } | import('../core/errors/index.js').RcfError>}
+ */
+export async function writeLibraryRegistry(projectRoot, registry, opts = {}) {
+  const path = join(projectRoot, REGISTRY_PATH);
+  const err = validateRegistryShape(registry, path);
+  if (err) return err;
+  if (opts.dryRun === true) return { written: false, path };
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  } catch (writeErr) {
+    return rcfError({ kind: 'ioFailure', message: `library registry: write failed: ${writeErr.message}`, filePath: path });
+  }
+  return { written: true, path };
+}
+
+/**
+ * @param {LibraryRegistry} registry
+ * @param {string} libraryPrefix
+ * @returns {RegistryEntry | undefined}
+ */
+export function findLibrary(registry, libraryPrefix) {
+  if (!registry || !Array.isArray(registry.libraries)) return undefined;
+  return registry.libraries.find((l) => l.libraryPrefix === libraryPrefix);
+}
+
+/**
+ * Load the core-shelf band reservations shipped alongside rcf-lite.
+ * Read-through with cache would be fine, but the file is tiny so we
+ * re-read on demand; keeps tests hermetic against a stale singleton.
+ *
+ * @param {string} [dataFilePath] - override for tests
+ * @returns {Promise<{ ac: Array<{ blueprint: string, start: number, end: number }>, suffixBlocks: Array<{ blueprint: string, kind: string, start: number, end: number }> }>}
+ */
+export async function loadCoreBandReservations(dataFilePath = CORE_BAND_RESERVATIONS_PATH) {
+  try {
+    const raw = await readFile(dataFilePath, 'utf8');
+    const doc = JSON.parse(raw);
+    return {
+      ac: Array.isArray(doc.ac) ? doc.ac : [],
+      suffixBlocks: Array.isArray(doc.suffixBlocks) ? doc.suffixBlocks : [],
+    };
+  } catch {
+    return { ac: [], suffixBlocks: [] };
+  }
+}
+
+/**
+ * Add-time band-overlap gate. Refuses when the candidate library's
+ * declared bands (`ac`, `suffixBlocks[]`) overlap either an
+ * already-registered library or a core-shelf reservation.
+ *
+ * @param {object} args
+ * @param {{ libraryPrefix: string, bands: { ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> } }} args.candidate
+ * @param {LibraryRegistry} args.registry
+ * @param {{ ac: Array<{ blueprint: string, start: number, end: number }>, suffixBlocks: Array<{ blueprint: string, kind: string, start: number, end: number }> }} args.coreReservations
+ * @returns {null | import('../core/errors/index.js').RcfError}
+ */
+export function detectBandOverlap({ candidate, registry, coreReservations }) {
+  // AC band: check against every registered library and every core row.
+  const cand = candidate.bands.ac;
+  for (const reg of registry.libraries) {
+    if (reg.libraryPrefix === candidate.libraryPrefix) continue;
+    if (rangesOverlap(cand, reg.bands.ac)) {
+      return rcfError({
+        kind: 'usage',
+        message: `AC band ${cand.start}-${cand.end} overlaps registered library '${reg.libraryPrefix}' (${reg.bands.ac.start}-${reg.bands.ac.end}).`,
+      });
+    }
+  }
+  for (const core of coreReservations.ac) {
+    if (rangesOverlap(cand, core)) {
+      return rcfError({
+        kind: 'usage',
+        message: `AC band ${cand.start}-${cand.end} overlaps core-shelf blueprint '${core.blueprint}' (${core.start}-${core.end}).`,
+      });
+    }
+  }
+  // Suffix blocks: per-kind overlap.
+  const suffixBlocks = candidate.bands.suffixBlocks ?? [];
+  for (const block of suffixBlocks) {
+    for (const reg of registry.libraries) {
+      if (reg.libraryPrefix === candidate.libraryPrefix) continue;
+      for (const other of reg.bands.suffixBlocks ?? []) {
+        if (other.kind === block.kind && rangesOverlap(block, other)) {
+          return rcfError({
+            kind: 'usage',
+            message: `suffix block ${block.kind} ${block.start}-${block.end} overlaps registered library '${reg.libraryPrefix}' (${other.start}-${other.end}).`,
+          });
+        }
+      }
+    }
+    for (const core of coreReservations.suffixBlocks) {
+      if (core.kind === block.kind && rangesOverlap(block, core)) {
+        return rcfError({
+          kind: 'usage',
+          message: `suffix block ${block.kind} ${block.start}-${block.end} overlaps core-shelf blueprint '${core.blueprint}' (${core.start}-${core.end}).`,
+        });
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Apply-time band gate (spec section 8.3 + open question 9.9 ratified
+ * as "add both"). Every contribution id whose numeric portion falls
+ * outside the library's declared band is refused, so a library that
+ * grew a blueprint outside its declared band (that its own CI should
+ * have caught but did not) refuses at the consuming project's `blueprint
+ * add`.
+ *
+ * @param {Array<{ id: string, kind: string }>} stampedContributions
+ * @param {{ ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> }} bands
+ * @returns {null | import('../core/errors/index.js').RcfError}
+ */
+export function detectContributionsOutOfBand(stampedContributions, bands) {
+  for (const c of stampedContributions) {
+    const parts = extractNumericPart(c.id);
+    if (!parts) continue;
+    if (c.kind === 'req' || c.kind === 'us' || c.kind === 'ts') {
+      if (!inRange(parts.number, bands.ac)) {
+        return rcfError({
+          kind: 'usage',
+          message: `contribution ${c.id} (${c.kind}) numeric ${parts.number} falls outside library AC band ${bands.ac.start}-${bands.ac.end}.`,
+        });
+      }
+    } else if (c.kind === 'adr' || c.kind === 'tac') {
+      const blocks = (bands.suffixBlocks ?? []).filter((b) => b.kind === c.kind);
+      if (blocks.length === 0) continue; // no block declared for this kind
+      const hit = blocks.some((b) => inRange(parts.number, b));
+      if (!hit) {
+        const desc = blocks.map((b) => `${b.start}-${b.end}`).join(', ');
+        return rcfError({
+          kind: 'usage',
+          message: `contribution ${c.id} (${c.kind}) numeric ${parts.number} falls outside library ${c.kind} suffix block(s) ${desc}.`,
+        }); // library-facing prefix is added by the CLI edge
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Prefix-collision gate for `library add` (spec section 5.1). Refuses
+ * when the candidate `libraryPrefix` collides with a core-shelf
+ * blueprint slug or with any already-registered library's prefix.
+ *
+ * @param {object} args
+ * @param {string} args.libraryPrefix
+ * @param {LibraryRegistry} args.registry
+ * @param {string[]} args.coreSlugs
+ * @returns {null | import('../core/errors/index.js').RcfError}
+ */
+export function detectPrefixCollision({ libraryPrefix, registry, coreSlugs }) {
+  if (libraryPrefix.includes(':') || libraryPrefix.includes('/')) {
+    return rcfError({ kind: 'usage', message: `library add: libraryPrefix '${libraryPrefix}' must not contain ':' or '/'.` });
+  }
+  for (const slug of coreSlugs) {
+    if (slug === libraryPrefix) {
+      return rcfError({ kind: 'usage', message: `library add: libraryPrefix '${libraryPrefix}' collides with core-shelf blueprint slug '${slug}'.` });
+    }
+    if (slug.startsWith(`${libraryPrefix}-`)) {
+      return rcfError({
+        kind: 'usage',
+        message: `libraryPrefix '${libraryPrefix}' is a boundary-swallowing substring prefix of core-shelf blueprint slug '${slug}'; choose a prefix that does not read as the leading segment of an existing slug.`,
+      });
+    }
+  }
+  for (const reg of registry.libraries) {
+    if (reg.libraryPrefix === libraryPrefix) {
+      return rcfError({ kind: 'usage', message: `library add: libraryPrefix '${libraryPrefix}' is already registered.` });
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the leading numeric block from an id like `wsd-auth-oauth2-REQ-1101`
+ * or `ADR-1300-deploy-cloudflare-workers`. Returns `{ number }` or null.
+ * We do NOT reimplement the id grammar here; the numeric portion of
+ * either family shape is unambiguous: the run of digits between two
+ * hyphens or between a hyphen and the string end.
+ */
+function extractNumericPart(id) {
+  const m = /-(\d+)(?:-|$)/.exec(id);
+  if (!m) return null;
+  return { number: Number(m[1]) };
+}
+
+function inRange(n, range) {
+  return n >= range.start && n <= range.end;
+}
+
+function rangesOverlap(a, b) {
+  return !(a.end < b.start || b.end < a.start);
+}
+
+function validateRegistryShape(doc, path) {
+  if (typeof doc !== 'object' || doc === null) {
+    return rcfError({ kind: 'validation', message: 'library registry: must be a JSON object', filePath: path });
+  }
+  if (!Number.isInteger(doc.registryVersion) || doc.registryVersion < 1) {
+    return rcfError({ kind: 'validation', message: `library registry: registryVersion must be a positive integer, got ${JSON.stringify(doc.registryVersion)}`, filePath: path });
+  }
+  if (doc.registryVersion > REGISTRY_VERSION) {
+    return rcfError({ kind: 'validation', message: `library registry: registryVersion ${doc.registryVersion} is newer than this CLI understands (max ${REGISTRY_VERSION}); upgrade rcf-lite.`, filePath: path });
+  }
+  if (!Array.isArray(doc.libraries)) {
+    return rcfError({ kind: 'validation', message: 'library registry: libraries[] is required (may be empty)', filePath: path });
+  }
+  const seen = new Set();
+  for (const [i, entry] of doc.libraries.entries()) {
+    if (typeof entry !== 'object' || entry === null) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}] must be an object`, filePath: path });
+    }
+    if (typeof entry.libraryPrefix !== 'string') {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].libraryPrefix is required`, filePath: path });
+    }
+    if (seen.has(entry.libraryPrefix)) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].libraryPrefix '${entry.libraryPrefix}' is declared more than once`, filePath: path });
+    }
+    seen.add(entry.libraryPrefix);
+    if (!['local', 'git', 'tarball'].includes(entry.sourceKind)) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].sourceKind '${entry.sourceKind}' must be one of local|git|tarball`, filePath: path });
+    }
+    if (typeof entry.sourceRef !== 'string' || entry.sourceRef.length === 0) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].sourceRef is required`, filePath: path });
+    }
+    if (typeof entry.cachePath !== 'string' || entry.cachePath.length === 0) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].cachePath is required`, filePath: path });
+    }
+    if (typeof entry.bands !== 'object' || entry.bands === null || typeof entry.bands.ac !== 'object' || entry.bands.ac === null) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].bands.ac is required`, filePath: path });
+    }
+    if (typeof entry.provenance !== 'object' || entry.provenance === null || !['local', 'git', 'tarball'].includes(entry.provenance.tier)) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].provenance.tier is required (local|git|tarball)`, filePath: path });
+    }
+    if (entry.provenance.tier !== 'local' && !entry.provenance.shaVerifiedAt) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].provenance.shaVerifiedAt is required when tier is '${entry.provenance.tier}'`, filePath: path });
+    }
+    if (entry.sourceKind === 'local' && entry.resolvedSha !== undefined) {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}] sourceKind=local must not carry a resolvedSha`, filePath: path });
+    }
+  }
+  return null;
+}

package/src/blueprint/list.js

@@ -11,7 +11,11 @@
 // as `category: null` so grouped rendering can place it under an
 // uncategorised heading rather than swallow the row.
 
+import { isAbsolute } from 'node:path';
+
+import { isRcfError } from '../core/errors/index.js';
 import { loadBlueprint } from './loader.js';
+import { resolveBlueprintSource } from './shelf-resolver.js';
 
 /**
  * @param {import('#core/store/walker.js').TreeModel} tree
@@ -37,17 +41,37 @@ export function listBlueprints(tree) {
  * `category: null` so the caller can render the row under an
  * uncategorised group rather than skip it.
  *
+ * A row's `source` may be a non-path token in two ratified cases: an
+ * external-library colon ref (`wsd:auth-oauth2`, spec §5.3) and, on
+ * legacy manifests pre-#128, bare shelf sugar (`application-spa`).
+ * Both re-resolve through `resolveBlueprintSource` against `projectRoot`
+ * before we hand a filesystem path to the loader; without this every
+ * such row would render under `uncategorised` (integration review
+ * d-2026-08-31-046).
+ *
  * @param {ReturnType<typeof listBlueprints>} rows
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot] - absolute path to the project root.
+ *   Required to re-resolve library colon refs and bare shelf slugs.
+ *   Absolute-path sources still work when omitted (they need no
+ *   re-resolution), so tests that only exercise absolute paths keep
+ *   their existing single-argument shape.
  * @returns {Promise<Array<{ slug: string, version: string, appliedAt: string, source: string, namespace: string | null, contributionCount: number, category: string | null }>>}
  */
-export async function enrichRowsWithCategories(rows) {
+export async function enrichRowsWithCategories(rows, opts = {}) {
+  const projectRoot = typeof opts.projectRoot === 'string' && opts.projectRoot.length > 0
+    ? opts.projectRoot
+    : null;
   const out = [];
   for (const row of rows) {
     let category = null;
     if (typeof row.source === 'string' && row.source.length > 0) {
-      const loaded = await loadBlueprint(row.source);
-      if (!loaded.kind && typeof loaded.category === 'string') {
-        category = loaded.category;
+      const sourceAbs = await resolveSourceForList(row.source, projectRoot);
+      if (sourceAbs !== null) {
+        const loaded = await loadBlueprint(sourceAbs);
+        if (!loaded.kind && typeof loaded.category === 'string') {
+          category = loaded.category;
+        }
       }
     }
     out.push({ ...row, category });
@@ -55,6 +79,16 @@ export async function enrichRowsWithCategories(rows) {
   return out;
 }
 
+async function resolveSourceForList(source, projectRoot) {
+  if (isAbsolute(source)) return source;
+  if (projectRoot === null) return null;
+  const resolved = await resolveBlueprintSource(source, { projectRoot }).catch(() => null);
+  if (resolved && !isRcfError(resolved) && typeof resolved.resolved === 'string') {
+    return resolved.resolved;
+  }
+  return null;
+}
+
 /**
  * Group category-enriched rows by category. Preserves appliedAt order
  * within each group. Categories are returned sorted alphabetically;

package/src/blueprint/shelf-resolver.js

@@ -1,26 +1,38 @@
 // Resolve a `rcf define blueprint add <source>` argument to an absolute
 // blueprint directory.
 //
-// Resolution order (Phase 1; the phase-2 external-library registry
-// layers on top of this without reworking the CLI):
+// Resolution order (Phase 1 + Phase 2b external-library registry;
+// see external-blueprint-libraries-spec-2026-08-31.md section 5.2 for
+// the ratified spec text):
 //
-//   1. Any argument that names a filesystem location - starts with `./`,
+//   1. `@stock/<slug>` is reserved for the packaged shelf. The `@stock/`
+//      qualifier strips off and the bare slug resolves against the
+//      packaged shelf. This is the recommended long-form.
+//   2. Any other `@<library>/<slug>` (slash form) is rejected. The
+//      ratified qualified surface (spec §9.2) is COLON-separated
+//      (`<libraryPrefix>:<slug>`); the slash form is a reserved
+//      non-canonical shape and the refusal message points at the colon
+//      form so the operator sees the right invocation.
+//   3. `<libraryPrefix>:<slug>` (colon form) is the qualified external-
+//      library reference (spec §5.2 step 1). The segment before the
+//      colon must match a `libraryPrefix` in the project registry at
+//      `rcf/blueprint-libraries.json`; the resolver expands to
+//      `<library-cache>/blueprints/<segment-after-colon>` and returns
+//      an `effectiveSlug` (`<libraryPrefix>-<slug>`) plus the library
+//      prefix so the apply layer can stamp the qualified identity on
+//      contributions and the applied-blueprint record.
+//   4. Any argument that names a filesystem location - starts with `./`,
 //      `../`, `/`, or `~`, or contains a path separator, or names an
 //      existing directory - is treated as a PATH and returned unchanged.
 //      This preserves the existing local / relative-path semantic every
 //      test and existing operator invocation relies on.
-//   2. `@stock/<slug>` is reserved for the packaged shelf. The `@stock/`
-//      qualifier strips off and the bare slug resolves against the
-//      packaged shelf. This is the recommended long-form.
-//   3. Any other bare kebab slug (`deploy-cloudflare-workers`,
+//   5. Any other bare kebab slug (`deploy-cloudflare-workers`,
 //      `application-spa`) resolves against the packaged shelf. This is
 //      the sugar the persona reviews asked for; it means the docs and
 //      the CLI say the same thing.
-//   4. A slug qualifier that names a KNOWN external-library alias other
-//      than `@stock` is rejected with a clear message pointing the
-//      operator at the current phase-1 capabilities. This reservation
-//      keeps the phase-2 external-libraries mechanism free to land the
-//      registry surface later without a breaking rename.
+//   6. Anything that has slipped through here falls through as a path
+//      so the loader's own "no blueprint.json found" error names the
+//      exact string the operator typed.
 //
 // The packaged shelf lives at `<packageRoot>/blueprints/<slug>/` - the
 // tarball is built with `files: [ "blueprints" ]` and a `prepack`
@@ -33,6 +45,7 @@ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { rcfError } from '../core/errors/index.js';
+import { findLibrary, readLibraryRegistry } from './library-registry.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 // packages/rcf-lite/src/blueprint -> packages/rcf-lite
@@ -41,27 +54,50 @@ const PACKAGED_SHELF = join(PACKAGE_ROOT, 'blueprints');
 
 const KEBAB_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const QUALIFIED = /^@([a-z][a-z0-9-]*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
+// Colon-form qualified reference: <libraryPrefix>:<blueprintSlug>. Both
+// sides are kebab slugs (per spec §5.1 / §5.2). Grammar matches the
+// blueprintSlug pattern on each side.
+const COLON_QUALIFIED = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*):([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
 
 const PATH_HINT = /[\\/]|^~|^\./;
 
 /**
  * @typedef {object} ResolvedSource
- * @property {'path' | 'shelf'} kind
+ * @property {'path' | 'shelf' | 'library'} kind
  *   `path` if the argument was treated as a filesystem path (unchanged);
  *   `shelf` if a bare slug or `@stock/<slug>` was resolved against the
- *   packaged shelf. The apply.js layer treats both the same once resolved -
- *   both are absolute directory paths - but the kind is exposed for the
- *   CLI's future diagnostics (`--dry-run` labelling, etc.).
+ *   packaged shelf; `library` if a colon-qualified `<libraryPrefix>:<slug>`
+ *   was resolved through the project registry to an external-library
+ *   blueprint directory. The apply.js layer treats every kind the same
+ *   once resolved (all are absolute directory paths); the kind is
+ *   exposed for the CLI's diagnostics and (for `library`) so the apply
+ *   layer can pick up the `effectiveSlug` and `libraryPrefix`.
  * @property {string} resolved  Absolute path suitable for `applyBlueprint({ source })`.
  * @property {string} original  The argument the operator typed, preserved for
- *   diagnostics and the conflict-renderer's supersede hint.
- * @property {string} [slug]    The bare slug when resolution went through the shelf.
+ *   diagnostics, the conflict-renderer's supersede hint, and (for
+ *   `library`) as the qualified ref written into `manifest.blueprints[].source`.
+ * @property {string} [slug]           The bare slug when resolution went through the shelf.
+ * @property {string} [libraryPrefix]  The library prefix when resolution went through the registry.
+ * @property {string} [libraryBlueprintSlug]
+ *                                     The blueprint's own bare slug inside the library.
+ * @property {string} [effectiveSlug]  `<libraryPrefix>-<libraryBlueprintSlug>` when
+ *                                     kind is `library` (spec §5.3); the value the
+ *                                     apply layer stamps as both the blueprint's
+ *                                     namespace and the applied record's `slug`.
+ * @property {{ ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> }} [libraryBands]
+ *                                     The library's declared bands, forwarded so the
+ *                                     apply-time gate can refuse contributions that
+ *                                     fall outside them.
  */
 
 /**
  * @param {string} source - argument as typed by the operator
  * @param {object} [opts]
  * @param {string} [opts.packagedShelf] - override for tests
+ * @param {string} [opts.projectRoot]   - project root for registry lookups.
+ *   When omitted, colon-qualified sources refuse with a "no registry
+ *   context" error. Callers apply-time (CLI, MCP) always supply this;
+ *   test callers that only exercise the shelf paths may omit it.
  * @returns {Promise<ResolvedSource | import('../core/errors/index.js').RcfError>}
  */
 export async function resolveBlueprintSource(source, opts = {}) {
@@ -70,11 +106,11 @@ export async function resolveBlueprintSource(source, opts = {}) {
   }
   const packagedShelf = opts.packagedShelf ?? PACKAGED_SHELF;
 
-  // Rule 2 / 4 FIRST: qualified `@lib/slug` forms carry a `/` that
+  // Rule 1 / 2 FIRST: qualified `@lib/slug` forms carry a `/` that
   // would otherwise trip the path-hint check below. `@stock/<slug>`
-  // resolves to the packaged shelf; any other library qualifier is
-  // reserved for the phase-2 external-libraries mechanism and refuses
-  // with a clear message.
+  // resolves to the packaged shelf; every other slash form is the
+  // non-canonical shape and refuses, pointing at the ratified colon
+  // form (spec §9.2).
   const qualified = QUALIFIED.exec(source);
   if (qualified) {
     const [, library, slug] = qualified;
@@ -84,13 +120,30 @@ export async function resolveBlueprintSource(source, opts = {}) {
     return rcfError({
       kind: 'usage',
       message: (
-        `blueprint source '${source}' names external library '@${library}', which is reserved for the phase-2 external-libraries mechanism and not resolvable yet. `
-        + 'Use `@stock/<slug>` for the packaged shelf, a local path (`./path/to/blueprint`), or wait for the external-library registry.'
+        `blueprint source '${source}' uses the slash-qualified '@<library>/<slug>' shape, which is not the ratified external-library reference form. `
+        + `Use the colon form '${library}:${slug}' after registering the library with 'rcf define blueprint library add <ref>', or '@stock/<slug>' for the packaged shelf.`
       ),
     });
   }
 
-  // Rule 1: path-looking arguments are passed through unchanged. We look
+  // Rule 3: colon-qualified `<libraryPrefix>:<slug>` is the ratified
+  // external-library reference (spec §5.2). We check before the path
+  // hint because the colon-form is unambiguous: a colon is not a
+  // filesystem separator on any platform we target, and the kebab
+  // grammar on both sides rules out an accidental match with, for
+  // example, a Windows drive letter (`C:\path`, uppercase, backslash).
+  const colon = COLON_QUALIFIED.exec(source);
+  if (colon) {
+    const [, libraryPrefix, blueprintSlug] = colon;
+    return resolveLibraryQualified({
+      libraryPrefix,
+      blueprintSlug,
+      original: source,
+      projectRoot: opts.projectRoot,
+    });
+  }
+
+  // Rule 4: path-looking arguments are passed through unchanged. We look
   // at the SHAPE only (does it contain a separator, does it start with a
   // relative-path marker, is it absolute), so an existing operator with a
   // `./blueprints/foo` invocation keeps the current behaviour byte-for-byte.
@@ -98,19 +151,79 @@ export async function resolveBlueprintSource(source, opts = {}) {
     return { kind: 'path', resolved: resolve(source), original: source };
   }
 
-  // Rule 3: any other bare kebab token is a shelf slug.
+  // Rule 5: any other bare kebab token is a shelf slug.
   if (KEBAB_SLUG.test(source)) {
     return resolveShelfSlug(source, source, packagedShelf);
   }
 
-  // Anything that has slipped through here is neither a path, nor a
-  // qualified library slug, nor a bare kebab slug. Treat it as a path so
-  // the loader emits the familiar "no blueprint.json found" error against
-  // the exact string the operator typed; that keeps the failure locus
-  // close to what they wrote rather than adding a resolver-specific class.
+  // Rule 6: anything that has slipped through here is neither a path,
+  // nor a qualified library slug, nor a bare kebab slug. Treat it as a
+  // path so the loader emits the familiar "no blueprint.json found"
+  // error against the exact string the operator typed; that keeps the
+  // failure locus close to what they wrote rather than adding a
+  // resolver-specific class.
   return { kind: 'path', resolved: resolve(source), original: source };
 }
 
+async function resolveLibraryQualified({ libraryPrefix, blueprintSlug, original, projectRoot }) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return rcfError({
+      kind: 'usage',
+      message: `blueprint source '${original}' uses the qualified library form but the resolver was called without a projectRoot; the registry at rcf/blueprint-libraries.json cannot be located.`,
+    });
+  }
+  const registry = await readLibraryRegistry(projectRoot);
+  if (registry.kind) return registry; // RcfError
+  const entry = findLibrary(registry, libraryPrefix);
+  if (!entry) {
+    const known = registry.libraries.map((l) => l.libraryPrefix);
+    const hint = known.length > 0
+      ? ` Registered libraries: ${known.join(', ')}.`
+      : ' No libraries are registered on this project; run `rcf define blueprint library add <ref>` first.';
+    return rcfError({
+      kind: 'usage',
+      message: `blueprint source '${original}' names library '${libraryPrefix}' which is not registered on this project.${hint}`,
+    });
+  }
+  const libraryRoot = isAbsolute(entry.cachePath) ? entry.cachePath : join(projectRoot, entry.cachePath);
+  const bpEntry = findBlueprintEntry(entry, blueprintSlug);
+  if (!bpEntry) {
+    return rcfError({
+      kind: 'usage',
+      message: `blueprint source '${original}': library '${libraryPrefix}' has no blueprint with slug '${blueprintSlug}' in its registered manifest snapshot; the operator may need to re-run 'rcf define blueprint library add <ref>' to pick up a newer library.`,
+    });
+  }
+  const resolved = join(libraryRoot, bpEntry.path);
+  if (!existsSync(resolved)) {
+    return rcfError({
+      kind: 'usage',
+      message: `blueprint source '${original}': library '${libraryPrefix}' blueprint '${blueprintSlug}' resolved to ${resolved} but that path is missing. Run 'rcf define blueprint library refresh ${libraryPrefix}'.`,
+      filePath: resolved,
+    });
+  }
+  return {
+    kind: 'library',
+    resolved,
+    original,
+    libraryPrefix,
+    libraryBlueprintSlug: blueprintSlug,
+    effectiveSlug: `${libraryPrefix}-${blueprintSlug}`,
+    libraryBands: entry.bands,
+  };
+}
+
+function findBlueprintEntry(entry, blueprintSlug) {
+  // Registry entries snapshot the library's blueprints[] at add time
+  // (spec §4.2); the snapshot is what the resolver consults. When the
+  // snapshot is absent (a future registry-version compatibility case),
+  // fall through and let the on-disk library dictate the layout by
+  // relying on the conventional blueprints/<slug>/ path.
+  if (!Array.isArray(entry.blueprints)) {
+    return { slug: blueprintSlug, path: `blueprints/${blueprintSlug}` };
+  }
+  return entry.blueprints.find((b) => b.slug === blueprintSlug);
+}
+
 async function resolveShelfSlug(slug, original, packagedShelf) {
   const candidate = join(packagedShelf, slug);
   if (!existsSync(candidate)) {