opensquid 0.5.395

package/dist/packs/loader.js

@@ -0,0 +1,357 @@
+/**
+ * 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 { readdir, stat, readFile as fsReadFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as yamlParse } from 'yaml';
+import { ChatAgentSchema } from './schemas/chat_agent.js';
+import { DriftResponseConfig } from './schemas/drift_response.js';
+import { Manifest } from './schemas/manifest.js';
+import { ModelsConfig } from './schemas/models.js';
+import { Skill } from './schemas/skill.js';
+import { Team } from './schemas/team.js';
+import { getLivingPackVersion } from './living_pack.js';
+import { compileVerifyGates } from './verify_gates_compiler.js';
+import { compileGuards } from './guards_compiler.js';
+import { compileFlows } from './flows_compiler.js';
+import { Fsm, validateFsm } from '../runtime/fsm.js';
+import { parseYamlFile } from './yaml.js';
+// alias to keep the inline team-load block readable
+const fs = { readFile: fsReadFile };
+// ---------------------------------------------------------------------------
+// loadPack — public entry point
+//
+// Returns a fully-typed `Pack` (runtime shape). `extends` is omitted (not set
+// to `undefined`) when the manifest doesn't declare it — `exactOptionalPropertyTypes`
+// in tsconfig.json treats `{ extends: undefined }` and `{}` as different types,
+// so we conditionally spread to avoid that mismatch.
+// ---------------------------------------------------------------------------
+export async function loadPack(dir) {
+    const manifestPath = join(dir, 'manifest.yaml');
+    const { data } = await parseYamlFile(manifestPath, Manifest);
+    // Re-cast to the schema's output type (see ManifestOutput comment above).
+    const manifest = data;
+    const skillsDir = join(dir, 'skills');
+    const skills = await loadSkillsDir(skillsDir);
+    // DOG.3 — compile verify_gates -> synthetic skill `<pack>/verify`. Errors
+    // throw loudly with offending gate name so pack authors get clear feedback.
+    if (manifest.verify_gates.length > 0) {
+        const compileResult = compileVerifyGates(manifest.name, manifest.verify_gates);
+        if (!compileResult.ok) {
+            const details = compileResult.errors.map((e) => `${e.gateName}: ${e.message}`).join('; ');
+            throw new Error(`pack ${manifest.name}: verify_gates compile errors: ${details}`);
+        }
+        if (compileResult.skill.rules.length > 0) {
+            skills.push(compileResult.skill);
+        }
+    }
+    // T-PACK-FSM-STANDARDIZATION slice B — compile guards -> synthetic skill
+    // `<pack>/guards` (the reusable detect→verdict gate template). Same fail-loud
+    // contract as verify_gates: a bad `when` expression throws with the guard
+    // name. Empty-rule skills are filtered to keep dispatcher noise low.
+    if (manifest.guards.length > 0) {
+        const guardsResult = compileGuards(manifest.name, manifest.guards);
+        if (!guardsResult.ok) {
+            const details = guardsResult.errors.map((e) => `${e.guardName}: ${e.message}`).join('; ');
+            throw new Error(`pack ${manifest.name}: guards compile errors: ${details}`);
+        }
+        if (guardsResult.skill.rules.length > 0) {
+            skills.push(guardsResult.skill);
+        }
+    }
+    // DOG.5 — read living-pack version triple from LP.1's version.json. Pure
+    // file read; null when pack isn't user-installed.
+    const livingVersion = await getLivingPackVersion(manifest.name);
+    // (retire-Rust RES-1) seed_lessons engine-ingest removed — it was dead code
+    // (no live caller ever passed an engine to loadPack). `Pack.seedLessons` data
+    // still rides on the manifest below.
+    // chat_agent.yaml — WAB.6 chat-agent binding side-file. OPTIONAL: absence
+    // (ENOENT) is the bind-time signal for "fall back to built-in defaults in
+    // pack_binding.ts". Any other read/parse error surfaces verbatim — a
+    // malformed `chat_agent.yaml` is a configuration bug, not a missing file.
+    const chatAgent = await loadOptionalChatAgent(join(dir, 'chat_agent.yaml'));
+    // models.yaml — PR-followup model-alias side-file. OPTIONAL: absence
+    // (ENOENT) means the pack ships no abstract aliases and the model
+    // resolver should fall back to env-var + user-level config only. Any
+    // other read/parse error surfaces verbatim — a malformed `models.yaml`
+    // is a configuration bug, not a missing file.
+    const models = await loadOptionalModels(join(dir, 'models.yaml'));
+    // drift_response.yaml — PR-followup drift-policy side-file. OPTIONAL:
+    // absence (ENOENT) means the runtime dispatcher should fall back to its
+    // Phase 1 conservative default (`block_tool`) — preserves pre-PR-followup
+    // behavior for packs that don't ship the file. Same parse-error contract.
+    const driftResponse = await loadOptionalDriftResponse(join(dir, 'drift_response.yaml'));
+    // fsm.yaml — T-PACK-FSM-STANDARDIZATION slice A2 pack-lifecycle FSM side-file.
+    // OPTIONAL: absence (ENOENT) → the pack declares no lifecycle FSM (undefined).
+    // When present it MUST be a valid total-transition FSM — validateFsm errors
+    // (a transition targeting an undeclared state, etc.) throw at load with the
+    // offending detail, so a malformed lifecycle is a loud config bug, not a
+    // silently-ignored file.
+    // T-FC2 — compile `flows:` templates into an FSM fragment, merged into the
+    // fsm.yaml machine BEFORE validateFsm so totality holds on the expanded FSM.
+    // Fail loud on an unknown template / bad params (mirrors guards compile above).
+    const flowsResult = compileFlows(manifest.name, manifest.flows);
+    if (!flowsResult.ok) {
+        throw new Error(flowsResult.errors.join('; '));
+    }
+    const fsm = await loadOptionalFsm(join(dir, 'fsm.yaml'), flowsResult.expansion);
+    // MM.1 (2026-05-30) — team.yaml existence check for profession-mode packs.
+    // `usage: profession | both` REQUIRES team.yaml declaring ≥1 SubagentRole.
+    // MM.2 (2026-05-30) extends this: actually LOAD + parse the team.yaml so
+    // the dispatcher's profession-directive validator can validate against it
+    // without re-reading at dispatch time.
+    let team;
+    if (manifest.usage === 'profession' || manifest.usage === 'both') {
+        const teamPath = join(dir, 'team.yaml');
+        try {
+            await stat(teamPath);
+        }
+        catch {
+            throw new Error(`pack ${manifest.name}: usage: ${manifest.usage} REQUIRES team.yaml at ${teamPath} declaring ≥1 SubagentRole (none found)`);
+        }
+        try {
+            const raw = await fs.readFile(teamPath, 'utf8');
+            const parsed = yamlParse(raw);
+            team = Team.parse(parsed);
+        }
+        catch (e) {
+            throw new Error(`pack ${manifest.name}: team.yaml at ${teamPath} failed to parse — ${String(e)}`);
+        }
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        scope: manifest.scope,
+        goal: manifest.goal,
+        description: manifest.description,
+        requires: manifest.requires,
+        conflicts: manifest.conflicts,
+        evolves: manifest.evolves,
+        skills,
+        // IDF.1 (2026-05-30) — fold the 3 new optional manifest fields into the
+        // runtime Pack. `foundation` stays optional (undefined when manifest
+        // omits); `activationScope` + `detectedBy` always present via Zod
+        // defaults applied at parse time.
+        activationScope: manifest.activation_scope,
+        detectedBy: manifest.detected_by,
+        ...(manifest.foundation !== undefined ? { foundation: manifest.foundation } : {}),
+        // MM.1 (2026-05-30) — kind/usage/includes always present via Zod defaults
+        // (focused / active / []).
+        kind: manifest.kind,
+        usage: manifest.usage,
+        includes: manifest.includes,
+        // MM.2 — loaded team.yaml (present iff usage is profession | both).
+        ...(team !== undefined ? { team } : {}),
+        // DOG.3 — manifest schema-sugar blocks hoisted onto runtime Pack so
+        // downstream consumers (audit-trail surface, future fixture sync)
+        // can read without re-parsing manifest YAML.
+        seedLessons: manifest.seed_lessons,
+        verifyGates: manifest.verify_gates,
+        guards: manifest.guards,
+        // DOG.5 — living-pack version triple from LP.1's version.json (if
+        // user-installed). Built-in packs without a personal_revision dir
+        // get undefined here.
+        ...(livingVersion !== null ? { livingVersion } : {}),
+        ...(manifest.extends !== undefined ? { extends: manifest.extends } : {}),
+        ...(chatAgent !== undefined ? { chatAgent } : {}),
+        ...(models !== undefined ? { models } : {}),
+        ...(driftResponse !== undefined ? { driftResponse } : {}),
+        ...(fsm !== undefined ? { fsm } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// loadOptionalChatAgent — read + validate `chat_agent.yaml` if present.
+//
+// ENOENT → returns `undefined` (the side-file is OPTIONAL per the WAB.6 spec
+// — packs that don't ship one fall back to built-in defaults in
+// `pack_binding.ts`). Any other error (YAML parse, schema validation, EACCES)
+// propagates verbatim via `parseYamlFile`'s path-bearing error messages so
+// the caller can blame the right file + field.
+// ---------------------------------------------------------------------------
+async function loadOptionalChatAgent(path) {
+    try {
+        const { data } = await parseYamlFile(path, ChatAgentSchema);
+        return data;
+    }
+    catch (e) {
+        // Node's readFile throws ENOENT as `NodeJS.ErrnoException`. parseYamlFile
+        // forwards the underlying error (it wraps YAML + Zod errors but does NOT
+        // wrap fs errors), so we test the code on the raw exception.
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------
+// loadOptionalModels — read + validate `models.yaml` if present.
+//
+// PR-followup: same ENOENT-as-absent contract as `loadOptionalChatAgent`.
+// Absent file → `undefined`. Parse/schema errors propagate verbatim via
+// `parseYamlFile`'s path-bearing error messages so the user can blame the
+// right file + alias. Re-cast to the schema's output type so defaults (e.g.
+// `args: []`, `description: ''`) are visible to the runtime.
+// ---------------------------------------------------------------------------
+async function loadOptionalModels(path) {
+    try {
+        const { data } = await parseYamlFile(path, ModelsConfig);
+        return data;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------
+// loadOptionalDriftResponse — read + validate `drift_response.yaml` if present.
+//
+// PR-followup: same ENOENT-as-absent contract. The schema is `.strict()` so a
+// typo at the top level (e.g. `defualt:`) fails loudly — important for a
+// safety-critical file. Absent file → `undefined`; the dispatcher then falls
+// back to the Phase 1 conservative `block_tool` default in code (NOT the
+// schema's `block_tool` default — that only fires when the file IS present
+// but omits the field). Keeping the two paths separate means "no file at all"
+// is a distinct signal from "file present with explicit defaults" — useful
+// for the setup-UI diagnostic ("pack X declares no drift_response policy").
+// ---------------------------------------------------------------------------
+async function loadOptionalDriftResponse(path) {
+    try {
+        const { data } = await parseYamlFile(path, DriftResponseConfig);
+        return data;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------
+// loadOptionalFsm — read + validate `fsm.yaml` if present (slice A2).
+//
+// ENOENT → `undefined` (the pack declares no lifecycle FSM). The `Fsm` zod
+// schema validates shape; `validateFsm` then enforces TOTALITY (every
+// transition lands on a declared state, initial is declared). A validation
+// failure throws a path-bearing error so an invalid lifecycle is loud at load
+// — never a silently-ignored machine. parseYamlFile threads the file path into
+// shape/parse errors; we prefix totality errors with the path ourselves.
+// ---------------------------------------------------------------------------
+async function loadOptionalFsm(path, flowExpansion) {
+    let fsm;
+    try {
+        const { data } = await parseYamlFile(path, Fsm);
+        fsm = data;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            fsm = undefined;
+        else
+            throw e;
+    }
+    if (fsm === undefined) {
+        // FC.2: flows AUGMENT a base FSM — a `flows:` block with no fsm.yaml has
+        // nothing to merge into, which is a loud config bug, not a silent no-op.
+        if (flowExpansion !== undefined &&
+            (flowExpansion.states.length > 0 || flowExpansion.transitions.length > 0)) {
+            throw new Error(`${path}: flows: declared but no fsm.yaml to merge into`);
+        }
+        return undefined;
+    }
+    // FC.2: merge the compiled flow fragment (dedup states, append transitions)
+    // BEFORE validateFsm so totality is checked on the EXPANDED machine.
+    if (flowExpansion !== undefined) {
+        const states = [...fsm.states];
+        for (const s of flowExpansion.states)
+            if (!states.includes(s))
+                states.push(s);
+        fsm = { ...fsm, states, transitions: [...fsm.transitions, ...flowExpansion.transitions] };
+    }
+    const errors = validateFsm(fsm);
+    if (errors.length > 0) {
+        throw new Error(`${path}: invalid FSM — ${errors.join('; ')}`);
+    }
+    return fsm;
+}
+// ---------------------------------------------------------------------------
+// loadSkillsDir — scan skills/ for sub-directories with skill.yaml
+//
+// Behavior notes:
+//   - ENOENT on the skills/ directory itself → `[]` (skills/ is optional).
+//   - Entries are SORTED alphabetically before processing. `readdir` order is
+//     filesystem-dependent — APFS isn't guaranteed alphabetical, ext4 + tmpfs
+//     return insertion order. Sorting is what makes load order deterministic
+//     across host OSes (spec risk callout 1).
+//   - Non-directory entries (stray README.md, .DS_Store, etc.) are silently
+//     skipped — only sub-directories with their own `skill.yaml` count.
+//   - Symlinks: `stat` follows symlinks by default, so a `skills/foo → /abs/path`
+//     symlink whose target is a directory is loaded. This is intentional —
+//     documented behavior so users can compose packs by symlinking shared
+//     skills (spec risk callout 3).
+// ---------------------------------------------------------------------------
+async function loadSkillsDir(skillsDir) {
+    let entries;
+    try {
+        entries = await readdir(skillsDir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    // Deterministic ordering — see header comment above.
+    entries.sort();
+    const skills = [];
+    for (const e of entries) {
+        const skillDir = join(skillsDir, e);
+        const st = await stat(skillDir);
+        if (!st.isDirectory())
+            continue;
+        const skillYaml = join(skillDir, 'skill.yaml');
+        const { data } = await parseYamlFile(skillYaml, Skill);
+        // Re-cast to the schema's output type (see ManifestOutput comment above).
+        skills.push(data);
+    }
+    return skills;
+}
+//# sourceMappingURL=loader.js.map

package/dist/packs/loader.js.map

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

package/dist/packs/personal_revision.d.ts

@@ -0,0 +1,82 @@
+import { PersonalRevision, type BaseVersion } from './schemas/manifest.js';
+export interface LessonFile {
+    /** Monotonic ordering id from filename `lesson_<n>.yaml`. */
+    id: number;
+    /** Absolute file path (so callers can copy / read / delete). */
+    path: string;
+    /** Parsed YAML body. */
+    body: Record<string, unknown>;
+    /** True iff file is a `.conflict.yaml` sidecar (unresolved merge state). */
+    hasConflict: boolean;
+}
+/**
+ * Read version.json from a pack's personal_revision directory. Returns null
+ * if directory or file is absent (e.g. fresh install, no lessons yet, OR
+ * built-in pack that has no personal_revision dir). Throws on malformed
+ * JSON or schema-invalid content (loud failure — the file is
+ * engine-written, never user-edited).
+ */
+export declare function readVersionJson(packStateDir: string): Promise<PersonalRevision | null>;
+/**
+ * Write version.json atomically (temp + rename). Creates the
+ * personal_revision/ directory if absent. Uses `<pid>.<rand>` suffix so
+ * concurrent tests (which run in the same process under vitest pool) don't
+ * collide on temp names.
+ */
+export declare function writeVersionJson(packStateDir: string, state: PersonalRevision): Promise<void>;
+/**
+ * Enumerate all lesson_*.yaml + lesson_*.conflict.yaml files in monotonic
+ * order. Returns empty array if directory is absent. Skips malformed-name
+ * files (anything not matching `^lesson_\d+(\.conflict)?\.yaml$`).
+ */
+export declare function readLessonFiles(packStateDir: string): Promise<LessonFile[]>;
+/**
+ * Append a new lesson_<n+1>.yaml atomically. Reads version.json, computes
+ * next id, writes the lesson file (temp + rename), bumps
+ * personal_revision_id in version.json. Returns the new id.
+ *
+ * NOT concurrency-safe across processes — caller must serialize.
+ */
+export declare function appendLessonFile(packStateDir: string, lessonBody: Record<string, unknown>): Promise<number>;
+/**
+ * Initialize a fresh personal_revision/ directory for a newly installed pack.
+ * Writes version.json with personal_revision_id=0 + supplied base_version.
+ * Idempotent: re-running for an already-initialized pack returns existing
+ * state without overwriting.
+ */
+export declare function initPersonalRevision(packStateDir: string, baseVersion: BaseVersion): Promise<PersonalRevision>;
+/**
+ * LP.3 — high-level "a Stage-2-promoted lesson lands in this pack's
+ * personal_revision/ directory" helper. Ensures version.json exists
+ * (idempotent init at `'0.0.0'` default — caller should pass a real
+ * baseline via `initPersonalRevision` first when known), then appends the
+ * lesson as `lesson_<n+1>.yaml` + bumps `personal_revision_id`.
+ *
+ * Lesson body shape per LP.3 spec:
+ *   promoted_at: ISO-8601 timestamp
+ *   engine_lesson_id: string (the engine's lesson id for reconciliation)
+ *   lesson_body: any (engine's lesson content)
+ *   cited_memory_ids: string[]
+ *   skill: string (originating skill name, optional)
+ *   retired: boolean (default false; user can flip via CLI later)
+ *
+ * Returns the new revision id. Throws on personal_revision write failure
+ * — caller must surface (NO silent swallow per [[feedback_no_silent_fail_open]]).
+ *
+ * Imported by: store_lesson primitive (LP.3 wiring follow-up); CLI install
+ * path (LP.4).
+ */
+export interface PromotedLessonInput {
+    /** Engine-side lesson id for reconciliation. */
+    engine_lesson_id: string;
+    /** Engine-side lesson body. */
+    lesson_body: unknown;
+    /** Memory ids cited by the lesson. */
+    cited_memory_ids?: string[];
+    /** Originating skill name (optional — engine-direct lessons omit). */
+    skill?: string;
+    /** Pack base version (passed at install time; defensive '0.0.0' default). */
+    packBaseVersion?: BaseVersion;
+}
+export declare function persistPromotedLesson(packStateDir: string, lesson: PromotedLessonInput): Promise<number>;
+//# sourceMappingURL=personal_revision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"personal_revision.d.ts","sourceRoot":"","sources":["../../src/packs/personal_revision.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE3E,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,EAAE,OAAO,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAW5F;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsBjF;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,eAAe,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/packs/personal_revision.js

