@telorun/analyzer 0.72.0 → 0.74.0

package/dist/release/workspace-config.js

@@ -1,64 +1,348 @@
 /**
- * `telo-workspace.yaml` — the release anchor.
+ * `telo-workspace.yaml` — the anchor.
  *
- * Every path the release system names — a module key, a ledger entry, a
- * fragment's `modules:` — is relative to this file's directory. That is the
- * whole of its job: **its location is the anchor**, and its one field names the
- * subtrees that may hold modules, which is not derivable (a whole-tree scan
- * would read every example and every cached `.telo/manifests` copy as a released
- * module).
+ * **Its location is the anchor, and every field lives in a block scoped to what
+ * it governs.** Every path the release system names — a module key, a ledger
+ * entry, a fragment's `modules:` — is relative to this file's directory, and so
+ * is the `.telo` cache. `release:` is what `telo release` reads; `env:` is what
+ * `telo run` reads when it resolves a manifest's environment.
  *
- * The file is **optional**, and everything reading it is harmless without one.
- * `telo release` requires one. `telo run` uses its LOCATION — never `modules:`,
- * which is release scope — as the bound on the walk-up that collects `.env` /
- * `.env.local`, and with no marker reads the manifest's own directory alone, as
- * it did before this file existed; a bound is what keeps that walk out of a
- * user's home directory. Nothing else — not `check`, `publish`, `install`,
- * `upgrade`, `migrate`, `module`, and not the kernel — looks for it, so a
- * single-manifest repo, a bare `examples/` directory and a third-party module
- * checkout keep working with nothing added. Any field added later must be true
- * of the whole tree, not derivable from it, and harmless by its absence.
+ * That rule is why `modules:` sits under `release:` rather than at the top
+ * level. It is a release inventory, not an inventory of manifests: it exists so
+ * a whole-tree scan does not read every example and every cached
+ * `.telo/manifests` copy as something to version and publish, and nothing else
+ * consults it — the env walk refuses to, which is why a manifest under
+ * `examples/`, in no release subtree, still gets the full walk.
  *
- * Parsing lives here, in the browser-safe half, because the editor answers
- * "what does changing this library bump?" from the same model. Finding the file
- * on disk is the CLI's half — this side takes text.
+ * The file is **optional and every block in it is optional**. A marker whose
+ * whole content is comments is valid: it anchors the cache and bounds the env
+ * walk, which is exactly what a runner seeds one for.
+ *
+ * **The reader is lenient; the diagnostics are the strict half.** It returns
+ * everything it could read plus everything it found wrong, each anchored at a
+ * key path, because an editor wants all of them and a command wants to exit on
+ * the first. Which of them are fatal is the CALLER's policy, not the file's:
+ * `telo release` refuses on any error, while `telo run` consumes `env:` alone
+ * and prints the rest — aborting every app in a workspace over a release typo is
+ * not a trade to make silently.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers "what
+ * does changing this library bump?" from the same model. Finding the file on
+ * disk is the CLI's half — this side takes text. Gitignore matching is INJECTED
+ * (`PatternMatch`) for the same reason: the grammar belongs to the glob package,
+ * which this half does not depend on.
  */
 import { parseDocument } from "yaml";
+import { DEFAULT_ENV_FILES, DEFAULT_RELEASE_IGNORE, MODULE_ENTRY_KEYS, WORKSPACE_BLOCKS, WORKSPACE_SCHEMA, } from "./workspace-schema.js";
 export const WORKSPACE_FILENAME = "telo-workspace.yaml";
+export { DEFAULT_ENV_FILES, DEFAULT_RELEASE_IGNORE };
 export class WorkspaceConfigError extends Error {
 }
+const EMPTY = {};
 /**
- * Parse the marker file's text.
+ * Read the marker's text.
  *
- * Strict about its one field, because there is nothing here to be lenient with:
- * an empty or absent `modules:` names no subtree, so discovery would find no
- * module and every gate would silently pass over a whole repo.
+ * Never throws: unreadable YAML is itself a diagnostic, because the one caller
+ * that must not abort on it is the run path.
  */
