opensquid 0.5.395

package/dist/packs/guards_compiler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * T-PACK-FSM-STANDARDIZATION slice B — `guards` -> synthetic skill compilation.
+ *
+ * A Guard is the GENERAL form of the detect→verdict skeleton that ~23/24 skills
+ * hand-respell (e.g. `default-discipline/skills/git/skill.yaml`'s two rules).
+ * Each guard compiles into one `TrackCheckRule` whose process is `[detect?,
+ * verdict]`, grouped under the synthetic skill `<pack>/guards`:
+ *
+ *   - `detect` (optional) — a generic primitive call bound via `as`. Omitted
+ *     for a check-only guard (the `verify_gate` shape).
+ *   - `verdict` — fired conditionally via `step.if = guard.when`, the same
+ *     `if:` expression engine + 5-fn allow-list the hand-written rules use.
+ *
+ * This is the reusable gate TEMPLATE: the skeleton lives HERE (in the
+ * compiler), so authors declare only the shape's parameters. The output is the
+ * EXACT `ProcessStep[]` an author would hand-write, so the runtime interpreter
+ * is unchanged (proven byte-identical in `guards_compiler.test.ts`).
+ *
+ * `verify_gates_compiler.ts` is the detect-less special case of this; the two
+ * stay separate while `verify_gates` keeps its own schema (a later slice may
+ * fold verify_gates into guards once the template surface settles).
+ *
+ * Pure: no I/O. Caller (`loader.ts`) appends the synthetic skill into
+ * `pack.skills` alongside hand-authored skills and the `<pack>/verify` skill.
+ *
+ * Audit trail: each compiled rule's `id` is `guard:<name>` so a drift-catalog
+ * grep can attribute the verdict to its source guard.
+ */
+import type { SkillType } from './schemas/index.js';
+import type { Guard } from './schemas/manifest.js';
+export interface GuardsCompileSuccess {
+    ok: true;
+    skill: SkillType;
+}
+export interface GuardsCompileFailure {
+    ok: false;
+    errors: readonly {
+        guardName: string;
+        message: string;
+    }[];
+}
+export type GuardsCompileResult = GuardsCompileSuccess | GuardsCompileFailure;
+/**
+ * Compile `guards` into a single synthetic skill `<pack>/guards`. When `guards`
+ * is empty the result is `{ok: true, skill}` with a zero-rule skill — callers
+ * SHOULD filter out empty-rule skills before appending (matches
+ * `compileVerifyGates`). A `when` expression that fails to parse is collected
+ * (with its guard name) and surfaced as `{ok: false, errors}` — no silent skip.
+ */
+export declare function compileGuards(packName: string, guards: readonly Guard[]): GuardsCompileResult;
+//# sourceMappingURL=guards_compiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guards_compiler.d.ts","sourceRoot":"","sources":["../../src/packs/guards_compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,SAAS,EAA6B,MAAM,oBAAoB,CAAC;AAE/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGnD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,SAAS,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3D;AACD,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,mBAAmB,CAkD7F"}

package/dist/packs/guards_compiler.js

@@ -0,0 +1,56 @@
+import { parseExpression } from '../runtime/evaluator/expression/index.js';
+import { DEFAULT_TRIGGERS } from '../runtime/event.js';
+/**
+ * Compile `guards` into a single synthetic skill `<pack>/guards`. When `guards`
+ * is empty the result is `{ok: true, skill}` with a zero-rule skill — callers
+ * SHOULD filter out empty-rule skills before appending (matches
+ * `compileVerifyGates`). A `when` expression that fails to parse is collected
+ * (with its guard name) and surfaced as `{ok: false, errors}` — no silent skip.
+ */
+export function compileGuards(packName, guards) {
+    const errors = [];
+    const rules = [];
+    for (const guard of guards) {
+        try {
+            parseExpression(guard.when);
+        }
+        catch (e) {
+            errors.push({
+                guardName: guard.name,
+                message: `when failed to parse: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            continue;
+        }
+        const process = [];
+        if (guard.detect !== undefined) {
+            process.push({
+                call: guard.detect.call,
+                ...(guard.detect.args !== undefined ? { args: guard.detect.args } : {}),
+                as: guard.as,
+            });
+        }
+        process.push({
+            call: 'verdict',
+            if: guard.when,
+            args: { level: guard.level, message: guard.message },
+        });
+        rules.push({ id: `guard:${guard.name}`, kind: 'track_check', requires: [], process });
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    // Triggers: one per guard's event kind, deduped (matches compileVerifyGates).
+    const kinds = new Set(guards.map((g) => g.on));
+    const triggers = guards.length === 0 ? [...DEFAULT_TRIGGERS] : [...kinds].map((kind) => ({ kind }));
+    const skill = {
+        name: `${packName}/guards`,
+        load: 'lazy',
+        when_to_load: [],
+        requires: [],
+        unloads_when: [],
+        triggers,
+        rules,
+        tools: [],
+    };
+    return { ok: true, skill };
+}
+//# sourceMappingURL=guards_compiler.js.map

package/dist/packs/guards_compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards_compiler.js","sourceRoot":"","sources":["../../src/packs/guards_compiler.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,EAAE,gBAAgB,EAAgB,MAAM,qBAAqB,CAAC;AAYrE;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,MAAwB;IACtE,MAAM,MAAM,GAA6C,EAAE,CAAC;IAC5D,MAAM,KAAK,GAAe,EAAE,CAAC;IAE7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC;gBACV,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,OAAO,EAAE,yBAAyB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;aAC/E,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI;gBACvB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvE,EAAE,EAAE,KAAK,CAAC,EAAE;aACb,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,SAAS;YACf,EAAE,EAAE,KAAK,CAAC,IAAI;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;SACrD,CAAC,CAAC;QAEH,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAEpD,8EAA8E;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,CAAkB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GACZ,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAErF,MAAM,KAAK,GAAc;QACvB,IAAI,EAAE,GAAG,QAAQ,SAAS;QAC1B,IAAI,EAAE,MAAM;QACZ,YAAY,EAAE,EAAE;QAChB,QAAQ,EAAE,EAAE;QACZ,YAAY,EAAE,EAAE;QAChB,QAAQ;QACR,KAAK;QACL,KAAK,EAAE,EAAE;KACV,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC"}

package/dist/packs/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Packs: multi-file pack format loader, manifest resolution, and schema
+ * validation for the bundled YAML schemas.
+ *
+ * Imports from: functions/ (for validation), runtime/ types only.
+ * Imported by: runtime/, setup/, mcp/.
+ */
+export * from './schemas/index.js';
+export { parseYamlFile, parseYamlString, serializeYamlDocument } from './yaml.js';
+export type { ParsedYaml } from './yaml.js';
+export { loadPack } from './loader.js';
+export { validatePackFunctions } from './validate_functions.js';
+export type { ValidationIssue } from './validate_functions.js';
+export { validateUniqueSkillNames } from './validate_uniqueness.js';
+export type { UniquenessIssue } from './validate_uniqueness.js';
+export { sortPacksByScope } from './load_order.js';
+export { applyExtends, detectExtendsCycle } from './apply_extends.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/packs/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,oBAAoB,CAAC;AAKnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAK5C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/packs/index.js

@@ -0,0 +1,33 @@
+/**
+ * Packs: multi-file pack format loader, manifest resolution, and schema
+ * validation for the bundled YAML schemas.
+ *
+ * Imports from: functions/ (for validation), runtime/ types only.
+ * Imported by: runtime/, setup/, mcp/.
+ */
+export * from './schemas/index.js';
+// YAML parser layer (Task 2.2) — single load boundary for pack-config YAML.
+// `parseYamlFile<T>` validates with a Zod schema and returns both the parsed
+// data + the underlying `Document.Parsed` for comment-preserving writeback.
+export { parseYamlFile, parseYamlString, serializeYamlDocument } from './yaml.js';
+// Pack folder loader (Task 2.3) — read a directory on disk into a typed `Pack`.
+// Reads `manifest.yaml` + scans `skills/<name>/skill.yaml`. Side-files
+// (models/channels/notifications/drift_response) live in separate consumers.
+export { loadPack } from './loader.js';
+// Function-reference validation (Task 2.4) — confirm every `process[*].call`
+// resolves to a registered primitive. Returns issues (with optional typo
+// suggestions); never throws so the orchestrator can collect across packs.
+export { validatePackFunctions } from './validate_functions.js';
+// Skill-name uniqueness validation (Task 2.5) — run at load-orchestrator time
+// over every loaded pack; surfaces collisions without auto-resolving per
+// design doc §"Conflict resolution policy".
+export { validateUniqueSkillNames } from './validate_uniqueness.js';
+// Scope-precedence pack ordering (Task 5.1) — stable sort by scope index
+// (universal → domain → specialty → workflow → project) then alphabetical
+// by name. Pure function consumed by the load-orchestrator.
+export { sortPacksByScope } from './load_order.js';
+// `extends:` mechanism (Task 5.2) — layer a child pack over a parent pack
+// with child-wins-on-collision semantics, plus a cycle detector for the
+// `extends:` chain. Validation-layer companion to the load orchestrator.
+export { applyExtends, detectExtendsCycle } from './apply_extends.js';
+//# sourceMappingURL=index.js.map

package/dist/packs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/packs/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,oBAAoB,CAAC;AAEnC,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGlF,gFAAgF;AAChF,uEAAuE;AACvE,6EAA6E;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,6EAA6E;AAC7E,yEAAyE;AACzE,2EAA2E;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,8EAA8E;AAC9E,yEAAyE;AACzE,4CAA4C;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,yEAAyE;AACzE,0EAA0E;AAC1E,4DAA4D;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/packs/living_pack.d.ts

@@ -0,0 +1,17 @@
+export interface LivingPackVersion {
+    /** semver string the pack was installed at. */
+    base: string;
+    /** monotonic count of promoted lessons. 0 = fresh install with no promotions. */
+    revision: number;
+}
+/**
+ * Read the user-scope personal_revision/version.json for `packId` and
+ * return a `{base, revision}` triple. Returns null when:
+ *  - the pack isn't user-installed (no `~/.opensquid/packs/<id>/` dir)
+ *  - version.json is absent (fresh install before any promotion)
+ *
+ * Throws on malformed JSON (LP.1 contract — engine-written file,
+ * unexpected content is a real bug worth surfacing).
+ */
+export declare function getLivingPackVersion(packId: string): Promise<LivingPackVersion | null>;
+//# sourceMappingURL=living_pack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"living_pack.d.ts","sourceRoot":"","sources":["../../src/packs/living_pack.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAK5F"}

package/dist/packs/living_pack.js

@@ -0,0 +1,41 @@
+/**
+ * DOG.5 — Living-pack version-triple convenience reader.
+ *
+ * Builds on LP.1's `readVersionJson` + LP.3's `resolvePackStateDir` to
+ * answer the single question "what's <pack>'s base.rev version triple
+ * RIGHT NOW?" without callers needing to know the underlying file layout.
+ *
+ * Returns null when:
+ *   - the pack has no personal_revision/version.json (built-in pack the
+ *     user hasn't installed; fresh-install before first lesson promotion)
+ *   - OPENSQUID_HOME is set to a sandbox without the pack directory (tests)
+ *
+ * Returns `{base, revision}` otherwise.
+ *
+ * Loader (`src/packs/loader.ts`) calls this once per pack at load time
+ * and folds the result into `Pack.livingVersion` for the runtime
+ * dispatcher + diagnostic surface to read without re-touching disk.
+ *
+ * NOT a long-lived cache — every call re-reads the JSON. Caching belongs
+ * to the loader (one-shot at load) + the merge cache from LP.5
+ * (per-session keyed on revision-id).
+ */
+import { resolvePackStateDir } from './discovery.js';
+import { readVersionJson } from './personal_revision.js';
+/**
+ * Read the user-scope personal_revision/version.json for `packId` and
+ * return a `{base, revision}` triple. Returns null when:
+ *  - the pack isn't user-installed (no `~/.opensquid/packs/<id>/` dir)
+ *  - version.json is absent (fresh install before any promotion)
+ *
+ * Throws on malformed JSON (LP.1 contract — engine-written file,
+ * unexpected content is a real bug worth surfacing).
+ */
+export async function getLivingPackVersion(packId) {
+    const stateDir = resolvePackStateDir(packId, 'user');
+    const version = await readVersionJson(stateDir);
+    if (version === null)
+        return null;
+    return { base: version.base_version, revision: version.personal_revision_id };
+}
+//# sourceMappingURL=living_pack.js.map

package/dist/packs/living_pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"living_pack.js","sourceRoot":"","sources":["../../src/packs/living_pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AASzD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAc;IACvD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;AAChF,CAAC"}

package/dist/packs/load_order.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pack load-order: scope-precedence + alphabetical-within-scope stable sort.
+ *
+ * Per `docs/opensquid-real-design.md` §"Pack format" scope levels. Scope is a
+ * LAYERING HINT — universal sets baseline conventions, project pins
+ * project-specific overrides, with three intermediate layers. The runtime
+ * walks the sorted list when applying load conditions, surfacing rules, and
+ * accumulating verdicts; ordering matters because later packs see prior
+ * packs' state in the same evaluation window.
+ *
+ * The order is intentionally fixed (universal → domain → specialty → workflow
+ * → project) rather than user-configurable per pack: pack authors declare
+ * scope, not priority. Two packs at the same scope are sorted alphabetically
+ * by `name` for determinism — output is byte-identical across runs given the
+ * same input set. Same-scope name collisions are NOT auto-resolved here;
+ * they surface via `validateUniqueSkillNames` (Task 2.5) at load-orchestrator
+ * time and require an explicit `extends:` or rename per design doc
+ * §"Conflict resolution policy".
+ *
+ * Purity contract: `sortPacksByScope` never mutates its input array (spreads
+ * first), never mutates pack objects (sort is by-reference comparison only),
+ * and is referentially transparent — calling it twice with the same input
+ * produces the same output. This matters for the load-orchestrator audit
+ * trail: re-sorting on every event must not surface phantom diffs.
+ *
+ * Imports from: runtime/types.ts (Pack, Scope).
+ * Imported by: future load-orchestrator (Phase 5 integration); re-exported
+ * via packs/index.ts.
+ */
+import type { Pack } from '../runtime/types.js';
+export declare function sortPacksByScope(packs: Pack[]): Pack[];
+//# sourceMappingURL=load_order.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load_order.d.ts","sourceRoot":"","sources":["../../src/packs/load_order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAS,MAAM,qBAAqB,CAAC;AAavD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAStD"}

package/dist/packs/load_order.js

@@ -0,0 +1,51 @@
+/**
+ * Pack load-order: scope-precedence + alphabetical-within-scope stable sort.
+ *
+ * Per `docs/opensquid-real-design.md` §"Pack format" scope levels. Scope is a
+ * LAYERING HINT — universal sets baseline conventions, project pins
+ * project-specific overrides, with three intermediate layers. The runtime
+ * walks the sorted list when applying load conditions, surfacing rules, and
+ * accumulating verdicts; ordering matters because later packs see prior
+ * packs' state in the same evaluation window.
+ *
+ * The order is intentionally fixed (universal → domain → specialty → workflow
+ * → project) rather than user-configurable per pack: pack authors declare
+ * scope, not priority. Two packs at the same scope are sorted alphabetically
+ * by `name` for determinism — output is byte-identical across runs given the
+ * same input set. Same-scope name collisions are NOT auto-resolved here;
+ * they surface via `validateUniqueSkillNames` (Task 2.5) at load-orchestrator
+ * time and require an explicit `extends:` or rename per design doc
+ * §"Conflict resolution policy".
+ *
+ * Purity contract: `sortPacksByScope` never mutates its input array (spreads
+ * first), never mutates pack objects (sort is by-reference comparison only),
+ * and is referentially transparent — calling it twice with the same input
+ * produces the same output. This matters for the load-orchestrator audit
+ * trail: re-sorting on every event must not surface phantom diffs.
+ *
+ * Imports from: runtime/types.ts (Pack, Scope).
+ * Imported by: future load-orchestrator (Phase 5 integration); re-exported
+ * via packs/index.ts.
+ */
+// Scope index keyed off the runtime `Scope` literal so a future scope
+// addition fails the typechecker until this map is updated (rather than
+// silently returning `undefined - 0 = NaN` at sort time).
+const SCOPE_ORDER = {
+    universal: 0,
+    domain: 1,
+    specialty: 2,
+    workflow: 3,
+    project: 4,
+};
+export function sortPacksByScope(packs) {
+    // Spread before sort — `Array.prototype.sort` mutates in place. The
+    // load-orchestrator passes its internal pack list straight through and we
+    // must not mutate the source-of-truth array.
+    return [...packs].sort((a, b) => {
+        const d = SCOPE_ORDER[a.scope] - SCOPE_ORDER[b.scope];
+        if (d !== 0)
+            return d;
+        return a.name.localeCompare(b.name);
+    });
+}
+//# sourceMappingURL=load_order.js.map

package/dist/packs/load_order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load_order.js","sourceRoot":"","sources":["../../src/packs/load_order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,sEAAsE;AACtE,wEAAwE;AACxE,0DAA0D;AAC1D,MAAM,WAAW,GAA0B;IACzC,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;CACX,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,oEAAoE;IACpE,0EAA0E;IAC1E,6CAA6C;IAC7C,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACtB,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/packs/loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pack folder loader — turn a directory on disk into a typed `Pack`.
+ *
+ * Authoritative source: `docs/opensquid-real-design.md` §"Pack format" folder
+ * layout + Task 2.3 of `docs/tasks/phase-2-pack-format.md`.
+ *
+ * A pack on disk looks like:
+ *
+ *     my-pack/
+ *       manifest.yaml          ← required
+ *       models.yaml            ← optional, FOLDED IN (PR-followup)
+ *       channels.yaml          ← optional, Phase 2.4+ consumer
+ *       notifications.yaml     ← optional, Phase 2.4+ consumer
+ *       drift_response.yaml    ← optional, FOLDED IN (PR-followup)
+ *       chat_agent.yaml        ← optional, FOLDED IN (WAB.6)
+ *       skills/
+ *         <skill-name>/skill.yaml
+ *
+ * This loader is the *only* read path for a pack folder. It does these things:
+ *
+ *   1. Parse `manifest.yaml` through `parseYamlFile` + the `Manifest` schema —
+ *      the four required fields (name/version/scope/goal) plus defaulted rest.
+ *   2. Scan `skills/` (if present) for sub-directories containing a
+ *      `skill.yaml` and parse each through the `Skill` schema.
+ *   3. PR-followup: parse `models.yaml` (if present) → `Pack.models` so the
+ *      LLM-primitive resolver can consult pack-declared aliases.
+ *   4. PR-followup: parse `drift_response.yaml` (if present) → `Pack.driftResponse`
+ *      so the hook dispatcher can resolve per-rule + default policies instead
+ *      of hard-coding `block_tool`.
+ *
+ * Side files `channels.yaml` / `notifications.yaml` remain orthogonal config
+ * consumers (per the original spec risk callout 2) — they wire in via the
+ * notification router when that subsystem lands. The two folded-in side
+ * files above ARE pack-identity-relevant (model aliases shape rule eval;
+ * drift policies shape dispatcher output), so they belong on the Pack.
+ *
+ * Error surface: every failure flows through `parseYamlFile`, which already
+ * threads the source path into both YAML-parse and Zod-validation error
+ * messages. The loader just propagates — no extra wrapping needed at this
+ * layer. (A structured `PackLoadError` may land in a later task when the
+ * setup UI needs to localize messages.)
+ *
+ * Imports from: node:fs/promises, node:path, schemas/, yaml.ts, runtime/types.
+ * Imported by: setup/, runtime bootstrap (Phase 2.4+), test fixtures.
+ */
+import type { Pack } from '../runtime/types.js';
+export declare function loadPack(dir: string): Promise<Pack>;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/packs/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAQH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAuChD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiJzD"}