opensquid 0.5.395

package/dist/packs/composite_resolver.js

@@ -0,0 +1,131 @@
+/**
+ * MM.1 — Composite-pack include expansion at load time.
+ *
+ * Walks every composite pack's `includes: [{pack_id, semver}]` against the
+ * registry of discovered packs (passed in as the input list). Returns an
+ * expanded flat list containing:
+ *   - every original focused pack (in input order)
+ *   - every composite pack (preserved for identity / audit / diagnostics)
+ *   - every focused pack referenced by any composite's includes (deduped
+ *     across composites; first-occurrence-wins for ordering;
+ *     scope-precedence per `sortPacksByScope` preserved when the caller
+ *     applies it AFTER expansion)
+ *
+ * Cycle detection: per-root visited-set keyed on pack name; revisit within
+ * one walk → load-time error with the cycle path.
+ *
+ * Depth-cap: MAX_COMPOSITE_DEPTH (3) levels of nested composite expansion
+ * per audit risk callout (composite-of-composites is allowed but capped).
+ * Exceeding the cap → load-time error.
+ *
+ * Missing include: composite references a pack_id not in the registry →
+ * load-time error with clear path-bearing message naming the composite,
+ * the missing pack_id, and the unsatisfied semver range.
+ *
+ * Semver mismatch: composite references pack_id present in registry but
+ * the registry pack's version does NOT satisfy the composite's semver
+ * range → load-time error naming all three (composite, included pack,
+ * range, found version).
+ *
+ * Pure: no I/O; takes the registry as input. Caller (discovery.ts)
+ * supplies the already-loaded pack list.
+ *
+ * Discovery-time caching contract: composite expansion happens AT DISCOVERY
+ * TIME (not at dispatch time). The expanded list is cached for the session.
+ * A user `pnpm install` of a new pack mid-session won't be picked up until
+ * session restart (matches IDF.3 caching contract).
+ *
+ * Duplicate `pack_id` entries within one composite's includes are allowed by
+ * the schema; the resolver picks first-occurrence semver per
+ * include-order intent.
+ */
+import { satisfies as semverSatisfies, valid as semverValid, validRange as semverValidRange, } from 'semver';
+export const MAX_COMPOSITE_DEPTH = 3;
+export class CompositeResolutionError extends Error {
+    compositePack;
+    cause;
+    constructor(message, compositePack, cause) {
+        super(message);
+        this.compositePack = compositePack;
+        this.cause = cause;
+        this.name = 'CompositeResolutionError';
+    }
+}
+/**
+ * Expand composite packs into their includes. Returns the flat list per the
+ * module-header contract. Throws `CompositeResolutionError` on cycle,
+ * depth-exceeded, missing include, semver-mismatch, or invalid-semver.
+ */
+export function expandComposites(packs) {
+    const registry = new Map();
+    for (const p of packs)
+        registry.set(p.name, p);
+    const out = [];
+    const seen = new Set();
+    for (const pack of packs) {
+        const kind = pack.kind ?? 'focused';
+        if (kind === 'composite') {
+            if (!seen.has(pack.name)) {
+                out.push(pack);
+                seen.add(pack.name);
+            }
+            const state = {
+                visited: new Set([pack.name]),
+                depth: 0,
+                rootComposite: pack.name,
+            };
+            walkIncludes(pack, registry, state, out, seen);
+        }
+        else {
+            if (!seen.has(pack.name)) {
+                out.push(pack);
+                seen.add(pack.name);
+            }
+        }
+    }
+    return out;
+}
+function walkIncludes(composite, registry, state, out, seen) {
+    if (state.depth >= MAX_COMPOSITE_DEPTH) {
+        throw new CompositeResolutionError(`composite ${state.rootComposite}: include-expansion depth exceeded ${String(MAX_COMPOSITE_DEPTH)} levels (chain: ${[...state.visited].join(' → ')})`, state.rootComposite, 'depth-exceeded');
+    }
+    const includes = composite.includes ?? [];
+    for (const inc of includes) {
+        if (!isValidRange(inc.semver)) {
+            throw new CompositeResolutionError(`composite ${composite.name}: include "${inc.pack_id}" has invalid semver range "${inc.semver}"`, composite.name, 'invalid-semver');
+        }
+        const found = registry.get(inc.pack_id);
+        if (found === undefined) {
+            throw new CompositeResolutionError(`composite ${composite.name}: include "${inc.pack_id}@${inc.semver}" — no pack with that name in the registry (registry has ${String(registry.size)} packs)`, composite.name, 'missing-include');
+        }
+        if (!semverSatisfies(found.version, inc.semver)) {
+            throw new CompositeResolutionError(`composite ${composite.name}: include "${inc.pack_id}@${inc.semver}" — registry has version ${found.version} which does NOT satisfy range`, composite.name, 'semver-mismatch');
+        }
+        if (state.visited.has(found.name)) {
+            throw new CompositeResolutionError(`composite ${state.rootComposite}: include cycle detected (chain: ${[...state.visited].join(' → ')} → ${found.name})`, state.rootComposite, 'cycle');
+        }
+        if (!seen.has(found.name)) {
+            out.push(found);
+            seen.add(found.name);
+        }
+        if ((found.kind ?? 'focused') === 'composite') {
+            walkIncludes(found, registry, {
+                visited: new Set([...state.visited, found.name]),
+                depth: state.depth + 1,
+                rootComposite: state.rootComposite,
+            }, out, seen);
+        }
+    }
+}
+/**
+ * semver.valid accepts only pinned versions ('1.0.0'); semver.validRange
+ * returns the parsed range string or null. We accept anything either lib
+ * recognizes. semver.satisfies tolerates malformed input by returning false
+ * (not throwing) so isValidRange must NOT rely on satisfies' throw behavior.
+ */
+function isValidRange(s) {
+    if (semverValid(s) !== null)
+        return true;
+    return semverValidRange(s) !== null;
+}
+//# sourceMappingURL=composite_resolver.js.map

