opensquid 0.5.395

package/dist/runtime/event.js

@@ -0,0 +1,303 @@
+/**
+ * Event union + Trigger schema — split out of `types.ts` per the AUTO.1
+ * file-size constraint ("types.ts stays under 400 LOC; split into
+ * `types/event.ts` if exceeded").
+ *
+ * `types.ts` re-exports every symbol declared here so existing
+ * `import { Event } from './types.js'` callsites continue to work — this
+ * file is internal layout, not a new public surface.
+ *
+ * Authoritative source: `docs/opensquid-real-design.md` §"The architecture
+ * in six concepts" (concept 1: Event) + `docs/tasks/automation.md` AUTO.1
+ * "Key code shapes" (the four new event variants + `triggers:` block).
+ *
+ * What lives here:
+ *   - The Event variants (tool_call, post_tool_call, prompt_submit,
+ *     session_end, stop, session_start, schedule, webhook, inbound_channel,
+ *     file_changed) — post_tool_call added by POSTPUSH.1, session_start by
+ *     HH6.1
+ *   - The `Event` discriminated union
+ *   - `EventKind` enum (the matching discriminator literals)
+ *   - `Trigger` discriminated union + `DEFAULT_TRIGGERS` + `defaultTriggers()`
+ *
+ * What does NOT live here:
+ *   - Verdict / Rule / Skill / Pack schemas → `types.ts` (the cross-process
+ *     contract for the rest of the runtime).
+ *   - DriftPolicy / RuntimeAction / PauseState → `types.ts` (drift-response
+ *     and pause-state machinery).
+ *
+ * Naming: `event.ts` (sibling) rather than `types/event.ts` (subdir) to
+ * avoid the NodeNext name collision between a sibling file `types.ts` and a
+ * sibling directory `types/`. Both `.ts` and `.d.ts` resolvers can find
+ * `./event.js` cleanly while preserving every existing `./types.js` import.
+ *
+ * Imports from: zod.
+ * Imported by: src/runtime/types.ts (re-export barrel).
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Event — discriminated union on `kind`.
+//
+// Use `z.discriminatedUnion` (not `z.union`) so TS narrows on `event.kind`
+// inside a `switch` and ZodError points at the right variant on rejection.
+// ---------------------------------------------------------------------------
+export const ToolCallEvent = z.object({
+    kind: z.literal('tool_call'),
+    tool: z.string(),
+    args: z.record(z.unknown()),
+    cwd: z.string().optional(),
+});
+// T-POSTPUSH POSTPUSH.1 (2026-05-29) — PostToolUse event fires AFTER a tool
+// call completes. exit_code lets gate skills react to success/failure
+// (canonical case = verify-CI-after-push fires only on exit_code === 0).
+// stdout/stderr/duration_ms are payload extras Claude Code includes; skills
+// don't currently consume them but the schema accepts them for forward
+// compat. Active-task mirror is NOT re-fired from this event (PreToolUse
+// already handles that surface — double-firing would duplicate writes).
+export const PostToolCallEvent = z.object({
+    kind: z.literal('post_tool_call'),
+    tool: z.string(),
+    args: z.record(z.unknown()),
+    exit_code: z.number().int(),
+    stdout: z.string().optional(),
+    stderr: z.string().optional(),
+    cwd: z.string().optional(),
+    duration_ms: z.number().optional(),
+});
+// T-RESPONSE-JUDGING-UPS RJ.1 (2026-06-01) — `priorAssistantText` carries the
+// SETTLED prior assistant turn so response-judging gates (honesty-ledger,
+// phase-logging, d9-guard) can run at UserPromptSubmit instead of Stop. CC
+// provides `transcript_path` on UserPromptSubmit and the prior turn is already
+// flushed at fire-time (confirmed against CC hook docs), so the UPS hook bin
+// fills this via `readLastAssistantText` with NO off-by-one (unlike Stop, where
+// the triggering response isn't flushed yet). Optional: absent on the synthetic
+// events tests construct + when no transcript is available (fail-open '').
+export const PromptSubmitEvent = z.object({
+    kind: z.literal('prompt_submit'),
+    prompt: z.string(),
+    priorAssistantText: z.string().optional(),
+    // T-RJ-FOLLOWUPS FU.2 — the last N text-bearing turns (role-labeled), filled
+    // by the UPS hook from the transcript. Consumed by the wedge-gate
+    // `lesson-capture` skill via the `recent_turns` primitive; multi-turn context
+    // (vs `priorAssistantText`'s single prior turn).
+    recentTurns: z.string().optional(),
+    // T-ATM ATM.2 — the OPEN tasks (latest status pending|in_progress) derived
+    // from the transcript by the UPS hook (THIS CC version keeps the task list in
+    // the transcript, not ~/.claude/tasks/). Consumed by Gate B
+    // (`task_list_generated`) to flag tasks lacking `metadata.taskId` provenance.
+    // Absent on synthetic test events + older CC (the function falls back to the
+    // harness-store read).
+    openTasks: z
+        .array(z.object({ id: z.string(), status: z.string(), taskId: z.string().optional() }))
+        .optional(),
+});
+export const SessionEndEvent = z.object({
+    kind: z.literal('session_end'),
+    sessionId: z.string(),
+});
+export const StopEvent = z.object({
+    kind: z.literal('stop'),
+    assistantText: z.string(),
+});
+// T-HANDOFF-HARDENING HH6.1 (2026-05-31) — SessionStart fires ONCE when a
+// session begins (Claude Code's `SessionStart` hook, the missing enforcement
+// point this track adds). `source` is the CC-supplied trigger: `startup`
+// (new), `resume` (--resume/--continue), `clear` (/clear), `compact`
+// (auto/manual compaction). The session-start bin acts only on startup|resume
+// (skips clear|compact — those fire mid-session and would re-inject noise).
+// `sessionId`/`cwd` are optional carriers (CC supplies them; the bin defaults
+// cwd to process.cwd()). First consumer = the connection-check pack rule
+// (HH6.2), which subscribes via `triggers: [{kind: session_start}]`.
+export const SessionStartEvent = z.object({
+    kind: z.literal('session_start'),
+    source: z.enum(['startup', 'resume', 'clear', 'compact']),
+    sessionId: z.string().optional(),
+    cwd: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// AUTO.1 — non-tool-call event variants.
+//
+// The four variants below back the trigger sources that don't ride on a host
+// tool-call hook: scheduler ticks (SCHED.1), webhook intakes (SCHED.2),
+// inbound channel messages (AUTO.6), and file-change watchers (AUTO.5).
+//
+// Discriminator literals stay strict `z.literal(<value>)` (per task spec risk
+// callout — `z.string()` would silently break narrowing inside `switch
+// (event.kind)`). Carrier fields stay deliberately loose at this layer so
+// downstream trigger sources can extend them without re-migrating every
+// pinned cron job or webhook spec:
+//
+//   - `ScheduleEvent.triggerPayload` is `z.record(z.unknown())` — schedule
+//     authors put what they want; tightening means migrating every cron job.
+//   - `WebhookEvent.body` is `z.unknown()` — bodies are JSON, plaintext,
+//     form-encoded, etc. The webhook intake (AUTO.6 / SCHED.2) is the right
+//     layer to refine per-route.
+//   - `WebhookEvent.headers` stays `z.record(z.string())` — headers are
+//     always string-valued by HTTP spec, but key set is open.
+//
+// `receivedAt` / `fireTime` / `changedAt` are ISO-8601 strings authored by
+// the trigger source. We don't `z.string().datetime()` them here because
+// the trigger source (not the runtime) owns the time-of-truth — refining
+// the format means surfacing bad-clock errors at the trigger boundary,
+// which is a follow-up task (SCHED.1 + AUTO.5 land that boundary).
+// ---------------------------------------------------------------------------
+export const ScheduleEvent = z.object({
+    kind: z.literal('schedule'),
+    scheduleId: z.string(),
+    fireTime: z.string(), // ISO-8601, authored by the scheduler tick (SCHED.1)
+    triggerPayload: z.record(z.unknown()).default({}),
+});
+export const WebhookEvent = z.object({
+    kind: z.literal('webhook'),
+    subscriptionId: z.string(),
+    method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
+    headers: z.record(z.string()),
+    body: z.unknown(),
+    receivedAt: z.string(),
+});
+export const InboundChannelEvent = z.object({
+    kind: z.literal('inbound_channel'),
+    channelUri: z.string(), // e.g. "telegram://-1001234567890/42"
+    sender: z.string(),
+    text: z.string(),
+    threadKey: z.string().optional(),
+    receivedAt: z.string(),
+});
+export const FileChangedEvent = z.object({
+    kind: z.literal('file_changed'),
+    path: z.string(),
+    changeKind: z.enum(['add', 'change', 'unlink']),
+    changedAt: z.string(),
+});
+// ---------------------------------------------------------------------------
+// Event — discriminated union on `kind`.
+//
+// The order below puts the host-hook events first (tool_call, post_tool_call,
+// prompt_submit, session_end, stop, session_start) and the trigger-source
+// events after, matching the load order in `EventKind` (see below) and the
+// matcher allow-list in `load_matchers.ts`. Pack authors can declare any
+// kind as a skill `triggers:` entry; the dispatcher filters skills
+// per event kind before evaluating rules.
+// ---------------------------------------------------------------------------
+export const Event = z.discriminatedUnion('kind', [
+    ToolCallEvent,
+    PostToolCallEvent, // T-POSTPUSH POSTPUSH.1
+    PromptSubmitEvent,
+    SessionEndEvent,
+    StopEvent,
+    SessionStartEvent, // T-HANDOFF-HARDENING HH6.1
+    ScheduleEvent,
+    WebhookEvent,
+    InboundChannelEvent,
+    FileChangedEvent,
+]);
+// ---------------------------------------------------------------------------
+// EventKind — the discriminator literals as a Zod enum + TS type.
+//
+// Lives next to `Event` so consumers that need the bare set of kinds
+// (skill `triggers:`, load matchers' `event_type` filter, scheduler audit
+// logs) import a single source of truth instead of re-typing the literals.
+// ---------------------------------------------------------------------------
+export const EventKind = z.enum([
+    'tool_call',
+    'post_tool_call', // T-POSTPUSH POSTPUSH.1
+    'prompt_submit',
+    'session_end',
+    'stop',
+    'session_start', // T-HANDOFF-HARDENING HH6.1
+    'schedule',
+    'webhook',
+    'inbound_channel',
+    'file_changed',
+]);
+// ---------------------------------------------------------------------------
+// Trigger — discriminated union declaring which `Event` kinds fire a skill.
+//
+// AUTO.1: skills opt in to non-tool-call events via a `triggers:` block on
+// the skill manifest. The runtime view declared here is the post-load
+// (post-YAML-validation) shape; the YAML-side schema in
+// `src/packs/schemas/skill.ts` re-uses this type so pack authors and the
+// dispatcher see one canonical Trigger shape.
+//
+// Per-kind filter args at this layer:
+//
+//   tool_call / prompt_submit / session_end / stop
+//     no filter args — the host hook delivers the event verbatim and
+//     existing in-rule primitives (tool_name, match_command) do per-event
+//     filtering.
+//
+//   schedule
+//     `cron`      — POSIX-style schedule expression, read by SCHED.1
+//     `cost_tier` — AUTO.7 cross-subscription routing hint
+//
+//   webhook
+//     `path`      — URL path filter, read by SCHED.2 webhook intake
+//     `cost_tier` — AUTO.7 cross-subscription routing hint
+//
+//   inbound_channel
+//     `channel`   — abstract channel name (mapped to URI via channels.yaml),
+//                   read by AUTO.6 inbound router
+//     `cost_tier` — AUTO.7 cross-subscription routing hint
+//
+//   file_changed
+//     `paths`     — glob list, read by AUTO.5 chokidar watcher
+//     `ignored`   — glob list, read by AUTO.5 chokidar watcher
+//     `cost_tier` — AUTO.7 cross-subscription routing hint
+//
+// Discriminator literals stay strict `z.literal(<value>)` (same risk
+// callout as Event) so the dispatcher's `event.kind ∈ triggers.kind` filter
+// narrows correctly inside a `switch`.
+// ---------------------------------------------------------------------------
+const CostTier = z.enum(['cheap', 'balanced', 'premium']);
+export const Trigger = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('tool_call') }),
+    z.object({ kind: z.literal('post_tool_call') }), // T-POSTPUSH POSTPUSH.1
+    z.object({ kind: z.literal('prompt_submit') }),
+    z.object({ kind: z.literal('session_end') }),
+    z.object({ kind: z.literal('stop') }),
+    z.object({ kind: z.literal('session_start') }), // T-HANDOFF-HARDENING HH6.1
+    z.object({
+        kind: z.literal('schedule'),
+        cron: z.string().optional(),
+        cost_tier: CostTier.optional(),
+    }),
+    z.object({
+        kind: z.literal('webhook'),
+        path: z.string().optional(),
+        cost_tier: CostTier.optional(),
+    }),
+    z.object({
+        kind: z.literal('inbound_channel'),
+        channel: z.string().optional(),
+        // LL.3 (2026-05-30) — sender_pattern is OPTIONAL so existing skill
+        // manifests parse unchanged. Compiled as JS RegExp at dispatch
+        // time; malformed pattern → silent skip (filter returns false).
+        // First-party pack manifests only — NOT a user-supplied input,
+        // so JS RegExp is acceptable here (not RE2 — see pack-runtime.md
+        // §7.5 anti-patterns).
+        sender_pattern: z.string().optional(),
+        cost_tier: CostTier.optional(),
+    }),
+    z.object({
+        kind: z.literal('file_changed'),
+        paths: z.array(z.string()).optional(),
+        ignored: z.array(z.string()).optional(),
+        cost_tier: CostTier.optional(),
+    }),
+]);
+/**
+ * Default trigger list applied when a skill omits the `triggers:` block.
+ * Pinned to a single `tool_call` entry for back-compat with every Phase
+ * 1–7 pack authored before AUTO.1 widened the Event union.
+ */
+export const DEFAULT_TRIGGERS = Object.freeze([
+    Object.freeze({ kind: 'tool_call' }),
+]);
+/**
+ * Build a fresh, mutable copy of the default trigger list — used by Zod
+ * `.default(fn)` so each parsed skill gets its own array instance.
+ */
+export function defaultTriggers() {
+    return [{ kind: 'tool_call' }];
+}
+//# sourceMappingURL=event.js.map

