trellis-hgl-core 0.6.0-beta.18

package/dist/channel/internal/store/events.d.ts

@@ -0,0 +1,203 @@
+import type { ChannelType, ContextEntry, ContextMutationAction, ContextTarget, EventOrigin, InboxPolicy, ThreadAction } from "./schema.js";
+export type ChannelEventKind = "create" | "join" | "leave" | "message" | "thread" | "context" | "channel" | "spawned" | "killed" | "respawned" | "progress" | "done" | "error" | "waiting" | "awake" | "undeliverable" | "interrupt_requested" | "turn_started" | "turn_finished" | "interrupted" | "supervisor_warning";
+export declare const CHANNEL_EVENT_KINDS: ReadonlySet<ChannelEventKind>;
+export declare function parseChannelKind(v: string | undefined): ChannelEventKind | undefined;
+/**
+ * Parse a CSV of event kinds into a typed list. Each member is validated
+ * through {@link parseChannelKind} so the single-value error message and
+ * whitelist remain the SOT. Returns `undefined` when input is undefined
+ * or contains no non-empty members.
+ */
+export declare function parseChannelKinds(v: string | undefined): ChannelEventKind[] | undefined;
+export interface BaseChannelEvent<K extends ChannelEventKind = ChannelEventKind> {
+    seq: number;
+    ts: string;
+    kind: K;
+    by: string;
+    to?: string | string[];
+    origin?: EventOrigin;
+    meta?: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+export interface CreateChannelEvent extends BaseChannelEvent<"create"> {
+    cwd?: string;
+    task?: string;
+    /**
+     * Stored channel type. May carry the legacy `"thread"` / `"threads"`
+     * values on old event logs — `reduceChannelMetadata` does NOT upgrade
+     * those to `"forum"`; they project to `"chat"`.
+     */
+    type?: ChannelType | "thread" | "threads";
+    description?: string;
+    /** Canonical context entries. */
+    context?: ContextEntry[];
+    /**
+     * Legacy alias kept for compatibility with channels created before
+     * `context` was the canonical field.
+     *
+     * @deprecated
+     */
+    linkedContext?: ContextEntry[];
+    labels?: string[];
+    ephemeral?: boolean;
+}
+export interface MessageChannelEvent extends BaseChannelEvent<"message"> {
+    text?: string;
+    tag?: string;
+}
+export interface ThreadChannelEvent extends BaseChannelEvent<"thread"> {
+    action?: ThreadAction;
+    thread: string;
+    title?: string;
+    text?: string;
+    description?: string;
+    status?: string;
+    labels?: string[];
+    assignees?: string[];
+    summary?: string;
+    context?: ContextEntry[];
+    /** Legacy alias on old event logs. */
+    linkedContext?: ContextEntry[];
+    /** Rename target (action === "rename"). */
+    newThread?: string;
+}
+export interface ContextChannelEvent extends BaseChannelEvent<"context"> {
+    target: ContextTarget;
+    action: ContextMutationAction;
+    context: ContextEntry[];
+    thread?: string;
+}
+export interface ChannelMetadataEvent extends BaseChannelEvent<"channel"> {
+    action: "title";
+    title?: string | null;
+}
+export interface SpawnedChannelEvent extends BaseChannelEvent<"spawned"> {
+    as?: string;
+    provider?: string;
+    pid?: number;
+    agent?: string;
+    files?: string[];
+    manifests?: string[];
+    /**
+     * Inbox delivery policy selected at spawn. Durable worker state — the
+     * worker registry projects `spawned` events without this field as
+     * `explicitOnly`.
+     */
+    inboxPolicy?: InboxPolicy;
+}
+export interface KilledChannelEvent extends BaseChannelEvent<"killed"> {
+    reason?: string;
+    signal?: string;
+    /** Worker the kill targeted (when written by the CLI kill path). */
+    worker?: string;
+    timeout_ms?: number;
+}
+export interface DoneChannelEvent extends BaseChannelEvent<"done"> {
+    duration_ms?: number;
+    exit_code?: number;
+    synthesized?: boolean;
+}
+export interface ErrorChannelEvent extends BaseChannelEvent<"error"> {
+    message?: string;
+    provider?: string;
+    synthesized?: boolean;
+    exit_code?: number;
+    exit_signal?: string;
+}
+export interface ProgressChannelEvent extends BaseChannelEvent<"progress"> {
+    detail?: Record<string, unknown>;
+}
+/** Why a worker interrupt was requested. */
+export type InterruptReason = "user" | "system" | "timeout" | "superseded";
+/** How an interrupt was attempted by the worker runtime. */
+export type InterruptMethod = "provider" | "stdin" | "signal" | "none";
+/** Result of an interrupt attempt as reported by the worker runtime. */
+export type InterruptOutcome = "interrupted" | "queued" | "unsupported" | "no-active-turn" | "failed";
+/** Why a message could not be delivered to a targeted worker. */
+export type UndeliverableReason = "worker-terminal" | "worker-unknown";
+export interface UndeliverableChannelEvent extends BaseChannelEvent<"undeliverable"> {
+    targetWorker: string;
+    messageSeq: number;
+    reason: UndeliverableReason;
+}
+export interface InterruptRequestedChannelEvent extends BaseChannelEvent<"interrupt_requested"> {
+    worker: string;
+    turnId?: string;
+    reason?: InterruptReason;
+    message?: string;
+}
+export interface TurnStartedChannelEvent extends BaseChannelEvent<"turn_started"> {
+    worker: string;
+    /**
+     * Durable link to the channel `message` event seq that initiated this
+     * turn. The worker registry uses this as the "consumed" marker for
+     * pending-message projection.
+     */
+    inputSeq: number;
+    turnId?: string;
+}
+export interface TurnFinishedChannelEvent extends BaseChannelEvent<"turn_finished"> {
+    worker: string;
+    inputSeq?: number;
+    turnId?: string;
+    outcome?: "done" | "error" | "aborted";
+}
+export interface InterruptedChannelEvent extends BaseChannelEvent<"interrupted"> {
+    worker: string;
+    turnId?: string;
+    reason?: InterruptReason;
+    method: InterruptMethod;
+    outcome: InterruptOutcome;
+    message?: string;
+}
+/** Reason for a supervisor pre-terminal warning event. */
+export type SupervisorWarningReason = "approaching_timeout";
+/**
+ * Pre-timeout observability event. Emitted at most once per worker run.
+ * Not part of {@link MEANINGFUL_EVENT_KINDS} so plain `wait` does not
+ * wake on it; explicit `--kind supervisor_warning` does match.
+ */
+export interface SupervisorWarningChannelEvent extends BaseChannelEvent<"supervisor_warning"> {
+    worker: string;
+    reason: SupervisorWarningReason;
+    timeout_ms: number;
+    remaining_ms: number;
+}
+export type GenericChannelEvent = BaseChannelEvent<Exclude<ChannelEventKind, "create" | "message" | "thread" | "context" | "channel" | "spawned" | "killed" | "done" | "error" | "progress" | "undeliverable" | "interrupt_requested" | "turn_started" | "turn_finished" | "interrupted" | "supervisor_warning">>;
+export type ChannelEvent = CreateChannelEvent | MessageChannelEvent | ThreadChannelEvent | ContextChannelEvent | ChannelMetadataEvent | SpawnedChannelEvent | KilledChannelEvent | DoneChannelEvent | ErrorChannelEvent | ProgressChannelEvent | UndeliverableChannelEvent | InterruptRequestedChannelEvent | TurnStartedChannelEvent | TurnFinishedChannelEvent | InterruptedChannelEvent | SupervisorWarningChannelEvent | GenericChannelEvent;
+export declare function isCreateEvent(ev: ChannelEvent): ev is CreateChannelEvent;
+export declare function isThreadEvent(ev: ChannelEvent): ev is ThreadChannelEvent;
+export declare function isContextEvent(ev: ChannelEvent): ev is ContextChannelEvent;
+export declare function isChannelMetadataEvent(ev: ChannelEvent): ev is ChannelMetadataEvent;
+export declare function ensureChannelDir(name: string, project?: string): Promise<string>;
+/**
+ * Read the last committed seq for a channel. Uses the same reconcile
+ * path as `appendEvent` so callers that need a snapshot do not see a
+ * stale sidecar.
+ */
+export declare function readLastSeq(name: string, project?: string): Promise<number>;
+export interface AppendablePartial {
+    kind: ChannelEventKind;
+    by: string;
+    ts?: string;
+    [extra: string]: unknown;
+}
+/**
+ * Cursor pagination options for {@link readChannelEvents}. When no field
+ * is set the reader returns every event (compatibility default).
+ */
+export interface ReadChannelEventsPagination {
+    /** Return events with `seq > afterSeq`, ascending. */
+    afterSeq?: number;
+    /** Return events with `seq < beforeSeq`, ascending. */
+    beforeSeq?: number;
+    /**
+     * Cap the page size. With a cursor, caps the page. Without a cursor,
+     * returns the latest N events in ascending seq order.
+     */
+    limit?: number;
+}
+/** Default page size applied when a cursor is present but `limit` is not. */
+export declare const DEFAULT_CURSOR_PAGE_SIZE = 200;
+export declare function readChannelEvents(name: string, project?: string, pagination?: ReadChannelEventsPagination): Promise<ChannelEvent[]>;
+//# sourceMappingURL=events.d.ts.map

package/dist/channel/internal/store/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../src/channel/internal/store/events.ts"],"names":[],"mappings":"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"}

package/dist/channel/internal/store/events.js

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import { withLock } from "./lock.js";
+import { channelDir, eventsPath, lockPath, seqSidecarPath, } from "./paths.js";
+import { reconcileSeq, writeSidecar } from "./seq.js";
+import { parseEventOrigin } from "./schema.js";
+export const CHANNEL_EVENT_KINDS = new Set([
+    "create",
+    "join",
+    "leave",
+    "message",
+    "thread",
+    "context",
+    "channel",
+    "spawned",
+    "killed",
+    "respawned",
+    "progress",
+    "done",
+    "error",
+    "waiting",
+    "awake",
+    "undeliverable",
+    "interrupt_requested",
+    "turn_started",
+    "turn_finished",
+    "interrupted",
+    "supervisor_warning",
+]);
+export function parseChannelKind(v) {
+    if (v === undefined)
+        return undefined;
+    if (!CHANNEL_EVENT_KINDS.has(v)) {
+        throw new Error(`Invalid --kind '${v}'. Must be one of: ${[...CHANNEL_EVENT_KINDS].join(", ")}`);
+    }
+    return v;
+}
+/**
+ * Parse a CSV of event kinds into a typed list. Each member is validated
+ * through {@link parseChannelKind} so the single-value error message and
+ * whitelist remain the SOT. Returns `undefined` when input is undefined
+ * or contains no non-empty members.
+ */
+export function parseChannelKinds(v) {
+    if (v === undefined)
+        return undefined;
+    const parts = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (parts.length === 0)
+        return undefined;
+    const out = [];
+    const seen = new Set();
+    for (const part of parts) {
+        const parsed = parseChannelKind(part);
+        if (parsed === undefined)
+            continue;
+        if (seen.has(parsed))
+            continue;
+        seen.add(parsed);
+        out.push(parsed);
+    }
+    return out;
+}
+export function isCreateEvent(ev) {
+    return ev.kind === "create";
+}
+export function isThreadEvent(ev) {
+    return ev.kind === "thread" && typeof ev.thread === "string";
+}
+export function isContextEvent(ev) {
+    return ev.kind === "context";
+}
+export function isChannelMetadataEvent(ev) {
+    return ev.kind === "channel";
+}
+export async function ensureChannelDir(name, project) {
+    const dir = channelDir(name, project);
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/**
+ * Read the last committed seq for a channel. Uses the same reconcile
+ * path as `appendEvent` so callers that need a snapshot do not see a
+ * stale sidecar.
+ */
+export async function readLastSeq(name, project) {
+    const file = eventsPath(name, project);
+    if (!fs.existsSync(file))
+        return 0;
+    return reconcileSeq(file, seqSidecarPath(name, project));
+}
+/**
+ * Append a channel event atomically under the channel lock.
+ *
+ * Internally reconciles the `.seq` sidecar with the JSONL tail to avoid
+ * the legacy full-scan path. Sidecar repair happens automatically on
+ * corruption, missing file, or sidecar drift in either direction.
+ *
+ * @internal Trellis CLI-internal write primitive — downstream consumers
+ *   must go through the typed mutation APIs (`createChannel`,
+ *   `sendMessage`, etc.).
+ */
+export async function appendEvent(name, partial, project) {
+    validateEventBase(partial);
+    await ensureChannelDir(name, project);
+    const jsonl = eventsPath(name, project);
+    const sidecar = seqSidecarPath(name, project);
+    return withLock(lockPath(name, project), async () => {
+        const lastSeq = await reconcileSeq(jsonl, sidecar);
+        const event = {
+            ...partial,
+            seq: lastSeq + 1,
+            ts: partial.ts ?? new Date().toISOString(),
+        };
+        await fsp.appendFile(jsonl, JSON.stringify(event) + "\n", "utf-8");
+        await writeSidecar(sidecar, event.seq);
+        return event;
+    });
+}
+function validateEventBase(partial) {
+    const origin = partial.origin;
+    if (origin !== undefined) {
+        parseEventOrigin(typeof origin === "string" ? origin : String(origin));
+    }
+    const meta = partial.meta;
+    if (meta !== undefined &&
+        (meta === null || typeof meta !== "object" || Array.isArray(meta))) {
+        throw new Error("meta must be a plain JSON object");
+    }
+}
+/** Default page size applied when a cursor is present but `limit` is not. */
+export const DEFAULT_CURSOR_PAGE_SIZE = 200;
+function readAllEvents(file) {
+    if (!fs.existsSync(file))
+        return [];
+    const text = fs.readFileSync(file, "utf-8");
+    const events = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            continue;
+        }
+    }
+    return events;
+}
+export async function readChannelEvents(name, project, pagination) {
+    const file = eventsPath(name, project);
+    const all = readAllEvents(file);
+    if (!pagination ||
+        (pagination.afterSeq === undefined &&
+            pagination.beforeSeq === undefined &&
+            pagination.limit === undefined)) {
+        return all;
+    }
+    const { afterSeq, beforeSeq, limit } = pagination;
+    if (afterSeq !== undefined && beforeSeq !== undefined) {
+        throw new Error("readChannelEvents: pass only one of afterSeq / beforeSeq");
+    }
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) {
+        throw new Error("readChannelEvents: limit must be a non-negative integer");
+    }
+    // Events are appended in monotonic seq order; keep that as the contract.
+    if (afterSeq !== undefined) {
+        const page = all.filter((ev) => ev.seq > afterSeq);
+        const cap = limit ?? DEFAULT_CURSOR_PAGE_SIZE;
+        return page.slice(0, cap);
+    }
+    if (beforeSeq !== undefined) {
+        const page = all.filter((ev) => ev.seq < beforeSeq);
+        const cap = limit ?? DEFAULT_CURSOR_PAGE_SIZE;
+        // Newest page first internally; return ascending for stable consumers.
+        return page.slice(Math.max(0, page.length - cap));
+    }
+    // limit only: latest N events in ascending seq order.
+    return limit !== undefined
+        ? all.slice(Math.max(0, all.length - limit))
+        : all;
+}
+//# sourceMappingURL=events.js.map

