dreamteamer 0.12.0 → 0.13.0

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.13.0",
 	"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

@@ -75,7 +75,11 @@ and deliberately nothing else — including nothing about people. There is no `u
   from git's own status letters), and a multi-record commit says what it swept.
 - **one commit per REPO.** a module can own its records (`owns-data` in its package.json), and git
   has no cross-repo commit — so a rename whose inbound refs live in another repo is TWO commits.
-  `dt commit` prints both. `dt commit <collection> …` scopes it; `--dry-run` shows the set first.
+  `dt commit` prints both. `--dry-run` shows the set first.
+- **scope the commit to what YOU wrote: `dt commit <collection>/<id>`.** any number of targets, each
+  either a whole `<collection>` or one record — bare `dt commit` publishes everything pending, and
+  `dt commit <collection>` publishes every dirty record under it *whoever wrote it*, which is the
+  same sweep as the blanket add below when a second session shares the tree.
 - **never `git add -A`, `git add .`, or `git commit -a`.** stage explicit paths. more than one agent
   can be working in a tree, and a blanket add silently commits whatever another session has
   uncommitted right now — under your subject, leaving `git status` clean and the damage invisible.
@@ -100,7 +104,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/cli.js

@@ -100,7 +100,10 @@ workspace verbs:
               [--since <sha|YYYY-MM-DD>] (default: the last commit) [--json]
   commit      publish records already written to disk: samples git status over every
               collection's record dirs, one commit PER REPO, subject composed from the
-              status letters. [<collection> …] to scope, [-m <subject>], [--dry-run]
+              status letters. Scope it with any number of targets, each either a whole
+              <collection> or one <collection>/<id> — the record form is what keeps a
+              concurrent session's pending records out of your commit.
+              [<collection>|<collection>/<id> …] [-m <subject>] [--dry-run] [--json]
   help        this text
 `;
 
@@ -206,7 +209,9 @@ export function run(argv) {
 				const store = new Store(ws);
 				const mi = rest.indexOf('-m');
 				const message = mi > -1 ? rest[mi + 1] : undefined;
-				// bare args are collection names — minus the token `-m` consumed as its subject
+				// bare args are TARGETS — a whole collection or a `<collection>/<id>` reference,
+				// told apart in commit.js against the declared collections — minus the token `-m`
+				// consumed as its subject
 				const only = rest.filter((a, i) => !a.startsWith('-') && (mi === -1 || i !== mi + 1));
 				const results = commitPending(store, { only, message, dryRun: rest.includes('--dry-run') });
 				if (rest.includes('--json')) { emit(JSON.stringify(results, null, 2)); process.exit(0); }

package/src/commit.js

@@ -5,6 +5,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToRecord } from './events.js';
+import { splitRef } from './ref.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -14,6 +15,28 @@ const QUIET = ['ignore', 'pipe', 'ignore'];
 
 const VERB = { A: 'add', M: 'set', D: 'rm', R: 'rename', '?': 'add' };
 
+/** What the caller asked to publish. A target is EITHER a collection name or a `<collection>/<id>`
+ *  reference — the same either-shape `move` and `commands` accept, and after 0.12.0 the shape every
+ *  other verb's target has. Which one it is cannot be guessed from the string (an id may contain
+ *  slashes and so may a namespaced collection name), so it is decided against the DECLARED
+ *  collections: a key of `descriptors` is a collection, anything else goes to splitRef — which
+ *  throws, naming the known collections, rather than letting a typo mean "no scope".
+ *
+ *  Returns `scope` (collections to sample, so the git pathspec stays as narrow as it was), `whole`
+ *  (collections asked for entire) and `records` (ref → {collection, id}). */
+function parseTargets(descriptors, only) {
+	const scope = new Set();
+	const whole = new Set();
+	const records = new Map();
+	for (const target of only) {
+		if (descriptors.has(target)) { whole.add(target); scope.add(target); continue; }
+		const { collection, id } = splitRef(descriptors, target);
+		records.set(`${collection}/${id}`, { collection, id });
+		scope.add(collection);
+	}
+	return { scoped: only.length > 0, scope: [...scope], whole, records };
+}
+
 /** Record directories to watch, grouped by owning repo. System-stored collections are excluded:
  *  they live in the gitignored runtime and their sources are module files — the same exclusion
  *  pathToRecord already applies. */
@@ -97,11 +120,44 @@ export function composeSubject(rows) {
 	return `dreamteamer: ${rows.length} changes across ${collections.join(', ')}`;
 }
 
+/** A requested reference that matched no pending row is one of two very different things: a record
+ *  that is already published (nothing to do, and fine) or a MISTYPED id — which must not pass as
+ *  "nothing pending", the one report that looks like success. Only the store can tell them apart,
+ *  and it is only asked in this branch: a pending DELETION matched a row above, so a record whose
+ *  file is legitimately gone never reaches here. */
+function assertResolvable(store, records, matched) {
+	for (const [ref, { collection, id }] of records) {
+		if (matched.has(ref) || store.ids(collection).has(id)) continue;
+		throw new Error(`${ref}: no such record — nothing pending under that reference`);
+	}
+}
+
 export function commitPending(store, { only = [], message, dryRun = false } = {}) {
-	const byRepo = scopeByRepo(store.descriptors, only);
-	const results = [];
+	// Targets are resolved BEFORE anything is committed, so one bad target in a list of good ones
+	// leaves the whole tree untouched rather than committing a prefix of what was asked for.
+	const targets = parseTargets(store.descriptors, only);
+	const byRepo = scopeByRepo(store.descriptors, targets.scope);
+	// ⚠ Sample every repo FIRST, then check the references, then commit. The unknown-reference test
+	// below can only be answered once every repo has been sampled — a record lives in exactly one
+	// repo, and which one is not known in advance.
+	const sampled = [];
+	const matched = new Set();
 	for (const [repo, dirs] of byRepo) {
 		const { cwd, rows } = sample(store.root, repo, dirs, store.descriptors);
+		// The SAMPLER is deliberately left alone — it is what makes a hand-edited record
+		// indistinguishable from one the store wrote. Narrowing happens here, on the sampled rows,
+		// so `dt commit <collection>/<id>` publishes that record and leaves a sibling written by
+		// another session exactly as pending as it found it.
+		const wanted = !targets.scoped ? rows : rows.filter((r) => {
+			const ref = `${r.collection}/${r.id}`;
+			if (targets.records.has(ref)) { matched.add(ref); return true; }
+			return targets.whole.has(r.collection);
+		});
+		sampled.push({ repo, cwd, rows: wanted });
+	}
+	assertResolvable(store, targets.records, matched);
+	const results = [];
+	for (const { repo, cwd, rows } of sampled) {
 		if (!rows.length) continue;
 		const blocked = inProgress(cwd);
 		if (blocked) { results.push({ repo, rows, blocked }); continue; }

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