@@ -0,0 +1,158 @@
+/**
+ * LP.1 — Helpers for the per-pack personal_revision state directory at
+ * `~/.opensquid/packs/<pack-id>/personal_revision/`.
+ *
+ * Layout:
+ *   version.json                — { base_version, personal_revision_id, last_merged_vanilla }
+ *   lesson_<n>.yaml             — one promoted lesson per file (n monotonic from 1)
+ *   lesson_<n>.conflict.yaml    — sidecar emitted by LP.2 merger on overlap
+ *
+ * Atomicity invariant: every write goes via `<file>.tmp.<pid>` + `fs.rename`
+ * so a crash mid-write leaves the prior version intact.
+ *
+ * Per [[feedback_stop_haiku_drift]] L4 / no-LLM-in-hot-path: pure I/O + YAML
+ * parse; no model calls.
+ *
+ * Concurrency: `appendLessonFile` is NOT cross-process safe in v1. wedge/
+ * promote.ts runs single-threaded per promotion; the helper inherits that
+ * assumption. If multi-process promotion ever lands, wrap with
+ * proper-lockfile.
+ *
+ * Imports: node:fs/promises, node:path, yaml. Imported by: src/packs/loader.ts
+ * (LP.1 fold) + src/wedge/promote.ts (LP.3 lesson-append) + tests.
+ */
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { PersonalRevision } from './schemas/manifest.js';
+const VERSION_FILE = 'version.json';
+const REVISION_DIR = 'personal_revision';
+const LESSON_RE = /^lesson_(\d+)(\.conflict)?\.yaml$/;
+/**
+ * Read version.json from a pack's personal_revision directory. Returns null
+ * if directory or file is absent (e.g. fresh install, no lessons yet, OR
+ * built-in pack that has no personal_revision dir). Throws on malformed
+ * JSON or schema-invalid content (loud failure — the file is
+ * engine-written, never user-edited).
+ */
+export async function readVersionJson(packStateDir) {
+    const path = join(packStateDir, REVISION_DIR, VERSION_FILE);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    return PersonalRevision.parse(parsed);
+}
+/**
+ * Write version.json atomically (temp + rename). Creates the
+ * personal_revision/ directory if absent. Uses `<pid>.<rand>` suffix so
+ * concurrent tests (which run in the same process under vitest pool) don't
+ * collide on temp names.
+ */
+export async function writeVersionJson(packStateDir, state) {
+    const dir = join(packStateDir, REVISION_DIR);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, VERSION_FILE);
+    const tmp = `${path}.tmp.${String(process.pid)}.${randSuffix()}`;
+    await writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+    await rename(tmp, path);
+}
+/**
+ * Enumerate all lesson_*.yaml + lesson_*.conflict.yaml files in monotonic
+ * order. Returns empty array if directory is absent. Skips malformed-name
+ * files (anything not matching `^lesson_\d+(\.conflict)?\.yaml$`).
+ */
+export async function readLessonFiles(packStateDir) {
+    const dir = join(packStateDir, REVISION_DIR);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const matched = [];
+    for (const entry of entries) {
+        const m = LESSON_RE.exec(entry);
+        if (m === null)
+            continue;
+        const id = Number.parseInt(m[1], 10);
+        const hasConflict = m[2] === '.conflict';
+        const path = join(dir, entry);
+        const raw = await readFile(path, 'utf8');
+        const body = parseYaml(raw);
+        matched.push({ id, path, body, hasConflict });
+    }
+    matched.sort((a, b) => a.id - b.id);
+    return matched;
+}
+/**
+ * Append a new lesson_<n+1>.yaml atomically. Reads version.json, computes
+ * next id, writes the lesson file (temp + rename), bumps
+ * personal_revision_id in version.json. Returns the new id.
+ *
+ * NOT concurrency-safe across processes — caller must serialize.
+ */
+export async function appendLessonFile(packStateDir, lessonBody) {
+    const current = await readVersionJson(packStateDir);
+    if (current === null) {
+        throw new Error(`appendLessonFile: version.json missing at ${packStateDir} — install pack first`);
+    }
+    const nextId = current.personal_revision_id + 1;
+    const dir = join(packStateDir, REVISION_DIR);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `lesson_${String(nextId)}.yaml`);
+    const tmp = `${path}.tmp.${String(process.pid)}.${randSuffix()}`;
+    await writeFile(tmp, stringifyYaml(lessonBody), 'utf8');
+    await rename(tmp, path);
+    await writeVersionJson(packStateDir, {
+        ...current,
+        personal_revision_id: nextId,
+    });
+    return nextId;
+}
+/**
+ * Initialize a fresh personal_revision/ directory for a newly installed pack.
+ * Writes version.json with personal_revision_id=0 + supplied base_version.
+ * Idempotent: re-running for an already-initialized pack returns existing
+ * state without overwriting.
+ */
+export async function initPersonalRevision(packStateDir, baseVersion) {
+    const existing = await readVersionJson(packStateDir);
+    if (existing !== null)
+        return existing;
+    const state = {
+        base_version: baseVersion,
+        personal_revision_id: 0,
+        last_merged_vanilla: null,
+    };
+    await writeVersionJson(packStateDir, state);
+    return state;
+}
+/** Random hex suffix for temp file naming (collision avoidance in tests). */
+function randSuffix() {
+    // 8 hex chars from process.hrtime.bigint() last 32 bits — deterministic in
+    // tests via fake-timers but unique across rapid sequential writes.
+    const t = process.hrtime.bigint();
+    return (t & 0xffffffffn).toString(16).padStart(8, '0');
+}
+export async function persistPromotedLesson(packStateDir, lesson) {
+    await initPersonalRevision(packStateDir, lesson.packBaseVersion ?? '0.0.0');
+    return appendLessonFile(packStateDir, {
+        promoted_at: new Date().toISOString(),
+        engine_lesson_id: lesson.engine_lesson_id,
+        lesson_body: lesson.lesson_body,
+        cited_memory_ids: lesson.cited_memory_ids ?? [],
+        ...(lesson.skill !== undefined ? { skill: lesson.skill } : {}),
+        retired: false,
+    });
+}
+//# sourceMappingURL=personal_revision.js.map

