dreamteamer 0.6.4 → 0.7.0

package/src/compile.js

@@ -8,8 +8,11 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { load, dump } from './yaml.js';
 import { slug } from './template.js';
-import { walk } from './records.js';
+import { walk, patternRe } from './records.js';
 import { unknownOperators } from './filter.js';
+import {
+	normalizeNamespaces, namespaceProblems, unqualifiedProblems, defaultStoragePath, storageOverlaps,
+} from './namespace.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
 import { runHarnessAdapters } from './harnesses.js';
@@ -387,7 +390,18 @@ export function compile({ root, pkg }) {
 			const srcDir = kindDir(source.root, kind);
 			if (!fs.existsSync(srcDir)) continue;
 			counts[kind] ??= 0;
-			for (const name of fs.readdirSync(srcDir).sort()) {
+			// `collections/` is enumerated RECURSIVELY, so a namespaced descriptor can be authored at
+			// `collections/health/doctors.collection.yaml` — mirroring where it lands in the runtime and
+			// letting a workspace group its descriptors the same way its data is grouped.
+			//
+			// ⚠ This is load-bearing, not cosmetic. `schema-ops` derives a descriptor's source path from
+			// its name, so `add-field` on `health/doctors` writes the nested path; with a flat readdir
+			// that file was written, silently skipped, and the verb reported ✔ while changing nothing —
+			// the decision-156 shape again. Every other kind stays flat: their ids are single segments.
+			const names = kind === 'collections'
+				? [...walk(srcDir)].map((f) => path.relative(srcDir, f).split(path.sep).join('/'))
+				: fs.readdirSync(srcDir).sort();
+			for (const name of names) {
 				if (name.startsWith('.')) continue;
 				const entityId = name.replace(/\.[^.]+\.(yaml|md|json)$/, '');
 				if (disabled.has(`${source.name}/${entityId}`)) { disabledHits.add(`${source.name}/${entityId}`); continue; }
@@ -478,6 +492,21 @@ export function compile({ root, pkg }) {
 		templateDocs.set(m[1], { template: doc.template ?? {}, src: entry.sources[0] });
 	}
 
+	// ---- namespaces: the declared list, validated against what actually compiled ----------
+	// Declared in the WORKSPACE package.json only, never per-module. A module that could declare a
+	// namespace could rename where another module's records live, and the whole point of a namespace
+	// is that the workspace decides how its own data is partitioned. `namespaces` is also config
+	// rather than records for the same bootstrap reason `git-modules` is (docs/repos-and-modules.md):
+	// a reference has to be parseable before anything has been compiled.
+	const namespaces = normalizeNamespaces(config.namespaces);
+	const collectionNames = [...descriptorGroups.keys()];
+	for (const p of namespaceProblems(namespaces, collectionNames)) fail(p);
+	// The silent failure this whole feature had to fix: a slash in a collection name used to compile
+	// clean, land at `.dreamteamer/collections/<ns>/<name>.collection.yaml`, and then vanish — the
+	// descriptor loader read one directory level, so the collection was simply absent from the
+	// runtime while compile reported ✔ (the same shape as decision 156).
+	for (const p of unqualifiedProblems(collectionNames, namespaces)) fail(p);
+
 	// ---- who owns which collection, and which module IS the workspace ----------------
 	// Needed before the resolution loop so each descriptor can be validated against the graph as it
 	// is merged. The owner is the group member that does NOT declare `extends`; a group with two of
@@ -504,6 +533,7 @@ export function compile({ root, pkg }) {
 	counts.collections = 0;
 	let mergedCount = 0;
 	let templatedCount = 0;
+	const storageEntries = []; // {name, path, base} per collection — checked for overlap after the loop
 	for (const [name, group] of descriptorGroups) {
 		// a template's bytes feed the compiled descriptor, so it MUST be one of that descriptor's
 		// declared sources — otherwise editing the template leaves every consumer silently stale
@@ -555,6 +585,12 @@ export function compile({ root, pkg }) {
 		// the workspace root, read as zero records, and become writable through the store.
 		merged.storage ??= {};
 		const owned = dataOwners.get(storageOwnerOf(group, base));
+		// A namespaced collection's folder IS its namespace, nested: `health/doctors` →
+		// `data/health/doctors`. Derived rather than required so a descriptor never has to repeat its
+		// own name in a path, and so moving a collection between namespaces is a one-line edit.
+		// An authored `storage.path` still wins — registering an existing folder is a first-class case
+		// (skills/building-dreamteamer/references/collections.md).
+		merged.storage.path ??= defaultStoragePath(name, namespaces, config['data-path'] ?? 'data');
 		const storagePath = String(merged.storage.path ?? '');
 		const systemKinds = [...KINDS, ...DERIVED_KINDS];
 		const isSystem = systemKinds.includes(storagePath) || systemKinds.includes(storagePath.replace(/^system\//, ''));
@@ -566,6 +602,7 @@ export function compile({ root, pkg }) {
 		} else {
 			merged.storage.repo = '.';
 		}
+		storageEntries.push({ name, path: merged.storage.path, base: merged.storage.base });
 		for (const [at, tpl, target] of staleDisplayKeywords(merged.schema)) {
 			const fix = target
 				? `either DELETE it (a reference to "${target}" now inherits that collection's \`title_template\`) or rename it to \`x-title-template\` if this field really needs its own`
@@ -580,6 +617,16 @@ export function compile({ root, pkg }) {
 		} catch (e) {
 			fail(`collection "${name}": schema is not a valid JSON Schema — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
 		}
+		// Same reasoning one line up, for the OTHER regex a descriptor carries. `patternRe` throws on a
+		// malformed pattern, and it is called from `store.add` and from `check` — so without this gate a
+		// typo'd `id.pattern` surfaces as a raw "Invalid regular expression" from inside a write instead
+		// of as a compile error naming the descriptor.
+		if (merged.id?.pattern !== undefined) {
+			if (typeof merged.id.pattern !== 'string') fail(`collection "${name}": id.pattern must be a string (got ${JSON.stringify(merged.id.pattern)})`);
+			try { patternRe(merged.id.pattern); } catch (e) {
+				fail(`collection "${name}": id.pattern is not a valid regular expression — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
+			}
+		}
 		// ---- the reference contract: every target is owned, depended on, or declared a peer ----
 		// Attribution is unioned across the whole group rather than taken from the base, because the
 		// merge keeps no per-field provenance — an overlay that adds a ref field would otherwise be
@@ -650,6 +697,12 @@ export function compile({ root, pkg }) {
 		if (extenders.length) mergedCount++;
 	}
 
+	// ---- no collection may sit inside another's folder -------------------------------
+	// Checked HERE because it is the first moment every path is resolved (namespace nesting, the
+	// `owns-data` module prefix and any authored override all already applied). See
+	// namespace.storageOverlaps for what this silently did before it was checked.
+	for (const p of storageOverlaps(storageEntries)) fail(p);
+
 	// ---- modules, projected ---------------------------------------------------------
 	// One record per discovered module, written from what discovery and the package pass already
 	// established. `package.json` remains the source of truth and compile keeps reading it — this
@@ -795,12 +848,17 @@ export function compile({ root, pkg }) {
 	const anyFlat = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, k))));
 	const anyNested = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, 'system', k))));
 	const sourceLayout = anyFlat && anyNested ? 'mixed' : anyNested ? 'nested' : 'flat';
-	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout });
+	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout, namespaces, version: engineVer });
 
 	// ---- provenance manifest ------------------------------------------------------
 	const manifest = {
 		compiled: new Date().toISOString(),
 		host: engineId(),
+		// The declared namespace list, carried across the boundary so the RECORD layer can split a
+		// reference without importing the compiler or re-reading package.json — the same reason
+		// `storage.base` is a field instead of a path test. An older runtime has no key here, which
+		// reads as "no namespaces", which is exactly right for a workspace that never declared any.
+		namespaces,
 		modules: sources.map((s) => ({ name: s.name, channel: s.channel, root: rel(s.root) || '.' })),
 		ui: uiModules.sort(),
 		'adapter-outputs': adapterOutputs.sort(),

package/src/harnesses.js

@@ -21,7 +21,7 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 const END = '<!-- dreamteamer:end -->';
 
-export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat' }) {
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown' }) {
 	const outputs = [];
 	const summary = [];
 	const rel = (p) => path.relative(root, p);
@@ -56,7 +56,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		}
 		summary.push(`claude-code → .claude (${n} files)`);
 	}