-export function parseWorkspaceConfig(text, where) {
+export function readWorkspaceConfig(text, where) {
+    const diagnostics = [];
+    const report = (code, message, path, severity = "error") => {
+        diagnostics.push({ code, severity, message, path });
+    };
     let value;
     try {
         value = parseDocument(text).toJSON();
     }
     catch (err) {
-        throw new WorkspaceConfigError(`${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+        report("WORKSPACE_INVALID_VALUE", `${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`, []);
+        return { config: EMPTY, diagnostics };
     }
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new WorkspaceConfigError(`${where} must be a YAML mapping.`);
+    if (value === null || value === undefined)
+        return { config: EMPTY, diagnostics };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        report("WORKSPACE_INVALID_VALUE", `${where} must be a YAML mapping.`, []);
+        return { config: EMPTY, diagnostics };
     }
     const record = value;
     for (const key of Object.keys(record)) {
-        if (key !== "modules") {
-            throw new WorkspaceConfigError(`${where}: unknown field '${key}'. The workspace marker carries only 'modules:' — ` +
-                `the subtrees that may hold modules.`);
+        if (WORKSPACE_BLOCKS.includes(key))
+            continue;
+        if (key === "modules") {
+            report("WORKSPACE_MODULES_MOVED", `${where}: 'modules' moved under 'release:'. It is release scope — where modules live, ` +
+                `for versioning and publishing — and every field of this file now sits in the block ` +
+                `that governs it. Indent this list under a 'release:' key.`, ["modules"]);
+            continue;
+        }
+        // A near-miss of a block name is the typo whose settings would otherwise go
+        // silently unapplied; an unrecognized block is a version skew, so the next
+        // one ships without breaking today's runs.
+        const near = nearMiss(key, WORKSPACE_BLOCKS);
+        if (near) {
+            report("WORKSPACE_UNKNOWN_KEY", `${where}: unknown block '${key}'. Did you mean '${near}'?`, [key]);
+        }
+        else {
+            report("WORKSPACE_UNKNOWN_KEY", `${where}: unknown block '${key}', which nothing reads. This telo knows ${WORKSPACE_BLOCKS.map((b) => `'${b}'`).join(" and ")}.`, [key], "warning");
+        }
+    }
+    const release = readRelease(record.release, where, report);
+    const env = readEnv(record.env, where, report);
+    return {
+        config: { ...(release ? { release } : {}), ...(env ? { env } : {}) },
+        diagnostics,
+    };
+}
+function readRelease(raw, where, report) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        report("WORKSPACE_INVALID_VALUE", `${where}: 'release' must be a mapping.`, ["release"]);
+        return undefined;
+    }
+    const block = raw;
+    const read = readBlock(block, WORKSPACE_SCHEMA.release.properties, where, ["release"], report);
+    return {
+        ...(read.registry !== undefined ? { registry: read.registry } : {}),
+        ...(read.ignore !== undefined ? { ignore: read.ignore } : {}),
+        modules: read.modules ?? [],
+    };
+}
+/**
+ * Read one block against its declared shape.
+ *
+ * The declared `type` is what DISPATCHES, so a new key is one entry in the
+ * schema and no change here. Reading the key names from the data while
+ * hand-writing every type check beside it would leave the half nothing reads
+ * free to drift from the half that decides — with the data half being the one no
+ * test would catch.
+ */
+function readBlock(block, properties, where, at, report) {
+    reportUnknownKeys(block, properties, where, at, report);
+    const out = {};
+    for (const [name, schema] of Object.entries(properties)) {
+        const value = schema.type === "string"
+            ? readString(block[name], where, [...at, name], report)
+            : schema.type === "string[]"
+                ? readStringList(block[name], where, [...at, name], report)
+                : readModuleEntries(block[name], where, report);
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+function readModuleEntries(raw, where, report) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        report("WORKSPACE_INVALID_VALUE", `${where}: 'release.modules' must be a list of path patterns, e.g. [modules/*, apps/*].`, ["release", "modules"]);
+        return [];
+    }
+    if (raw.length === 0) {
+        report("WORKSPACE_INVALID_VALUE", `${where}: 'release.modules' is empty, so no directory can ever be discovered as a module. ` +
+            `List the subtrees that hold them, e.g. [modules/*, apps/*].`, ["release", "modules"]);
+        return [];
+    }
+    const entries = [];
+    for (const [index, item] of raw.entries()) {
+        const at = ["release", "modules", index];
+        if (typeof item === "string") {
+            entries.push({ path: item });
+            continue;
+        }
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            report("WORKSPACE_INVALID_VALUE", `${where}: 'release.modules' entry ${index} must be a pattern string, or a mapping ` +
+                `carrying 'path:' plus the keys it overrides.`, at);
+            continue;
         }
+        const entry = item;
+        const read = readBlock(entry, MODULE_ENTRY_KEYS, where, at, report);
+        const path = read.path;
+        if (path === undefined) {
+            report("WORKSPACE_INVALID_VALUE", `${where}: 'release.modules' entry ${index} declares no 'path:', so it matches nothing.`, at);
+            continue;
+        }
+        entries.push({
+            path,
+            ...(read.registry !== undefined ? { registry: read.registry } : {}),
+            ...(read.ignore !== undefined ? { ignore: read.ignore } : {}),
+        });
     }
-    const modules = record.modules;
-    if (!Array.isArray(modules) || modules.some((entry) => typeof entry !== "string")) {
-        throw new WorkspaceConfigError(`${where}: 'modules' must be a list of path patterns, e.g. [modules/*, apps/*].`);
+    return entries;
+}
+function readEnv(raw, where, report) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        report("WORKSPACE_INVALID_VALUE", `${where}: 'env' must be a mapping.`, ["env"]);
+        return undefined;
     }
-    if (modules.length === 0) {
-        throw new WorkspaceConfigError(`${where}: 'modules' is empty, so no directory can ever be discovered as a module. ` +
-            `List the subtrees that hold them, e.g. [modules/*, apps/*].`);
+    const block = raw;
+    const read = readBlock(block, WORKSPACE_SCHEMA.env.properties, where, ["env"], report);
+    const roots = read.roots;
+    const files = read.files;
+    if (files) {
+        for (const [index, name] of files.entries()) {
+            // A path would let one entry reach outside the bound `roots:` exists to
+            // state, so the list is filenames and the refusal is structural.
+            if (name.includes("/") || name.includes("\\") || name.includes("*")) {
+                report("WORKSPACE_INVALID_VALUE", `${where}: 'env.files' entry '${name}' is a path or a glob. It names a file collected in ` +
+                    `each directory the walk visits, so it must be a bare filename — the walk's reach is ` +
+                    `'env.roots'.`, ["env", "files", index]);
+            }
+        }
     }
-    return { modules: modules };
+    return {
+        ...(roots !== undefined ? { roots } : {}),
+        ...(files !== undefined ? { files } : {}),
+    };
+}
+function reportUnknownKeys(block, known, where, at, report) {
+    const names = Object.keys(known);
+    for (const key of Object.keys(block)) {
+        if (names.includes(key))
+            continue;
+        const near = nearMiss(key, names);
+        report("WORKSPACE_UNKNOWN_KEY", `${where}: unknown key '${[...at, key].join(".")}'.` +
+            (near ? ` Did you mean '${near}'?` : ` Known keys: ${names.map((n) => `'${n}'`).join(", ")}.`), [...at, key]);
+    }
+}
+function readString(raw, where, at, report) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "string") {
+        report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' must be a string.`, at);
+        return undefined;
+    }
+    if (raw === "") {
+        // Reported rather than read as an absence: an empty value would fall
+        // through to the next rung of the cascade and publish somewhere the author
+        // did not name, which is the one thing a declared destination must not do.
+        report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' is empty.`, at);
+        return undefined;
+    }
+    return raw;
+}
+function readStringList(raw, where, at, report) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' must be a list of strings.`, at);
+        return undefined;
+    }
+    const out = [];
+    for (const [index, item] of raw.entries()) {
+        if (typeof item !== "string") {
+            report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' entry ${index} must be a string.`, [
+                ...at,
+                index,
+            ]);
+            continue;
+        }
+        out.push(item);
+    }
+    return out;
+}
+/** One edit apart, case-insensitively — enough to separate a typo from a key
+ *  this reader is simply too old to know. */
+function nearMiss(key, known) {
+    const lower = key.toLowerCase();
+    return known.find((name) => name !== key && editDistanceAtMostOne(lower, name.toLowerCase()));
+}
+function editDistanceAtMostOne(a, b) {
+    if (a === b)
+        return true;
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0;
+    let j = 0;
+    let edits = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        if (++edits > 1)
+            return false;
+        if (a.length > b.length)
+            i++;
+        else if (a.length < b.length)
+            j++;
+        else {
+            i++;
+            j++;
+        }
+    }
+    return edits + (a.length - i) + (b.length - j) <= 1;
+}
+// ---------------------------------------------------------------------------
+// Diagnostics as a caller's policy
+// ---------------------------------------------------------------------------
+/** The diagnostics anchored inside one top-level block, plus the ones anchored
+ *  at the document itself (unreadable YAML, a non-mapping root) — those are
+ *  every block's problem. */
+export function diagnosticsFor(diagnostics, block) {
+    return diagnostics.filter((d) => d.path.length === 0 || d.path[0] === block);
+}
+export function hasError(diagnostics) {
+    return diagnostics.some((d) => d.severity === "error");
+}
+/**
+ * The release settings, or a throw naming what is missing.
+ *
+ * `telo release` is the one caller for which any error is fatal, and for which
+ * an absent block is itself one: a marker with no `release:` anchors a cache and
+ * declares no release scope, which is exactly the state a runner's seeded marker
+ * is in.
+ */
+export function requireReleaseSettings(read, where) {
+    const first = read.diagnostics.find((d) => d.severity === "error");
+    if (first)
+        throw new WorkspaceConfigError(first.message);
+    if (!read.config.release || read.config.release.modules.length === 0) {
+        throw new WorkspaceConfigError(`${where} declares no 'release.modules', so no directory can be discovered as a module. ` +
+            `List the subtrees that hold them:\n\n  release:\n    modules:\n      - modules/*\n      - apps/*\n`);
+    }
+    return read.config.release;
+}
+/**
+ * Which entry claims `key`, and what it therefore settles.
+ *
+ * **The last matching entry supplies them** — the rule the list already has,
+ * since it is one gitignore-style list evaluated last-match-wins. A negation
+ * entry is an exclusion and therefore supplies nothing: a module the last match
+ * excludes is not a module of this workspace at all, which is why this returns
+ * `undefined` rather than a settings object for it.
+ *
+ * The cascade is key-wise and each key's value replaces whole, so an entry
+ * naming only `registry:` keeps the block's `ignore:`.
+ */
+export function settingsForModule(release, key, match) {
+    const index = decidingIndex(key, release.modules.map((entry) => entry.path), match);
+    if (index < 0)
+        return undefined;
+    const entry = release.modules[index];
+    return {
+        entry: index,
+        ...(entry.registry ?? release.registry
+            ? { registry: entry.registry ?? release.registry }
+            : {}),
+        ignore: entry.ignore ?? release.ignore ?? DEFAULT_RELEASE_IGNORE,
+    };
+}
+/** Whether `path` is matched by an authored pattern list, negations honoured.
+ *  `env.roots` and a resolved `ignore` list are both read through this. */
+export function matchesPatterns(path, patterns, match) {
+    return decidingIndex(path, patterns, match) >= 0;
+}
+/**
+ * The index of the entry that CLAIMS `path`, or `-1`.
+ *
+ * The one place last-match-wins and the negation reading live: every pattern
+ * list in this file rests on that rule, and two derivations of it would be two
+ * answers to what a marker means.
+ */
+function decidingIndex(path, patterns, match) {
+    const index = match(path, patterns);
+    return index >= 0 && patterns[index].startsWith("!") ? -1 : index;
 }

package/dist/release/workspace-schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The shape of `telo-workspace.yaml`, declared as data.
+ *
+ * One declaration read by two consumers — the strict half that reports what a
+ * marker got wrong, and the editor's completion list. Two hand-maintained key
+ * lists drift, and the drift is silent in the worst direction: an editor
+ * offering a key the checker rejects.
+ *
+ * Written as JSON Schema because that is what the shape *is*, and because the
+ * `description` a completion item shows and the type a diagnostic names are the
+ * same two facts a schema already carries. It is not compiled by AJV — the
+ * strict half walks it, which is what lets a wrong value say `'registry' must be
+ * the publish destination base, as a string` instead of a keyword trace.
+ */
+export interface WorkspaceKeySchema {
+    readonly type: "string" | "string[]" | "entry[]";
+    readonly description: string;
+    /** Values worth offering at this key when nothing better is known. */
+    readonly examples?: readonly string[];
+}
+export interface WorkspaceBlockSchema {
+    readonly description: string;
+    readonly properties: Readonly<Record<string, WorkspaceKeySchema>>;
+}
+/**
+ * Every block, and every key in it, is optional — a marker whose whole content
+ * is comments is valid, and is what a runner seeds for the cache anchor alone.
+ */
+export declare const WORKSPACE_SCHEMA: Readonly<Record<string, WorkspaceBlockSchema>>;
+/** Keys a `release.modules` entry may carry in its object form. `path` is the
+ *  pattern; the rest override the block's own keys, key-wise. */
+export declare const MODULE_ENTRY_KEYS: Readonly<Record<string, WorkspaceKeySchema>>;
+export declare const WORKSPACE_BLOCKS: readonly string[];
+/** Built-in when `release.ignore` is absent. Every pattern carries `**\/` — the
+ *  anchoring at a module root is the defect this replaced, so anchoring some and
+ *  not others would reproduce it partially. */
+export declare const DEFAULT_RELEASE_IGNORE: readonly string[];
+/** Built-in when `env.files` is absent — the pair the walk hardcoded before it
+ *  was authorable, in the order it applied them. */
+export declare const DEFAULT_ENV_FILES: readonly string[];
+//# sourceMappingURL=workspace-schema.d.ts.map

package/dist/release/workspace-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-schema.d.ts","sourceRoot":"","sources":["../../src/release/workspace-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACnE;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAuC3E,CAAC;AAEF;iEACiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAO1E,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAkC,CAAC;AAEjF;;+CAE+C;AAC/C,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAMnD,CAAC;AAEF;oDACoD;AACpD,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAA2B,CAAC"}

package/dist/release/workspace-schema.js

@@ -0,0 +1,77 @@
+/**
+ * The shape of `telo-workspace.yaml`, declared as data.
+ *
+ * One declaration read by two consumers — the strict half that reports what a
+ * marker got wrong, and the editor's completion list. Two hand-maintained key
+ * lists drift, and the drift is silent in the worst direction: an editor
+ * offering a key the checker rejects.
+ *
+ * Written as JSON Schema because that is what the shape *is*, and because the
+ * `description` a completion item shows and the type a diagnostic names are the
+ * same two facts a schema already carries. It is not compiled by AJV — the
+ * strict half walks it, which is what lets a wrong value say `'registry' must be
+ * the publish destination base, as a string` instead of a keyword trace.
+ */
+/**
+ * Every block, and every key in it, is optional — a marker whose whole content
+ * is comments is valid, and is what a runner seeds for the cache anchor alone.
+ */
+export const WORKSPACE_SCHEMA = {
+    release: {
+        description: "How `telo release` behaves: where modules are, where they publish, and which of their paths are not release-relevant.",
+        properties: {
+            registry: {
+                type: "string",
+                description: "Publish destination base. A module's ref is `<registry>/<its own directory name>`. Omitted: --registry, then TELO_OCI_REGISTRY, then the base each module's own ledger entry recorded.",
+                examples: ["oci://ghcr.io/telorun"],
+            },
+            ignore: {
+                type: "string[]",
+                description: "Paths under a module whose changes are not release-relevant, so no changelog fragment is asked for. Module-relative, gitignore-style. Declaring it replaces the built-in default; [] ignores nothing.",
+                examples: ["**/tests/**", "**/docs/**", "**/plans/**", "**/README.md", "**/CHANGELOG.md"],
+            },
+            modules: {
+                type: "entry[]",
+                description: "The subtrees that may hold modules — a place to look, never a module: what makes a directory a module is its telo.yaml. Workspace-relative, gitignore-style, last match wins. A bare string is an entry with no overrides.",
+            },
+        },
+    },
+    env: {
+        description: "How `telo run` resolves a manifest's environment.",
+        properties: {
+            roots: {
+                type: "string[]",
+                description: "How far up the .env walk may climb. Workspace-relative, gitignore-style, matched against each ancestor directory; the nearest match stops the walk. Omitted: the walk stops at this file.",
+            },
+            files: {
+                type: "string[]",
+                description: "Which files are collected in each directory, later winning within one directory. Filenames only — a / or a glob is an error. Declaring it replaces the default; [] collects none.",
+                examples: [".env", ".env.local"],
+            },
+        },
+    },
+};
+/** Keys a `release.modules` entry may carry in its object form. `path` is the
+ *  pattern; the rest override the block's own keys, key-wise. */
+export const MODULE_ENTRY_KEYS = {
+    path: {
+        type: "string",
+        description: "The gitignore-style pattern this entry matches modules with.",
+    },
+    registry: WORKSPACE_SCHEMA.release.properties.registry,
+    ignore: WORKSPACE_SCHEMA.release.properties.ignore,
+};
+export const WORKSPACE_BLOCKS = Object.keys(WORKSPACE_SCHEMA);
+/** Built-in when `release.ignore` is absent. Every pattern carries `**\/` — the
+ *  anchoring at a module root is the defect this replaced, so anchoring some and
+ *  not others would reproduce it partially. */
+export const DEFAULT_RELEASE_IGNORE = [
+    "**/tests/**",
+    "**/docs/**",
+    "**/plans/**",
+    "**/README.md",
+    "**/CHANGELOG.md",
+];
+/** Built-in when `env.files` is absent — the pair the walk hardcoded before it
+ *  was authorable, in the order it applied them. */
+export const DEFAULT_ENV_FILES = [".env", ".env.local"];

package/dist/resolve-ref-sentinels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-ref-sentinels.d.ts","sourceRoot":"","sources":["../src/resolve-ref-sentinels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAGlC;+CAC+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAK5C,kBAAkB,GAAE,gBAAgB,EAAO;AAC3C;;+CAE+C;AAC/C,IAAI,CAAC,EAAE,mBAAmB,GACzB,IAAI,CAyIN"}
+{"version":3,"file":"resolve-ref-sentinels.d.ts","sourceRoot":"","sources":["../src/resolve-ref-sentinels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC;+CAC+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAK5C,kBAAkB,GAAE,gBAAgB,EAAO;AAC3C;;+CAE+C;AAC/C,IAAI,CAAC,EAAE,mBAAmB,GACzB,IAAI,CAyIN"}

package/dist/resolve-ref-sentinels.js

@@ -1,6 +1,7 @@
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { isScopeEntry, resolveFieldEntries, } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { isForwardedDeclaration, isForwardedExport } from "./forwarded-declaration.js";
 /**
  * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
  * to `{kind, name}` (local) or `{kind, name, alias}` (cross-module), in place.
@@ -48,9 +49,10 @@ crossModuleTargets = [],
  *  it shadows — so both call sites pass it. */
 defs) {
     const moduleOf = (r) => r.metadata?.module;
-    // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
-    // cross-module resolution targets only — never walked as local ref sources here.
-    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    // A dependency's code — a forwarded export, or what extraction pulled out of one — is
+    // never walked as a local ref source here and never a local name; only an EXPORT is a
+    // cross-module resolution target.
+    const isForeign = isForwardedDeclaration;
     // Local resources resolve a bare / `Self.`-qualified name; forwarded foreign exports
     // resolve an `Alias.`-qualified name keyed by (module, name).
     const byName = new Map();
@@ -60,14 +62,15 @@ defs) {
             continue;
         const name = r.metadata.name;
         if (isForeign(r)) {
-            byModuleName.set(`${moduleOf(r)}\0${name}`, r);
+            if (isForwardedExport(r))
+                byModuleName.set(`${moduleOf(r)}\0${name}`, r);
         }
         else {
             byName.set(name, r);
         }
     }
     for (const r of crossModuleTargets) {
-        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForwardedExport(r))
             continue;
         byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
     }

package/dist/resolve-throws-union.d.ts

@@ -1,6 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { type AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { type RefSlot, type RefUse } from "./ref-slot.js";
 export interface ThrowsCodeMeta {
     data?: Record<string, any>;
 }
@@ -56,11 +57,31 @@ export interface ResolveCtx {
 }
 export declare function createResolveCtx(allManifests: ResourceManifest[], defs: DefinitionRegistry, aliases: AliasResolver, aliasesByModule?: Map<string, AliasResolver>, rootModules?: Set<string>, moduleManifests?: Map<string, ResourceManifest[]>): ResolveCtx;
 /** Resolve the effective throw union for a named manifest. The result combines
- *  explicit `throws.codes`, `throws.inherit: true` dataflow (step-context
- *  traversal with try/catch subtraction), and unbounded markers for
- *  unresolvable passthrough call sites. Cycles short-circuit to an empty
- *  result so resolution always terminates. */
+ *  explicit `throws.codes`, `throws.inherit: true` dataflow (step bodies with
+ *  try/catch subtraction, plus reference slots that hand a failure back), and
+ *  unbounded markers for unresolvable passthrough call sites. Cycles
+ *  short-circuit to an empty result so resolution always terminates. */
 export declare function resolveThrowsUnion(manifest: ResourceManifest, ctx: ResolveCtx): ThrowsUnion;
+/**
+ * True for a use through which a target's failure reaches the declaring
+ * resource's CALLER: `call` returns into my invocation, and `trigger.consumer`
+ * rejects the value my caller drains. `detached` and `trigger.inbound` run where
+ * no caller of mine awaits them; `dependency` and `schema` dispatch nothing.
+ *
+ * The reduction `inherit` is read through — by the resolver and by the check
+ * that a definition declaring it has something to inherit from.
+ */
+export declare function handsFailureBack(use: RefUse): boolean;
+/**
+ * The uses a throws consumer reads off a slot. A slot that declares no use —
+ * the legacy bare-string form — reads as `call`: the throws union must assume
+ * `call` to keep an error path, the direction the call graph takes for the same
+ * slot. The zone projection reads it the opposite way, deliberately.
+ *
+ * `uses` defaults to every use the slot can take; a consumer that resolved the
+ * slot's case map for one instance passes that answer instead.
+ */
+export declare function throwsUses(slot: RefSlot, uses?: readonly RefUse[]): readonly RefUse[];
 /**
  * The union a SCOPE-LEVEL `catches:` list can be asked to render — everything
  * the resource it is written on drives, transitively.

package/dist/resolve-throws-union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAKnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;gFAEgF;AAChF,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;gDAI4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB;;;wFAGoF;IACpF,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC5C,0FAA0F;IAC1F,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACjD;uEACmE;IACnE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,EACpC,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAa,GAC3D,UAAU,CAWZ;AA2HD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CAiDb;AAiCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE,UAAU,EACf,IAAI,GAAE,GAAG,CAAC,gBAAgB,CAAa,GACtC,WAAW,CAmCb;AAkMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,gBAAgB,GAAG,SAAS,CAsB9B"}
+{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,MAAM,EACZ,MAAM,eAAe,CAAC;AAIvB,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;gFAEgF;AAChF,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;gDAI4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB;;;wFAGoF;IACpF,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC5C,0FAA0F;IAC1F,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACjD;uEACmE;IACnE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,EACpC,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAa,GAC3D,UAAU,CAWZ;AA2HD;;;;wEAIwE;AACxE,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CAiDb;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,SAAS,MAAM,EAAuB,GAC3C,SAAS,MAAM,EAAE,CAEnB;AAuCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE,UAAU,EACf,IAAI,GAAE,GAAG,CAAC,gBAAgB,CAAa,GACtC,WAAW,CAkCb;AAiND;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,gBAAgB,GAAG,SAAS,CAsB9B"}