package/dist/packs/composite_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite_resolver.js","sourceRoot":"","sources":["../../src/packs/composite_resolver.ts"],"names":[],"mappings":"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"}

package/dist/packs/discovery.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Active-pack discovery — scan a scope root for `active.json` + `packs/<name>/`.
+ *
+ * G.1 wires the real loader path. Given a scope root (either user-scope from
+ * `resolveUserScopeRoot()` or project-scope from `resolveProjectScopeRoot(cwd)`),
+ * this module:
+ *
+ *   1. Reads `<scopeRoot>/active.json` — schema `{ packs: string[] }`.
+ *   2. For each entry, loads `<scopeRoot>/packs/<name>/` through the
+ *      existing `loadPack` (Phase-2 pack format: `manifest.yaml` + `skills/`).
+ *
+ * Behavior contract:
+ *   - `scopeRoot === null`           → returns `[]` (project absent case).
+ *   - `active.json` ENOENT           → returns `[]` (scope present, no opt-in).
+ *   - `active.json` malformed JSON   → throws path-bearing error.
+ *   - `active.json` missing `packs:` → throws with clear "missing field" message.
+ *   - `active.json` references a pack folder that doesn't exist or fails to
+ *     load → `loadPack` throws; we propagate verbatim.
+ *
+ * Fail-loud is intentional per `project_opensquid_runtime_failure_handling`
+ * memory: a user-authored config bug must surface, not silent-fail to the
+ * "allow everything" path. The two test seams in `bootstrap.ts`
+ * (`OPENSQUID_TEST_PACK`, `OPENSQUID_TEST_PACK_DIR`) keep their own
+ * fail-open contracts because their fixtures are opensquid-authored, not
+ * user-authored.
+ *
+ * Harness-agnostic: this module knows nothing about Claude Code, hook
+ * formats, or any consumer-side concept. The settings-writer that lives in
+ * `src/setup/wizard/` is the ONLY G.1 module that names the consumer.
+ *
+ * Imports from: node:fs/promises, node:path, packs/loader.
+ * Imported by: src/runtime/bootstrap.ts (the real loader path).
+ */
+import { type DetectionContext } from '../runtime/detection.js';
+import type { Pack } from '../runtime/types.js';
+import { type MergeResult } from '../runtime/versioning.js';
+/** LP.5 — bootstrap calls this on SessionStart to clear per-session cache. */
+export declare function clearMergeCache(): void;
+/** LP.5 — exposed for tests to peek cached count. */
+export declare function _mergeCacheSize(): number;
+/**
+ * LP.5 — lazy 3-way merge trigger. For an installed pack at `packStateDir`,
+ * check whether the on-disk vanilla is newer than the recorded base AND has
+ * lessons to preserve AND hasn't been merged yet. If so, trigger LP.2's
+ * runThreeWayMerge against the vanilla source (passed in as `vanillaDir`).
+ *
+ * Cached per-session — same (packId, base, vanilla, revisionId) tuple
+ * resolves once per session lifetime.
+ *
+ * Returns null in any skip-merge case (not installed, no lessons, already
+ * merged, not an upgrade). Returns the MergeResult when the merge actually
+ * runs.
+ *
+ * Per L10 LAZY: NO background poller; this fires on next discovery only.
+ * Per L11 IMMUTABLE base_version: only `last_merged_vanilla` mutates;
+ * base_version stays the install-time value.
+ */
+export declare function checkAndMergeUpgrades(packStateDir: string, vanillaManifest: {
+    name: string;
+    version: string;
+}, vanillaDir: string): Promise<MergeResult | null>;
+/**
+ * LP.3 — path-traversal-safe validator for pack ids that come from
+ * potentially-untrusted sources (manifest.yaml name field, CLI input).
+ * Rejects ids containing `/`, `\`, `..`, or starting with `.`. Use before
+ * any path construction with the id.
+ */
+export declare function validatePackId(packId: string): void;
+/**
+ * LP.3 — resolve the on-disk state directory for a pack by id. User scope:
+ * `~/.opensquid/packs/<id>/`. Project scope: `<projectCwd>/.opensquid/
+ * packs/<id>/` (projectCwd required). Path resolver only; does NOT verify
+ * directory exists. Caller mkdir-recursive before writing.
+ *
+ * Honors OPENSQUID_HOME env override (tests). validatePackId is called
+ * before path construction.
+ */
+export declare function resolvePackStateDir(packId: string, scope?: 'user' | 'project', projectCwd?: string): string;
+export interface ActiveJson {
+    /** Pack names (folder names under `packs/`) declared active in this scope. */
+    packs: string[];
+}
+/**
+ * Scan a scope root for active packs. See module header for the full
+ * contract; in short: returns `[]` on the two "scope-absent" branches
+ * (`null` arg, ENOENT active.json) and throws on anything malformed.
+ *
+ * IDF.3 — optional `ctx` second arg gates loading on the per-pack
+ * `detected_by[]` rules via IDF.2's pure evaluator. When `ctx` is
+ * `null`/`undefined`, legacy behavior applies (every opted-in pack
+ * loads). When `ctx` is provided, each opted-in pack only loads if its
+ * `detectedBy` matches the staged context (empty `detectedBy[]` always
+ * matches — back-compat). Opt-in invariant preserved end-to-end: a pack
+ * NOT listed in `active.json` is never loaded by this fn, regardless of
+ * what its `detectedBy` would say.
+ */
+export declare function discoverActivePacks(scopeRoot: string | null, ctx?: DetectionContext | null, builtinRoot?: string | null): Promise<Pack[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/packs/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/packs/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAyB9E,8EAA8E;AAC9E,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,qDAAqD;AACrD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAmBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAClD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAyB7B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAMnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAM,GAAG,SAAkB,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAUR;AAED,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,GAAG,GAAE,gBAAgB,GAAG,IAAW,EACnC,WAAW,GAAE,MAAM,GAAG,IAAW,GAChC,OAAO,CAAC,IAAI,EAAE,CAAC,CAgDjB"}

package/dist/packs/discovery.js

@@ -0,0 +1,255 @@
+/**
+ * Active-pack discovery — scan a scope root for `active.json` + `packs/<name>/`.
+ *
+ * G.1 wires the real loader path. Given a scope root (either user-scope from
+ * `resolveUserScopeRoot()` or project-scope from `resolveProjectScopeRoot(cwd)`),
+ * this module:
+ *
+ *   1. Reads `<scopeRoot>/active.json` — schema `{ packs: string[] }`.
+ *   2. For each entry, loads `<scopeRoot>/packs/<name>/` through the
+ *      existing `loadPack` (Phase-2 pack format: `manifest.yaml` + `skills/`).
+ *
+ * Behavior contract:
+ *   - `scopeRoot === null`           → returns `[]` (project absent case).
+ *   - `active.json` ENOENT           → returns `[]` (scope present, no opt-in).
+ *   - `active.json` malformed JSON   → throws path-bearing error.
+ *   - `active.json` missing `packs:` → throws with clear "missing field" message.
+ *   - `active.json` references a pack folder that doesn't exist or fails to
+ *     load → `loadPack` throws; we propagate verbatim.
+ *
+ * Fail-loud is intentional per `project_opensquid_runtime_failure_handling`
+ * memory: a user-authored config bug must surface, not silent-fail to the
+ * "allow everything" path. The two test seams in `bootstrap.ts`
+ * (`OPENSQUID_TEST_PACK`, `OPENSQUID_TEST_PACK_DIR`) keep their own
+ * fail-open contracts because their fixtures are opensquid-authored, not
+ * user-authored.
+ *
+ * Harness-agnostic: this module knows nothing about Claude Code, hook
+ * formats, or any consumer-side concept. The settings-writer that lives in
+ * `src/setup/wizard/` is the ONLY G.1 module that names the consumer.
+ *
+ * Imports from: node:fs/promises, node:path, packs/loader.
+ * Imported by: src/runtime/bootstrap.ts (the real loader path).
+ */
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { matchesDetectedBy } from '../runtime/detection.js';
+import { runThreeWayMerge } from '../runtime/versioning.js';
+import { expandComposites } from './composite_resolver.js';
+import { loadPack } from './loader.js';
+import { readVersionJson } from './personal_revision.js';
+/**
+ * LP.5 — module-scoped per-session merge cache. Cleared by bootstrap on
+ * SessionStart via `clearMergeCache()`. Key is the (packId, baseVersion,
+ * vanillaVersion, personalRevisionId) tuple — when ANY of those change the
+ * cache is invalid.
+ */
+const mergeCache = new Map();
+function cacheKey(k) {
+    return `${k.packId}@base=${k.baseVersion}@vanilla=${k.vanillaVersion}@rev=${String(k.personalRevisionId)}`;
+}
+/** LP.5 — bootstrap calls this on SessionStart to clear per-session cache. */
+export function clearMergeCache() {
+    mergeCache.clear();
+}
+/** LP.5 — exposed for tests to peek cached count. */
+export function _mergeCacheSize() {
+    return mergeCache.size;
+}
+function semverLtLocal(a, b) {
+    const ap = a
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10));
+    const bp = b
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const d = (ap[i] ?? 0) - (bp[i] ?? 0);
+        if (d < 0)
+            return true;
+        if (d > 0)
+            return false;
+    }
+    return false;
+}
+/**
+ * LP.5 — lazy 3-way merge trigger. For an installed pack at `packStateDir`,
+ * check whether the on-disk vanilla is newer than the recorded base AND has
+ * lessons to preserve AND hasn't been merged yet. If so, trigger LP.2's
+ * runThreeWayMerge against the vanilla source (passed in as `vanillaDir`).
+ *
+ * Cached per-session — same (packId, base, vanilla, revisionId) tuple
+ * resolves once per session lifetime.
+ *
+ * Returns null in any skip-merge case (not installed, no lessons, already
+ * merged, not an upgrade). Returns the MergeResult when the merge actually
+ * runs.
+ *
+ * Per L10 LAZY: NO background poller; this fires on next discovery only.
+ * Per L11 IMMUTABLE base_version: only `last_merged_vanilla` mutates;
+ * base_version stays the install-time value.
+ */
+export async function checkAndMergeUpgrades(packStateDir, vanillaManifest, vanillaDir) {
+    const version = await readVersionJson(packStateDir);
+    if (version === null)
+        return null;
+    if (version.personal_revision_id === 0)
+        return null;
+    if (version.last_merged_vanilla === vanillaManifest.version)
+        return null;
+    if (!semverLtLocal(version.base_version, vanillaManifest.version))
+        return null;
+    const key = cacheKey({
+        packId: vanillaManifest.name,
+        baseVersion: version.base_version,
+        vanillaVersion: vanillaManifest.version,
+        personalRevisionId: version.personal_revision_id,
+    });
+    const cached = mergeCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const result = await runThreeWayMerge({
+        packId: vanillaManifest.name,
+        baseDir: join(packStateDir, 'base'),
+        personalStateDir: packStateDir,
+        vanillaDir,
+        vanillaVersion: vanillaManifest.version,
+    });
+    mergeCache.set(key, result);
+    return result;
+}
+/**
+ * LP.3 — path-traversal-safe validator for pack ids that come from
+ * potentially-untrusted sources (manifest.yaml name field, CLI input).
+ * Rejects ids containing `/`, `\`, `..`, or starting with `.`. Use before
+ * any path construction with the id.
+ */
+export function validatePackId(packId) {
+    if (packId.length === 0)
+        throw new Error('validatePackId: empty packId');
+    if (packId.startsWith('.'))
+        throw new Error(`validatePackId: packId may not start with "."`);
+    if (/[\\/]|\.\./.test(packId)) {
+        throw new Error(`validatePackId: packId "${packId}" contains path-traversal characters`);
+    }
+}
+/**
+ * LP.3 — resolve the on-disk state directory for a pack by id. User scope:
+ * `~/.opensquid/packs/<id>/`. Project scope: `<projectCwd>/.opensquid/
+ * packs/<id>/` (projectCwd required). Path resolver only; does NOT verify
+ * directory exists. Caller mkdir-recursive before writing.
+ *
+ * Honors OPENSQUID_HOME env override (tests). validatePackId is called
+ * before path construction.
+ */
+export function resolvePackStateDir(packId, scope = 'user', projectCwd) {
+    validatePackId(packId);
+    if (scope === 'project') {
+        if (projectCwd === undefined || projectCwd.length === 0) {
+            throw new Error('resolvePackStateDir: projectCwd required for project scope');
+        }
+        return join(projectCwd, '.opensquid', 'packs', packId);
+    }
+    const home = process.env.OPENSQUID_HOME ?? join(homedir(), '.opensquid');
+    return join(home, 'packs', packId);
+}
+/**
+ * Scan a scope root for active packs. See module header for the full
+ * contract; in short: returns `[]` on the two "scope-absent" branches
+ * (`null` arg, ENOENT active.json) and throws on anything malformed.
+ *
+ * IDF.3 — optional `ctx` second arg gates loading on the per-pack
+ * `detected_by[]` rules via IDF.2's pure evaluator. When `ctx` is
+ * `null`/`undefined`, legacy behavior applies (every opted-in pack
+ * loads). When `ctx` is provided, each opted-in pack only loads if its
+ * `detectedBy` matches the staged context (empty `detectedBy[]` always
+ * matches — back-compat). Opt-in invariant preserved end-to-end: a pack
+ * NOT listed in `active.json` is never loaded by this fn, regardless of
+ * what its `detectedBy` would say.
+ */
+export async function discoverActivePacks(scopeRoot, ctx = null, builtinRoot = null) {
+    if (scopeRoot === null)
+        return [];
+    const activePath = join(scopeRoot, 'active.json');
+    let active;
+    try {
+        const raw = await fs.readFile(activePath, 'utf-8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`opensquid: failed to parse ${activePath} as JSON: ${e.message}`);
+        }
+        active = parsed;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    if (!Array.isArray(active.packs)) {
+        throw new Error(`opensquid: ${activePath} missing required "packs": string[] field`);
+    }
+    // Validate every entry is a non-empty string before we touch the disk —
+    // surfacing a stringly-typed error here is more actionable than the
+    // ENOENT loadPack would surface if we passed `undefined` through join().
+    for (const [i, name] of active.packs.entries()) {
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error(`opensquid: ${activePath} "packs[${String(i)}]" is not a non-empty string`);
+        }
+    }
+    // Pack folders live under `<scope>/packs/`. (The legacy `<scope>/codexes/`
+    // fallback was removed in T-CHAT-AS-TERMINAL's codex→pack standardization —
+    // `packs/` is the sole, standard layout.)
+    const packsDir = join(scopeRoot, 'packs');
+    const packs = [];
+    for (const name of active.packs) {
+        const pack = await loadPackWithBuiltinFallback(name, packsDir, builtinRoot);
+        if (ctx === null || matchesDetectedBy(pack.detectedBy ?? [], ctx)) {
+            packs.push(pack);
+        }
+    }
+    // MM.1 (2026-05-30) — expand composite packs into their includes after
+    // per-pack detected_by gating. Composite identity is preserved (the
+    // composite stays in the list for audit); its included focused packs are
+    // appended (deduped first-occurrence-wins). Errors throw
+    // CompositeResolutionError with the composite name + cause.
+    return expandComposites(packs);
+}
+/**
+ * BPDISC — Try to load `<name>` from the scope's packs/ dir; if that path
+ * doesn't exist, fall back to `<builtinRoot>/<name>/`. The fallback only
+ * fires on ENOENT at the manifest level — every other loadPack error
+ * (YAML parse, Zod validation, missing skill file) propagates verbatim
+ * from the user-scope attempt so the user sees the right blame path.
+ *
+ * Why a fallback rather than always-search-both: scope-precedence is
+ * explicit (user-installed wins over built-in even when names collide),
+ * matching the layering contract in pack-runtime.md §1.6.
+ */
+async function loadPackWithBuiltinFallback(name, scopePacksDir, builtinRoot) {
+    const userPath = join(scopePacksDir, name);
+    try {
+        return await loadPack(userPath);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code !== 'ENOENT' || builtinRoot === null)
+            throw e;
+        try {
+            return await loadPack(join(builtinRoot, name));
+        }
+        catch (fallbackErr) {
+            const fbCode = fallbackErr.code;
+            if (fbCode === 'ENOENT') {
+                throw new Error(`opensquid: pack "${name}" listed in active.json was not found at user-scope (${userPath}) OR built-in (${join(builtinRoot, name)}). Either install the pack via \`opensquid pack install\` or drop the entry from active.json.`);
+            }
+            throw fallbackErr;
+        }
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/packs/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/packs/discovery.ts"],"names":[],"mappings":"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"}

package/dist/packs/flows_compiler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * T-FC2-FLOW-TEMPLATES — `flows:` → FSM-fragment expansion (B2: the FLOW half of
+ * the reusable-template thesis; the gate half is `guards:`/`guards_compiler`).
+ *
+ * A flow is a `{template, params}` invocation that a pure expander turns into an
+ * FSM `{states, transitions}` fragment, merged into the hand-authored `fsm.yaml`
+ * machine BEFORE `validateFsm` so totality is checked on the EXPANDED FSM. Mirrors
+ * `guards_compiler`'s contract: a FLAT template registry, fail-LOUD on an unknown
+ * template or invalid params (no silent skip).
+ *
+ * First template: `loopback_gate` — a quality-gate re-do edge (e.g. the guess-audit
+ * loop `researched --guess_found--> researching`). FSM-only (no skills); the
+ * block-while-state pattern is already covered by `guards:`.
+ *
+ * Pure: no I/O. Imported by: `loader.ts` (at the fsm-load site).
+ */
+import type { Transition } from '../runtime/fsm.js';
+import type { Flow } from './schemas/manifest.js';
+export interface FlowExpansion {
+    states: string[];
+    transitions: Transition[];
+}
+export type CompileFlowsResult = {
+    ok: true;
+    expansion: FlowExpansion;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Compile a pack's `flows` into one merged `{states, transitions}` fragment.
+ * Empty `flows` → an empty (no-op) expansion. An unknown template or invalid
+ * params is collected (prefixed with the pack name) and surfaced as
+ * `{ok:false, errors}` — never silently dropped (mirrors `compileGuards`).
+ */
+export declare function compileFlows(packName: string, flows: readonly Flow[]): CompileFlowsResult;
+//# sourceMappingURL=flows_compiler.d.ts.map

package/dist/packs/flows_compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows_compiler.d.ts","sourceRoot":"","sources":["../../src/packs/flows_compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AA6BD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,aAAa,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,kBAAkB,CAwBzF"}

package/dist/packs/flows_compiler.js

@@ -0,0 +1,55 @@
+/**
+ * Pure params→fragment expanders. A new template is purely additive here — no
+ * generalization of this signature until a 2nd/3rd template earns it (the n=1
+ * discipline: the abstraction stays shaped by concrete instances).
+ */
+const FLOW_TEMPLATES = {
+    // loopback_gate: being in `state`, a `trigger` (e.g. an audit-fail) loops back to
+    // `back_to` to redo the region. A loop-back connects two EXISTING spine states, so
+    // it contributes only the edge — both endpoints MUST already be declared in
+    // fsm.yaml. validateFsm (run on the merged machine) then catches a typo'd endpoint.
+    loopback_gate: (params) => {
+        const { state, trigger, back_to } = params;
+        if (typeof state !== 'string' || typeof trigger !== 'string' || typeof back_to !== 'string') {
+            return {
+                ok: false,
+                error: 'loopback_gate requires string params { state, trigger, back_to }',
+            };
+        }
+        return {
+            ok: true,
+            expansion: { states: [], transitions: [{ from: state, on: trigger, to: back_to }] },
+        };
+    },
+};
+/**
+ * Compile a pack's `flows` into one merged `{states, transitions}` fragment.
+ * Empty `flows` → an empty (no-op) expansion. An unknown template or invalid
+ * params is collected (prefixed with the pack name) and surfaced as
+ * `{ok:false, errors}` — never silently dropped (mirrors `compileGuards`).
+ */
+export function compileFlows(packName, flows) {
+    const errors = [];
+    const states = [];
+    const transitions = [];
+    for (const flow of flows) {
+        const expander = FLOW_TEMPLATES[flow.template];
+        if (expander === undefined) {
+            errors.push(`pack ${packName}: unknown flow template "${flow.template}" (known: ${Object.keys(FLOW_TEMPLATES).join(', ')})`);
+            continue;
+        }
+        const result = expander(flow.params);
+        if (!result.ok) {
+            errors.push(`pack ${packName}: ${flow.template}: ${result.error}`);
+            continue;
+        }
+        for (const s of result.expansion.states)
+            if (!states.includes(s))
+                states.push(s);
+        transitions.push(...result.expansion.transitions);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, expansion: { states, transitions } };
+}
+//# sourceMappingURL=flows_compiler.js.map

package/dist/packs/flows_compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows_compiler.js","sourceRoot":"","sources":["../../src/packs/flows_compiler.ts"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH,MAAM,cAAc,GAAsE;IACxF,kFAAkF;IAClF,mFAAmF;IACnF,4EAA4E;IAC5E,oFAAoF;IACpF,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE;QACxB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5F,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,kEAAkE;aAC1E,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,IAAI;YACR,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE;SACpF,CAAC;IACJ,CAAC;CACF,CAAC;AAMF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAsB;IACnE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CACT,QAAQ,QAAQ,4BAA4B,IAAI,CAAC,QAAQ,aAAa,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAChH,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,QAAQ,QAAQ,KAAK,IAAI,CAAC,QAAQ,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YACnE,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjF,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACpD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC;AAC1D,CAAC"}