-	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version) : null);
 
 	// ---- shared cross-agent skills mirror (.agents/skills) — codex/pi discover it,
 	// cursor/gemini blocks point at it. written once no matter how many harnesses use it.
@@ -73,17 +73,17 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	}
 
 	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
-	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version) : null);
 	if (on('codex')) summary.push('codex → AGENTS.md block');
 	if (on('pi')) summary.push('pi → AGENTS.md block + .agents/skills');
 
 	// ---- gemini-cli: GEMINI.md is its context file -----------------------------------
-	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -127,15 +127,25 @@ function buildSkillsIndex(entries) {
  *  'nested' (the pre-2026-08-05 `<module>/system/skills/`), or 'mixed'. It is passed in rather than
  *  assumed because generated prose that contradicts the workspace is worse than no prose: this block
  *  is the first thing an agent session reads, and a workspace still on the old layout was being told
- *  to write somewhere it does not keep its sources. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
+ *  to write somewhere it does not keep its sources.
+ *
+ *  `namespaces` is here for exactly the same reason, and it matters more. A reference is
+ *  `<collection>/<id>`, and an id is ALSO a slash path — so in a workspace with declared namespaces an
+ *  agent that splits `health/doctors/dana-levi` at the first slash reads a collection that does not
+ *  exist. Naming the declared list is what makes the grammar decidable from this block alone, without
+ *  the agent having to go read the manifest. A workspace with no namespaces gets no extra sentence. */
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown') {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		mixed: '`modules/<module>/<kind>/`, or `<module>/system/<kind>/` where a module still nests it —\n`collections/`, `skills/`, `agents/`, `commands/`,',
 	}[sourceLayout] ?? '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,';
 	const lines = [
-		'this workspace is operated by dreamteamer v0.6. **read the `using-dreamteamer` skill before',
+		// PASSED IN, never hardcoded: this string used to say "v0.6" literally, which was correct for
+		// exactly one minor release and then quietly wrong in every workspace it had been written into.
+		// Passed rather than imported because compile.js already computes it and imports THIS module —
+		// reaching back for `engineVersion` would close a cycle for the sake of one string.
+		`this workspace is operated by dreamteamer v${version}. **read the \`using-dreamteamer\` skill before`,
 		'working with data.** schemas (read): `.dreamteamer/collections/` (provenance:',
 		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
 		'`command-bindings/`, `ui-views/`, `collection-templates/`',
@@ -145,6 +155,17 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
 		'check`) after bulk edits; run `dreamteamer compile` (`npm run compile`) after changing any',
 		'source or installing modules.',
 	];