package/dist/channel/internal/store/events.js.map

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

package/dist/channel/internal/store/filter.d.ts

@@ -0,0 +1,22 @@
+import { type ChannelEvent, type ChannelEventKind } from "./events.js";
+import type { ThreadAction } from "./schema.js";
+export declare const MEANINGFUL_EVENT_KINDS: ReadonlySet<ChannelEventKind>;
+export interface ChannelEventFilter {
+    from?: string[];
+    /**
+     * Restrict to one kind (legacy single value) or any of a list (OR
+     * semantics). An explicit kind constraint bypasses the default
+     * meaningful-kinds filter so non-meaningful kinds can still match
+     * when requested directly (e.g. `supervisor_warning`).
+     */
+    kind?: ChannelEventKind | readonly ChannelEventKind[];
+    tag?: string;
+    to?: string;
+    self?: string;
+    includeProgress?: boolean;
+    includeNonMeaningful?: boolean;
+    thread?: string;
+    action?: ThreadAction;
+}
+export declare function matchesEventFilter(ev: ChannelEvent, filter: ChannelEventFilter): boolean;
+//# sourceMappingURL=filter.d.ts.map

package/dist/channel/internal/store/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../../src/channel/internal/store/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,gBAAgB,CAazC,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,gBAAgB,EAAE,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAaD,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAoDT"}