package/dist/runtime/event.js.map

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

package/dist/runtime/failure_handling.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime failure handling — three-stage pattern (Task 1.18).
+ *
+ * Per `docs/opensquid-real-design.md` §"Runtime failure handling":
+ *
+ *   Stage 1: validate-at-load — fires from the pack loader at session
+ *            start (lives in Phase 2; surfaces config errors to the user
+ *            BEFORE any rule evaluation runs).
+ *   Stage 2: runtime-notify   — when a `notify_and_pause` policy fires
+ *            mid-session, multicast the verdict to the user's channels.
+ *   Stage 3: pause-for-user   — persist a session-level pause marker so
+ *            that subsequent hook invocations short-circuit until the
+ *            user resumes.
+ *
+ * This module owns Stages 2 + 3. Stage 1 is the pack loader's concern.
+ *
+ * ORDERING CONTRACT (C10 — no silent fail-open):
+ *
+ *   Write the pause-state file FIRST, then multicast. The pause file is
+ *   the single source of truth for "is this session halted?" — if the
+ *   notification multicast throws, the runtime is still correctly paused
+ *   and the user will see the halt the next time they look. Inverting
+ *   this order would risk the opposite: a notification fires, the user
+ *   thinks the session is paused, but the next event sails through
+ *   because the pause file never landed.
+ *
+ *   The multicast call is therefore wrapped in `try/catch` and logged to
+ *   `stderr` on failure — `notifyAndPause` must never throw out of the
+ *   notification path. Pause-state write errors DO propagate, because a
+ *   failed pause is a real fault the caller must handle (per C10, the
+ *   alternative is silently fail-open).
+ *
+ * Imported by: drift_response dispatcher (Task 1.6 wiring) and the hook
+ * layer (Task 1.7) for the `isPaused` short-circuit check.
+ */
+import type { NotificationRouter } from '../channels/router.js';
+import type { RoutingConfig } from '../channels/types.js';
+import type { PauseState } from './types.js';
+/**
+ * Pause the session and notify the user. Stage 2 + Stage 3 in one call.
+ *
+ * Writes `sessionStateFile(sessionId, 'pause')` atomically (tmp + rename
+ * within the same directory, so the rename is a single inode swap on
+ * POSIX), then attempts to multicast an `error`-severity message. If
+ * multicast throws, the error is logged to `stderr` and swallowed — the
+ * session is already paused, which is the load-bearing side effect.
+ */
+export declare function notifyAndPause(reason: string, sessionId: string, router: NotificationRouter, routing: RoutingConfig, meta?: {
+    ruleId?: string;
+    packId?: string;
+}): Promise<void>;
+/**
+ * Cheap existence check used by hook dispatch to short-circuit paused
+ * sessions. Returns `true` iff `sessionStateFile(sessionId, 'pause')`
+ * exists and is readable. Never throws — any I/O error is treated as
+ * "not paused" so transient FS issues don't block recovery flows.
+ */
+export declare function isPaused(sessionId: string): Promise<boolean>;
+/**
+ * Read the full `PauseState` for a paused session, or `null` if the
+ * session is not paused / the file is unreadable / the JSON is invalid.
+ *
+ * Soft failure (returns `null` on parse error) is intentional: a corrupt
+ * pause file is recoverable by the user (delete the file) and we never
+ * want this read path to crash the hook layer.
+ */
+export declare function readPauseState(sessionId: string): Promise<PauseState | null>;
+//# sourceMappingURL=failure_handling.d.ts.map

