dreamteamer 0.12.0 → 0.12.1

package/README.md

@@ -73,8 +73,8 @@ source_file: ${env:FILES_FOLDER}/2026/q3.pdf
 ```
 
 Three variables, borrowing VS Code's grammar: `${env:NAME}` — declared in `dreamteamer.vars` in
-`package.json`, valued in the gitignored `.env` — plus `${workspaceFolder}` and `${userHome}`.
-One verb renders them:
+`package.json`, valued in the gitignored `.env` (an empty or whitespace-only value counts as no
+value at all) — plus `${workspaceFolder}` and `${userHome}`. One verb renders them:
 
 ```bash
 npx dreamteamer resolve '${env:FILES_FOLDER}/x'            # → /Volumes/annex/x

package/collections/collections.collection.yaml

@@ -93,7 +93,7 @@ schema:
       description: >-
         The module that OWNS this concept — DERIVED by compile from the base source, never authored.
         An overlay adds fields to somebody else's collection and does not take it over, so `meetings`
-        stays owned by crm even though hq3 overlays it. This is the workspace's real partition, and
+        stays owned by crm even though the workspace module overlays it. This is the workspace's real partition, and
         what the nav groups by.
     group:
       type: string

package/collections/modules.collection.yaml

@@ -30,7 +30,7 @@ schema:
   properties:
     name:
       type: string
-      description: The module's package name, verbatim — `@dreamteamer/crm`, `hq3-workspace`.
+      description: The module's package name, verbatim — `@dreamteamer/crm`, `acme-workspace`.
     title:
       type: string
       description: >-

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.12.0",
+	"version": "0.12.1",
 	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",
@@ -57,6 +57,7 @@
 		"test": "node scripts/test.mjs",
 		"test:unit": "node scripts/test.mjs --unit",
 		"test:watch": "node --watch scripts/test.mjs --unit",
+		"perf": "node test/perf/run.mjs",
 		"metrics": "node scripts/metrics.mjs",
 		"metrics:check": "node scripts/metrics.mjs --check",
 		"layers": "node scripts/layers.mjs",

package/skills/using-dreamteamer/SKILL.md

@@ -100,7 +100,7 @@ source_file: ${env:FILES_FOLDER}/2026/q3.pdf
 
 | variable | renders to |
 |---|---|
-| `${env:NAME}` | `NAME`'s value in the workspace's `.env` — and only if `NAME` is listed in `dreamteamer.vars` in `package.json` |
+| `${env:NAME}` | `NAME`'s value in the workspace's `.env` — and only if `NAME` is listed in `dreamteamer.vars` in `package.json` AND has a non-empty value there (an empty or whitespace-only value fails exactly like an unset key) |
 | `${workspaceFolder}` | the workspace root, absolute |
 | `${userHome}` | the current user's home directory |
 

package/src/compile.js