package/dist/channel/internal/store/filter.js

@@ -0,0 +1,78 @@
+import { isThreadEvent, } from "./events.js";
+export const MEANINGFUL_EVENT_KINDS = new Set([
+    "create",
+    "join",
+    "leave",
+    "message",
+    "thread",
+    "context",
+    "channel",
+    "spawned",
+    "killed",
+    "respawned",
+    "done",
+    "error",
+]);
+function matchesKind(evKind, filterKind) {
+    if (filterKind === undefined)
+        return true;
+    if (typeof filterKind === "string")
+        return evKind === filterKind;
+    // Empty array = no kind constraint (treat as if filter.kind was undefined).
+    if (filterKind.length === 0)
+        return true;
+    return filterKind.includes(evKind);
+}
+export function matchesEventFilter(ev, filter) {
+    if (filter.self && ev.by === filter.self)
+        return false;
+    // An explicit kind filter is itself the caller's "I know what I want"
+    // signal — bypass the default meaningful-kinds gate so non-meaningful
+    // kinds like `supervisor_warning` remain matchable when requested.
+    const hasExplicitKind = filter.kind !== undefined &&
+        (typeof filter.kind === "string" || filter.kind.length > 0);
+    if (!filter.includeNonMeaningful &&
+        !hasExplicitKind &&
+        !MEANINGFUL_EVENT_KINDS.has(ev.kind)) {
+        return false;
+    }
+    if (!filter.includeProgress && ev.kind === "progress")
+        return false;
+    if (!matchesKind(ev.kind, filter.kind))
+        return false;
+    if (filter.thread !== undefined) {
+        if (!isThreadEvent(ev))
+            return false;
+        if (ev.thread !== filter.thread)
+            return false;
+    }
+    if (filter.action !== undefined) {
+        if (!isThreadEvent(ev))
+            return false;
+        if (ev.action !== filter.action)
+            return false;
+    }
+    if (filter.from && filter.from.length > 0) {
+        if (!filter.from.includes(ev.by))
+            return false;
+    }
+    if (filter.tag !== undefined && ev.tag !== filter.tag) {
+        return false;
+    }
+    if (filter.to) {
+        const evTo = ev.to;
+        if (filter.to === "exclusive") {
+            if (!evTo)
+                return false;
+        }
+        else {
+            if (!evTo)
+                return true;
+            if (Array.isArray(evTo))
+                return evTo.includes(filter.to);
+            return evTo === filter.to;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=filter.js.map

package/dist/channel/internal/store/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../../src/channel/internal/store/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,GAGd,MAAM,aAAa,CAAC;AAGrB,MAAM,CAAC,MAAM,sBAAsB,GAAkC,IAAI,GAAG,CAAC;IAC3E,QAAQ;IACR,MAAM;IACN,OAAO;IACP,SAAS;IACT,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;IACR,WAAW;IACX,MAAM;IACN,OAAO;CACc,CAAC,CAAC;AAoBzB,SAAS,WAAW,CAClB,MAAwB,EACxB,UAAsC;IAEtC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,MAAM,KAAK,UAAU,CAAC;IACjE,4EAA4E;IAC5E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,EAAgB,EAChB,MAA0B;IAE1B,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAEvD,sEAAsE;IACtE,sEAAsE;IACtE,mEAAmE;IACnE,MAAM,eAAe,GACnB,MAAM,CAAC,IAAI,KAAK,SAAS;QACzB,CAAC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE9D,IACE,CAAC,MAAM,CAAC,oBAAoB;QAC5B,CAAC,eAAe;QAChB,CAAC,sBAAsB,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAEpE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAErD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;IAChD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;IAChD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;IACjD,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAK,EAAuB,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,IAAI,GAAI,EAAiC,CAAC,EAAE,CAAC;QACnD,IAAI,MAAM,CAAC,EAAE,KAAK,WAAW,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI;gBAAE,OAAO,KAAK,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YACvB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzD,OAAO,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/channel/internal/store/inbox.d.ts

@@ -0,0 +1,17 @@
+import type { ChannelEvent, MessageChannelEvent } from "./events.js";
+import type { InboxPolicy } from "./schema.js";
+/** Default inbox policy applied to workers / spawned events without one. */
+export declare const DEFAULT_INBOX_POLICY: InboxPolicy;
+/**
+ * Decide whether a channel `message` event should be delivered to a
+ * worker's inbox under the given policy. Single source of truth shared
+ * by the worker registry reducer, the delivery helper, and the CLI
+ * supervisor inbox watcher.
+ *
+ * - `explicitOnly`: deliver only when `to` targets the worker.
+ * - `broadcastAndExplicit`: also deliver broadcast messages (no `to`).
+ *
+ * A worker never consumes its own message events.
+ */
+export declare function matchesInboxPolicy(ev: ChannelEvent, workerId: string, policy: InboxPolicy): ev is MessageChannelEvent;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/channel/internal/store/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../../../src/channel/internal/store/inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,EAAE,WAA4B,CAAC;AAOhE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAClB,EAAE,IAAI,mBAAmB,CAO3B"}

package/dist/channel/internal/store/inbox.js

@@ -0,0 +1,30 @@
+/** Default inbox policy applied to workers / spawned events without one. */
+export const DEFAULT_INBOX_POLICY = "explicitOnly";
+function toList(to) {
+    if (to === undefined)
+        return [];
+    return Array.isArray(to) ? to : [to];
+}
+/**
+ * Decide whether a channel `message` event should be delivered to a
+ * worker's inbox under the given policy. Single source of truth shared
+ * by the worker registry reducer, the delivery helper, and the CLI
+ * supervisor inbox watcher.
+ *
+ * - `explicitOnly`: deliver only when `to` targets the worker.
+ * - `broadcastAndExplicit`: also deliver broadcast messages (no `to`).
+ *
+ * A worker never consumes its own message events.
+ */
+export function matchesInboxPolicy(ev, workerId, policy) {
+    if (ev.kind !== "message")
+        return false;
+    if (ev.by === workerId)
+        return false;
+    const targets = toList(ev.to);
+    if (targets.length > 0)
+        return targets.includes(workerId);
+    // Broadcast (no `to`).
+    return policy === "broadcastAndExplicit";
+}
+//# sourceMappingURL=inbox.js.map

package/dist/channel/internal/store/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../../../src/channel/internal/store/inbox.ts"],"names":[],"mappings":"AAGA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAgB,cAAc,CAAC;AAEhE,SAAS,MAAM,CAAC,EAAiC;IAC/C,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAgB,EAChB,QAAgB,EAChB,MAAmB;IAEnB,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,EAAE,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC1D,uBAAuB;IACvB,OAAO,MAAM,KAAK,sBAAsB,CAAC;AAC3C,CAAC"}

package/dist/channel/internal/store/lock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * File-based advisory lock primitive.
+ *
+ * Uses `open(path, "wx")` (O_EXCL) for atomic creation across processes.
+ * Each lockfile stores the holder's pid for forensic + stale-lock
+ * recovery. If a lock file exists but the owning pid is no longer alive,
+ * the next `acquireLock` will steal it.
+ */
+interface AcquireOptions {
+    retryIntervalMs?: number;
+    maxWaitMs?: number;
+}
+export declare function acquireLock(lockFile: string, opts?: AcquireOptions): Promise<void>;
+export declare function releaseLock(lockFile: string): void;
+export declare function withLock<T>(lockFile: string, fn: () => Promise<T> | T, opts?: AcquireOptions): Promise<T>;
+export {};
+//# sourceMappingURL=lock.d.ts.map

package/dist/channel/internal/store/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../../src/channel/internal/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,UAAU,cAAc;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CASlD;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,CAAC,CAAC,CAOZ"}