package/dist/runtime/failure_handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure_handling.d.ts","sourceRoot":"","sources":["../../src/runtime/failure_handling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlE;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAOlF"}

package/dist/runtime/failure_handling.js

@@ -0,0 +1,103 @@
+/**
+ * Runtime failure handling — three-stage pattern (Task 1.18).
+ *
+ * Per `docs/opensquid-real-design.md` §"Runtime failure handling":
+ *
+ *   Stage 1: validate-at-load — fires from the pack loader at session
+ *            start (lives in Phase 2; surfaces config errors to the user
+ *            BEFORE any rule evaluation runs).
+ *   Stage 2: runtime-notify   — when a `notify_and_pause` policy fires
+ *            mid-session, multicast the verdict to the user's channels.
+ *   Stage 3: pause-for-user   — persist a session-level pause marker so
+ *            that subsequent hook invocations short-circuit until the
+ *            user resumes.
+ *
+ * This module owns Stages 2 + 3. Stage 1 is the pack loader's concern.
+ *
+ * ORDERING CONTRACT (C10 — no silent fail-open):
+ *
+ *   Write the pause-state file FIRST, then multicast. The pause file is
+ *   the single source of truth for "is this session halted?" — if the
+ *   notification multicast throws, the runtime is still correctly paused
+ *   and the user will see the halt the next time they look. Inverting
+ *   this order would risk the opposite: a notification fires, the user
+ *   thinks the session is paused, but the next event sails through
+ *   because the pause file never landed.
+ *
+ *   The multicast call is therefore wrapped in `try/catch` and logged to
+ *   `stderr` on failure — `notifyAndPause` must never throw out of the
+ *   notification path. Pause-state write errors DO propagate, because a
+ *   failed pause is a real fault the caller must handle (per C10, the
+ *   alternative is silently fail-open).
+ *
+ * Imported by: drift_response dispatcher (Task 1.6 wiring) and the hook
+ * layer (Task 1.7) for the `isPaused` short-circuit check.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { sessionStateFile } from './paths.js';
+/**
+ * Pause the session and notify the user. Stage 2 + Stage 3 in one call.
+ *
+ * Writes `sessionStateFile(sessionId, 'pause')` atomically (tmp + rename
+ * within the same directory, so the rename is a single inode swap on
+ * POSIX), then attempts to multicast an `error`-severity message. If
+ * multicast throws, the error is logged to `stderr` and swallowed — the
+ * session is already paused, which is the load-bearing side effect.
+ */
+export async function notifyAndPause(reason, sessionId, router, routing, meta = {}) {
+    const state = {
+        reason,
+        triggeredAt: new Date().toISOString(),
+        ...(meta.ruleId !== undefined ? { ruleId: meta.ruleId } : {}),
+        ...(meta.packId !== undefined ? { packId: meta.packId } : {}),
+    };
+    const path = sessionStateFile(sessionId, 'pause');
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    await writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+    await rename(tmp, path);
+    // Multicast LAST. Failures here are non-fatal — the pause file is the
+    // source of truth and is already on disk. Logging to stderr surfaces
+    // the failure without blowing up the runtime.
+    try {
+        await router.multicast('error', null, { text: `opensquid paused: ${reason}`, severity: 'error' }, routing);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`opensquid: pause notification failed (state still written): ${message}\n`);
+    }
+}
+/**
+ * Cheap existence check used by hook dispatch to short-circuit paused
+ * sessions. Returns `true` iff `sessionStateFile(sessionId, 'pause')`
+ * exists and is readable. Never throws — any I/O error is treated as
+ * "not paused" so transient FS issues don't block recovery flows.
+ */
+export async function isPaused(sessionId) {
+    try {
+        await readFile(sessionStateFile(sessionId, 'pause'), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the full `PauseState` for a paused session, or `null` if the
+ * session is not paused / the file is unreadable / the JSON is invalid.
+ *
+ * Soft failure (returns `null` on parse error) is intentional: a corrupt
+ * pause file is recoverable by the user (delete the file) and we never
+ * want this read path to crash the hook layer.
+ */
+export async function readPauseState(sessionId) {
+    try {
+        const raw = await readFile(sessionStateFile(sessionId, 'pause'), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=failure_handling.js.map

package/dist/runtime/failure_handling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure_handling.js","sourceRoot":"","sources":["../../src/runtime/failure_handling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,SAAiB,EACjB,MAA0B,EAC1B,OAAsB,EACtB,OAA6C,EAAE;IAE/C,MAAM,KAAK,GAAe;QACxB,MAAM;QACN,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9D,CAAC;IACF,MAAM,IAAI,GAAG,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,GAAG,IAAI,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC7D,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAExB,sEAAsE;IACtE,qEAAqE;IACrE,8CAA8C;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CACpB,OAAO,EACP,IAAI,EACJ,EAAE,IAAI,EAAE,qBAAqB,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAC1D,OAAO,CACR,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+DAA+D,OAAO,IAAI,CAC3E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,SAAiB;IAC9C,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAiB;IACpD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/runtime/fsm.d.ts

@@ -0,0 +1,120 @@
+/**
+ * T-PACK-FSM-STANDARDIZATION slice A — the generic total-transition FSM engine.
+ *
+ * The capstone thesis is that a pack's lifecycle is an EXPLICIT TOTAL-TRANSITION
+ * FSM. Today the only "FSM" (`chain_state.ts`) is a single global stage tracker
+ * whose `transitionChainStage` accepts ANY target with no legality matrix — it
+ * is NOT total and cannot loop back. This module is the generic engine that
+ * replaces that: a pure, pack-declarable FSM with validated transitions.
+ *
+ * Two pure pieces:
+ *   - `validateFsm(fsm)` — load-time checks: `initial` and every transition's
+ *     `from`/`to` reference a declared state; no transition targets an
+ *     undefined state. Returns the list of errors (empty = valid). This is what
+ *     makes the machine TOTAL-by-construction: every reachable transition lands
+ *     on a real state, and the runner defines an outcome for EVERY (state,event)
+ *     pair (a matching transition, else an explicit stay).
+ *   - `step(fsm, current, event, evalWhen?)` — the transition function. Total:
+ *     returns a defined next-state for every input. No I/O; the optional
+ *     `when` guard is evaluated through an injected `evalWhen` (the caller wires
+ *     the expression engine) so this module stays pure + testable.
+ *
+ * Unlike `chain_state`, transitions here are DECLARED data, support `*` (any
+ * source) and a `when` guard, and can LOOP BACK (e.g. `researching --guess-->
+ * researching`) — the edge the scope guess-prevention gate (slice C) needs.
+ *
+ * Imports: zod only. Imported by: slice A2 (runtime integration), slice C
+ * (scope FSM), tests.
+ */
+import { z } from 'zod';
+/** A wildcard `from` matching any current state. */
+export declare const ANY_STATE: "*";
+export declare const Transition: z.ZodObject<{
+    /** Source state name, or `*` to match any current state. */
+    from: z.ZodString;
+    /** Event name that fires this transition. */
+    on: z.ZodString;
+    /** Target state — MUST be a declared state (validateFsm enforces). */
+    to: z.ZodString;
+    /** Optional `if:`-expression guard; evaluated via the injected evalWhen. */
+    when: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    on: string;
+    when?: string | undefined;
+}, {
+    from: string;
+    to: string;
+    on: string;
+    when?: string | undefined;
+}>;
+export type Transition = z.infer<typeof Transition>;
+export declare const Fsm: z.ZodObject<{
+    initial: z.ZodString;
+    states: z.ZodArray<z.ZodString, "many">;
+    transitions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Source state name, or `*` to match any current state. */
+        from: z.ZodString;
+        /** Event name that fires this transition. */
+        on: z.ZodString;
+        /** Target state — MUST be a declared state (validateFsm enforces). */
+        to: z.ZodString;
+        /** Optional `if:`-expression guard; evaluated via the injected evalWhen. */
+        when: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        from: string;
+        to: string;
+        on: string;
+        when?: string | undefined;
+    }, {
+        from: string;
+        to: string;
+        on: string;
+        when?: string | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    initial: string;
+    states: string[];
+    transitions: {
+        from: string;
+        to: string;
+        on: string;
+        when?: string | undefined;
+    }[];
+}, {
+    initial: string;
+    states: string[];
+    transitions?: {
+        from: string;
+        to: string;
+        on: string;
+        when?: string | undefined;
+    }[] | undefined;
+}>;
+export type Fsm = z.infer<typeof Fsm>;
+/**
+ * Load-time validation. Returns a (possibly empty) list of human-readable
+ * errors. The machine is TOTAL by construction once these pass: the runner
+ * defines an outcome for every (state, event), and every declared transition
+ * lands on a real state.
+ */
+export declare function validateFsm(fsm: Fsm): string[];
+export interface StepResult {
+    /** The next state (== current when no transition matched — total/explicit stay). */
+    next: string;
+    /** True iff a transition actually moved to a different state. */
+    transitioned: boolean;
+    /** The id (index) of the transition taken, or null for the stay default. */
+    via: number | null;
+}
+/**
+ * The transition function — TOTAL: returns a defined next-state for every
+ * (current, event). Finds the FIRST transition whose `from` matches (exact or
+ * `*`), whose `on` equals `event`, and whose `when` guard (if any) holds.
+ * No match → stay in `current` (the explicit default — no implicit/undefined
+ * state). `evalWhen` evaluates a guard expression; omitted → guards are treated
+ * as satisfied (caller opted out of guard evaluation).
+ */
+export declare function step(fsm: Fsm, current: string, event: string, evalWhen?: (expr: string) => boolean): StepResult;
+//# sourceMappingURL=fsm.d.ts.map

package/dist/runtime/fsm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm.d.ts","sourceRoot":"","sources":["../../src/runtime/fsm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oDAAoD;AACpD,eAAO,MAAM,SAAS,EAAG,GAAY,CAAC;AAEtC,eAAO,MAAM,UAAU;IAEnB,4DAA4D;;IAE5D,6CAA6C;;IAE7C,sEAAsE;;IAEtE,4EAA4E;;;;;;;;;;;;EAGrE,CAAC;AACZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,GAAG;;;;QAZZ,4DAA4D;;QAE5D,6CAA6C;;QAE7C,sEAAsE;;QAEtE,4EAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYrE,CAAC;AACZ,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,CAgB9C;AAED,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,YAAY,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACnC,UAAU,CAUZ"}