package/dist/packs/personal_revision.js.map

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

package/dist/packs/schemas/channels.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Zod schema for `channels.yaml` — the pack's suggested channel URI defaults.
+ *
+ * Authoritative source: `docs/opensquid-real-design.md` §"Pluggable channels"
+ * + §"Two-layer pattern" + memory `project_opensquid_notification_routing`.
+ *
+ * Two-layer model: packs declare abstract channel names (`alerts`, `audit_log`,
+ * `opensquid_topic`); user config at `~/.opensquid/channels.yaml` maps
+ * abstract names → concrete URIs (`telegram://12345/666`, `slack://...`, etc.).
+ * The pack-side `channels.yaml` is OPTIONAL suggested defaults a pack ships
+ * for documentation / setup-UI prefill — runtime resolution always reads the
+ * user's mapping last (resolution algorithm steps 3-4).
+ *
+ * Schema shape: `Record<string, string>` — abstract name → URI string. We do
+ * NOT validate URI schemes at this layer because new adapters land over time
+ * (Phase 1 ships chat / telegram / discord / slack; more later). The channel
+ * adapter registry (Task 2.6 / runtime adapter layer) is the right place to
+ * reject unknown schemes; at load time we accept any string so a pack can
+ * declare a future-adapter URI without breaking on schema validation.
+ *
+ * `.default({})` makes an empty `channels.yaml` (or a missing file) parse to
+ * `{}` — out-of-the-box constraint. The minimum-viable pack ships no channels.
+ *
+ * Imports from: zod only (self-contained per audit constraint).
+ * Imported by: src/packs/schemas/index.ts.
+ */
+import { z } from 'zod';
+export declare const ChannelsConfig: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+export type ChannelsConfig = z.infer<typeof ChannelsConfig>;
+//# sourceMappingURL=channels.d.ts.map