+	// ⚠ Only when the workspace HAS namespaces. Telling an agent about a feature this workspace does
+	// not use is the same failure as telling it the wrong source layout — prose that contradicts the
+	// workspace is worse than no prose.
+	if (namespaces.length) {
+		lines.push(
+			`this workspace declares NAMESPACES: ${namespaces.map((n) => `\`${n}\``).join(', ')}. a collection`,
+			'in one is named with its prefix (`health/doctors`), stores records under `data/<namespace>/`,',
+			'and is referenced as `<namespace>/<collection>/<id>` — so split a reference at the end of the',
+			'DECLARED prefix, not at the first slash. collections with no prefix are unaffected.',
+		);
+	}
 	// claude-code discovers skills natively (Skill tool) — an index in CLAUDE.md is pure
 	// context bloat there. every other harness gets the trigger index + discovery pointers.
 	if (flavor !== 'claude-code') {

package/src/namespace.js

@@ -0,0 +1,181 @@
+// NAMESPACES — how a collection name is scoped, and how a reference splits back apart.
+//
+// A namespace is a slash-delimited prefix on a collection name: `health/doctors` is the collection
+// `doctors` in the namespace `health`, and its records live under `data/health/doctors/`. A
+// reference to one of those records is `health/doctors/dana-levi`.
+//
+// ⚠ THE WHOLE PROBLEM IN ONE LINE: an id is ALSO a slash-delimited path (`meetings/2026/07/kickoff`
+// is one collection and a three-segment id), so `a/b/c` is either collection `a` + id `b/c` or
+// collection `a/b` + id `c`, and nothing about the STRING says which.
+//
+// So namespaces are DECLARED, in the workspace package.json:
+//
+//     "dreamteamer": { "namespaces": ["health", "finance", "work/clients"] }
+//
+// and every split consults that closed set, longest match first. The alternative — inferring the
+// boundary from whichever collections happen to exist — was rejected: it makes the meaning of a
+// reference depend on the current descriptor set, so installing a module could silently re-point
+// references in records nobody edited. A declared list also turns the dangerous case (a namespace
+// whose name collides with a collection's) into a compile error instead of a longest-prefix win.
+//
+// The DEFAULT namespace is the empty prefix. `tasks/kickoff` is a reference into it, `data/tasks/`
+// is where it lives, and that is exactly what every workspace already has — which is why adopting
+// namespaces migrates nothing. `default` is reserved precisely so there is never a second spelling
+// for the same collection.
+//
+// This module is deliberately PURE — the declared list arrives as an argument. compile validates it
+// and writes it into the manifest; runtime.js hands it to the record layer. Nothing here reads a
+// file, so all of it is unit-testable without a workspace.
+
+/** Never a namespace: it would give the default namespace a second, prefixed spelling. */
+export const RESERVED_NAMESPACES = new Set(['default']);
+
+/** One segment of a namespace or collection name: the id-safe alphabet the rest of the engine uses. */
+const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The declared list, cleaned and ordered for prefix matching: de-duplicated, slash-trimmed, and
+ * sorted LONGEST FIRST so a nested namespace (`work/clients`) is tested before its parent (`work`).
+ * Order is the correctness property here, not a nicety — parent-first would claim `work/clients/acme`
+ * for the namespace `work`, making the collection `clients` and the id `acme` on a workspace where
+ * `work/clients` is the namespace and the collection is something else entirely.
+ */
+export function normalizeNamespaces(list) {
+	if (!Array.isArray(list)) return [];
+	const seen = new Set();
+	for (const raw of list) {
+		if (typeof raw !== 'string') continue;
+		const ns = raw.trim().replace(/^\/+|\/+$/g, '');
+		if (ns) seen.add(ns);
+	}
+	return [...seen].sort((a, b) => b.length - a.length || a.localeCompare(b));
+}
+
+/**
+ * Everything wrong with a declared list, as sentences — or `[]`. `collectionNames` is every compiled
+ * collection's qualified name, which is what makes the collision check possible at all.
+ *
+ * compile calls this and fails on a non-empty result. It is a separate function from the compiler so
+ * the rules can be tested directly, and so the error text lives beside the semantics it protects.
+ */
+export function namespaceProblems(namespaces, collectionNames = []) {
+	const problems = [];
+	const names = new Set(collectionNames);
+	for (const ns of namespaces) {
+		const segments = ns.split('/');
+		for (const seg of segments) {
+			if (RESERVED_NAMESPACES.has(seg)) {
+				problems.push(`namespace "${ns}": "${seg}" is reserved — the default namespace is the EMPTY prefix, so a collection in it is spelled \`tasks\`, never \`default/tasks\`.`);
+			} else if (!SEGMENT.test(seg)) {
+				problems.push(`namespace "${ns}": segment "${seg}" must be lowercase alphanumeric with single hyphens (it becomes a folder name and part of every reference).`);
+			}
+		}
+		// The collision that makes a slash-delimited namespace dangerous: with BOTH a namespace
+		// `health` and a collection `health`, the reference `health/doctors/dana-levi` is a record of
+		// collection `health/doctors` AND a record of collection `health` with the nested id
+		// `doctors/dana-levi`. Longest-match would silently pick the first and make the second
+		// unreferenceable. Refused up front instead.
+		if (names.has(ns)) {
+			problems.push(`namespace "${ns}" collides with the collection of the same name — a reference like "${ns}/x/y" would be ambiguous. Rename one.`);
+		}
+	}
+	return problems;
+}
+
+/** `health` + `doctors` → `health/doctors`; the default namespace (empty) → `doctors`. */
+export function qualify(namespace, name) {
+	const ns = String(namespace ?? '').replace(/^\/+|\/+$/g, '');
+	return ns ? `${ns}/${name}` : String(name);
+}
+
+/**
+ * The declared namespace a qualified collection name sits in, or `''` for the default namespace.
+ * Matched against the declared list rather than by cutting at the last slash, because a collection
+ * name is only namespaced if its prefix was actually declared — see `unqualifiedProblems`.
+ */
+export function namespaceOf(qualified, namespaces) {
+	for (const ns of namespaces) if (qualified.startsWith(ns + '/')) return ns;
+	return '';
+}
+
+/** The bare collection name inside its namespace: `health/doctors` → `doctors`. */
+export function baseNameOf(qualified, namespaces) {
+	const ns = namespaceOf(qualified, namespaces);
+	return ns ? qualified.slice(ns.length + 1) : qualified;
+}
+
+/**
+ * A collection name carrying a slash whose prefix is NOT declared, which is the silent-failure this
+ * whole module exists to prevent: every reference to it would split at the first slash, name a
+ * collection that does not exist, and dangle. Returns problems as sentences, or `[]`.
+ */
+export function unqualifiedProblems(collectionNames, namespaces) {
+	const problems = [];
+	for (const name of collectionNames) {
+		if (!name.includes('/')) continue;
+		if (namespaceOf(name, namespaces)) continue;
+		const guess = name.slice(0, name.lastIndexOf('/'));
+		problems.push(`collection "${name}" is namespaced, but "${guess}" is not declared — add it to \`dreamteamer.namespaces\` in package.json, or every reference to this collection will split at the first slash and dangle.`);
+	}
+	return problems;
+}
+
+/**
+ * Split a reference into `{ collection, id }`, or `null` when it is not a reference shape.
+ *
+ * THE one place the boundary is decided. Everything that parses a reference — the store's write-time
+ * check, `check`'s report, the extension's go-to-definition — goes through here, so a namespace can
+ * never mean one thing on write and another on read.
+ */
+export function parseRef(ref, namespaces = []) {
+	if (typeof ref !== 'string' || !ref) return null;
+	for (const ns of namespaces) {
+		if (!ref.startsWith(ns + '/')) continue;
+		const rest = ref.slice(ns.length + 1);
+		const slash = rest.indexOf('/');
+		// `health/doctors` alone names a COLLECTION, not a record — there is no id, so it is not a
+		// reference. Falling through to the unnamespaced split would call it collection `health`,
+		// which is the ambiguity this module refuses everywhere else.
+		if (slash < 1 || slash === rest.length - 1) return null;
+		return { collection: `${ns}/${rest.slice(0, slash)}`, id: rest.slice(slash + 1) };
+	}
+	const slash = ref.indexOf('/');
+	if (slash < 1 || slash === ref.length - 1) return null;
+	return { collection: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+
+/**
+ * The folder a collection's records belong in, workspace-relative and WITHOUT any module prefix
+ * (compile adds that for an `owns-data` module). The namespace becomes real directory nesting, which
+ * is the point: `health/doctors` lands in `data/health/doctors/` rather than beside `data/tasks/`.
+ */
+export function defaultStoragePath(qualified, namespaces, dataPath = 'data') {
+	const ns = namespaceOf(qualified, namespaces);
+	const base = ns ? qualified.slice(ns.length + 1) : qualified;
+	return ns ? `${dataPath}/${ns}/${base}` : `${dataPath}/${base}`;
+}
+
+/**
+ * Storage paths that swallow each other, as sentences — or `[]`. `entries` is `[{name, path}]`.
+ *
+ * ⚠ MEASURED DATA LOSS, not a hypothetical. Give collection A the path `data/health` and collection
+ * B `data/health/doctors`, and A's recursive walk indexes B's records as its own: `dt A list` prints
+ * B's records under A's name, `check` reports B's fields as unknown fields of A, and a write through
+ * A can overwrite a record of B. compile reported ✔ through all of it, because nothing ever compared
+ * two collections' paths. Namespaces make near-misses like this ordinary, so the check is no longer
+ * optional.
+ *
+ * Segment-wise on purpose: `data/health` must not flag `data/health-notes`.
+ */
+export function storageOverlaps(entries) {
+	const problems = [];
+	const sorted = [...entries].filter((e) => e.path).sort((a, b) => a.path.localeCompare(b.path));
+	for (const outer of sorted) {
+		for (const inner of sorted) {
+			if (outer === inner || outer.base !== inner.base) continue;
+			if (!inner.path.startsWith(outer.path + '/')) continue;
+			problems.push(`collection "${inner.name}" stores records under "${inner.path}", which is INSIDE "${outer.name}"'s folder "${outer.path}" — the outer collection would index the inner one's records as its own. Give one of them a folder of its own.`);
+		}
+	}
+	return problems;
+}

package/src/runtime.js

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { load } from './yaml.js';
+import { normalizeNamespaces } from './namespace.js';
 
 export const RUNTIME_DIR = '.dreamteamer';
 
@@ -72,9 +73,13 @@ export function loadDescriptors(root) {
 	const dir = runtimeKindDir(root, 'collections');
 	if (!fs.existsSync(dir)) return null;
 	const out = new Map();
-	for (const f of fs.readdirSync(dir).sort()) {
-		if (!f.endsWith('.collection.yaml')) continue;
-		const d = load(fs.readFileSync(path.join(dir, f), 'utf8'));
+	// RECURSIVE, because a namespaced collection compiles to `collections/<ns>/<name>.collection.yaml`
+	// and this loop used to read exactly one directory level. ⚠ That was a SILENT failure, not an
+	// error: compile wrote the nested file and reported ✔, this returned a Map without it, and the
+	// collection was simply absent — `dt <c> list` said "unknown collection" for something that had
+	// just compiled successfully. Keep the walk.
+	for (const f of walkDescriptors(dir)) {
+		const d = load(fs.readFileSync(f, 'utf8'));
 		d.storage ??= {};
 		d.storage.base ??= derivedBase(d);
 		out.set(d.name, d);
@@ -82,6 +87,27 @@ export function loadDescriptors(root) {
 	return out;
 }
 
+/** Every `*.collection.yaml` under a directory, at any depth, in a stable order. */
+function walkDescriptors(dir, out = []) {
+	for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		if (e.name.startsWith('.')) continue;
+		const p = path.join(dir, e.name);
+		if (e.isDirectory()) walkDescriptors(p, out);
+		else if (e.name.endsWith('.collection.yaml')) out.push(p);
+	}
+	return out;
+}
+
+/**
+ * The workspace's declared namespaces, longest-first — the closed set every reference is split
+ * against. Read off the MANIFEST rather than package.json so the record layer keeps its single
+ * dependency on the compiled artifact (the `sourceRoots()` precedent), and so a runtime compiled
+ * before namespaces existed answers `[]` instead of throwing.
+ */
+export function namespaces(root) {
+	return normalizeNamespaces(readManifest(root)?.namespaces);
+}
+
 /**
  * Which root `storage.path` is relative to — the whole of what the record layer needs to know about
  * the system/data distinction, as DATA rather than as a string test it has to perform. `runtime` =