@@ -49,7 +49,7 @@ export function titleCase(id) {
  * Every `x-display` left in a schema, as `[fieldPath, template, referenceTarget|null]`.
  *
  * The keyword was renamed to `x-title-template` and mostly DELETED — its value is inherited from
- * the target collection's `title_template`. There is deliberately no alias: recipes and dt-hq pin
+ * the target collection's `title_template`. There is deliberately no alias: real workspaces pin
  * this engine by SHA, so nothing breaks until someone bumps a pin, and that person needs a message
  * rather than silence. JSON Schema IGNORES unknown keywords, so the alternative to failing here is
  * a label that quietly stops working and regresses to a raw id.
@@ -318,7 +318,11 @@ export function compile({ root, pkg }) {
 			// pairing there is: compile says nothing and then `dt resolve` answers "no value in
 			// .env" about a line the operator is looking straight at. Values are read here and
 			// never printed — the warnings below name keys only.
-			const present = new Set(parseEnvValues(fs.readFileSync(envPath, 'utf8')).keys());
+			// A key present with an EMPTY (or whitespace-only) value is treated as absent, same as
+			// resolve's renderTemplate — `FILES_FOLDER=` must warn here exactly as `FILES_FOLDER`
+			// missing entirely would, or compile says nothing and resolve fails on the same line.
+			const parsedEnv = parseEnvValues(fs.readFileSync(envPath, 'utf8'));
+			const present = new Set([...parsedEnv].filter(([, v]) => v.trim() !== '').map(([k]) => k));
 			for (const [k, mods] of declaredEnv) {
 				if (present.has(k)) continue;
 				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k} — missing from .env (see .env.example)`);
@@ -662,7 +666,8 @@ export function compile({ root, pkg }) {
 		// judged against the BASE module's declarations, which it never wrote.
 		const groupModules = [...new Set(group.map((g) => g.moduleName))];
 		// WHO OWNS the concept — the module whose source is the base, not the ones overlaying it.
-		// An overlay adds fields to somebody else's collection (hq3 adds `tags` to crm's contacts);
+		// An overlay adds fields to somebody else's collection (a workspace module adding its own
+		// `tags` to the `crm` module's `contacts`);
 		// it does not take the concept over. Measured 2026-08-11: letting the overlay win moves
 		// `contacts` and `meetings` out of CRM, and a CRM without contacts reads as broken.
 		//
@@ -672,7 +677,8 @@ export function compile({ root, pkg }) {
 		// IS the answer, and it exists to REPLACE `group:` as the workspace's partition rather than
 		// to sit beside it.
 		merged.owner = `modules/${moduleId(base?.moduleName ?? groupModules[0])}`;
-		// EVERY contributing module, not just the base — a collection merged from crm + hq3 belongs
+		// EVERY contributing module, not just the base — a collection merged from `crm` and the
+		// workspace module that overlays it belongs
 		// to both, and saying otherwise is what made a flat "which module owns this" field wrong.
 		for (const m of groupModules) {
 			if (!moduleColls.has(m)) moduleColls.set(m, new Set());
@@ -881,7 +887,8 @@ export function compile({ root, pkg }) {
 	// in this loop and never got cleared — a module that was RENAMED or REMOVED left its old record
 	// behind forever, listing collections that no longer exist. `check` reads those records like any
 	// other, so it surfaced as a dangling reference in a file nobody had touched, twice in one day
-	// (`hq3-workspace` after the workspace-module rename, and again after `crm` was folded in). The
+	// (the workspace module's own record after it was renamed, and a domain module's after it was
+	// folded into another). The
 	// runtime is build output; stale build output is the compiler's problem, not the reader's.
 	for (const kind of [...KINDS, ...DERIVED_KINDS]) fs.rmSync(path.join(RUNTIME, kind), { recursive: true, force: true });
 	fs.rmSync(path.join(RUNTIME, 'system'), { recursive: true, force: true });

package/src/env-vars.js

@@ -34,7 +34,11 @@ export function renderTemplate(str, { env, workspaceFolder, declared }) {
 		if (ns !== 'env') throw new Error(`\${${ns}:${arg}} is not a dreamteamer variable — ${SUPPORTED}`);
 		if (!arg) throw new Error(`\${env:} needs a key name — ${SUPPORTED}`);
 		if (!declared.includes(arg)) throw new Error(`\${env:${arg}}: "${arg}" is not declared in dreamteamer.vars (workspace package.json) — declared: ${declared.join(', ') || '(none)'}`);
-		if (!env.has(arg)) throw new Error(`\${env:${arg}} is declared but has no value in .env on this machine`);
+		// An empty or whitespace-only value is indistinguishable from unset to anyone reading the
+		// rendered output — `FILES_FOLDER=` passes `env.has()` and silently renders to '', producing
+		// a plausible-looking but wrong path. Same failure, same message: the operator can't tell
+		// the two states apart from outside and doesn't care which one it is.
+		if (!env.has(arg) || env.get(arg).trim() === '') throw new Error(`\${env:${arg}} is declared but has no value in .env on this machine`);
 		return env.get(arg);
 	});
 }

package/src/init.js

@@ -75,10 +75,10 @@ export function init({ flags = {} } = {}) {
 		harnesses,
 		'gitignore-runtime-folder': true,
 		// The workspace's own sources live in `modules/default/`, and the folder is named for its ROLE,
-		// not for the vault. It used to be named after the workspace, and that name went stale twice in
-		// one repo (`hq3` → `gk`, decision 213 reversed by 224) — each rename rewriting every path that
-		// RESOLVES while the historical documents deliberately kept the old spelling, so a stale-looking
-		// `modules/hq3` was correct in prose and a bug in a path. A role name cannot go stale.
+		// not for the vault. It used to be named after the workspace, and that name went stale TWICE in
+		// one repo (decision 213, reversed by 224) — each rename rewriting every path that RESOLVES
+		// while the historical documents deliberately kept the old spelling, so the old `modules/<vault>`
+		// was correct in prose and a bug in a path. A role name cannot go stale.
 		//
 		// `default` is deliberately the same word `RESERVED_NAMESPACES` holds (namespace.js): this module
 		// owns the DEFAULT-namespace collections, and the default namespace is the empty prefix. The one

package/src/schema-ops.js

@@ -219,14 +219,23 @@ export function removeCollection(ws, store, name, { force = false } = {}) {
  * relearn both, and would corrupt `data/tasks/` in a path or a URL on its first outing. N passes over
  * the record files is the price, and at human scale it is worth paying for reusing the correct code.
  *
- * ⚠ MEASURED 2026-08-17, so the cost is a number rather than a hope: a 2,291-record collection in a
- * 3,391-file workspace — gk-brain's `finance-transactions` — takes **3 minutes**, of which 142s is
- * system time. That is 7.7M file reads to rewrite ZERO references, because the pass runs per id
- * whether or not anything points at the collection. Tolerable for a one-time migration and left
- * alone on that basis; it is O(records x files), so a workspace 3x larger pays 27 minutes. The fix
- * when it is needed is a batch entry point on the store that reads each file ONCE and loops the ref
- * set in memory, with `text.includes(oldName + '/')` as a cheap NEGATIVE filter only — never as the
- * matcher, for the reason above.
+ * ⚠ MEASURED 2026-08-17, so the cost is a number rather than a hope: a real 2,291-record collection
+ * in a 3,391-file workspace takes **3 minutes**, of which 142s is system time — 7.7M file reads to
+ * rewrite ZERO references, because the pass runs per id whether or not anything points at the
+ * collection. Tolerable for a one-time migration and left alone on that basis; it is
+ * O(records x files), so a workspace 3x larger pays 27 minutes.
+ *
+ * ⚠ REPRODUCED 2026-08-22 by `npm run perf -- --records=2291 --filler=1100`, which generates a
+ * workspace that shape — 271s wall, 203s of it system, and **15.6M reads, not 7.7M**. The original
+ * figure counted ONE pass per id; there are TWO, because `captureRefs` walks every record file for
+ * the rollback snapshot before `rewriteRefs` walks them all again. `7.7M` is the per-pass number.
+ * That is what a generated fixture is for: the finding was right about the shape and off by 2x on
+ * the count, and no comment could have told you.
+ *
+ * The fix when it is needed is a batch entry point on the store that reads each file ONCE and loops
+ * the ref set in memory, with `text.includes(oldName + '/')` as a cheap NEGATIVE filter only — never
+ * as the matcher, for the reason above. Halving it is cheaper still: the snapshot pass and the
+ * rewrite pass read the same bytes.
  */
 export function renameCollection(ws, store, oldName, newName) {
 	const d = store.descriptor(oldName); // throws with the known-collection list if absent