@zfdx123/dsh-hooks-ordering 1.0.1

package/lib/service-base-CCmIBwnB.d.ts

@@ -0,0 +1,100 @@
+import { n as Orderable } from "./topo-sort-BZ1fFcTs.js";
+import { r as DagSection } from "./dag-Bqx-sl71.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+
+//#region src/service-base.d.ts
+
+/**
+ * Where a participant runs relative to the native hook chain.
+ * - `front`: ahead of every native listener (and, for waterfall, the built-in default).
+ * - `back`: behind the native chain (waterfall) / best-effort last (serial).
+ */
+type Phase = 'front' | 'back';
+/** Thrown when registering into, or double-controlling, a hook in an unsupported state. */
+declare class HookControlError extends Error {
+  /**
+   * @param message - the specific control-state violation.
+   */
+  constructor(message: string);
+}
+/** Optional file logging shared by both services. */
+interface HookOrderingLogConfig {
+  /**
+   * When set, the constraint DAG (JSON) is written to this file on every
+   * registration change, so it always reflects current state. Write failures
+   * are reported via `console.warn` and never thrown back into the fiber.
+   */
+  readonly log?: string;
+}
+/** Per-hook coordinator state: the two ordered phases and the disposer for the installed coordinator(s). */
+interface ControlledHook<E extends Orderable> {
+  readonly front: E[];
+  readonly back: E[];
+  readonly dispose: () => void;
+}
+/**
+ * Common base for the hook-ordering services. Subclasses implement
+ * {@link install} (register the coordinator listener(s) for one hook and return
+ * their disposer) and expose a typed `register`; everything else is shared.
+ * @typeParam E - the participant entry type stored per phase.
+ */
+declare abstract class HookOrderingBase<E extends Orderable> extends Service {
+  protected readonly hooks: Map<string, ControlledHook<E>>;
+  /** File the DAG is logged to on every registration change, if configured. */
+  readonly log: string | undefined;
+  /**
+   * @param ctx - the Cordis context to register the service in.
+   * @param name - the service name exposed on `ctx`.
+   * @param config - optional `log` file for the constraint DAG. May be `null`:
+   * a loader row whose `config:` key holds only comments parses as YAML null.
+   */
+  constructor(ctx: Context, name: string, config?: HookOrderingLogConfig | null);
+  /**
+   * Install the coordinator listener(s) for one hook, capturing its `front`/
+   * `back` lists, and return a disposer removing them. Subclass-specific.
+   */
+  protected abstract install(hook: string, front: E[], back: E[]): () => void;
+  /**
+   * Take control of a hook by installing the coordinator listener(s). Called
+   * once per hook; participants then register into it. Controlling twice is
+   * rejected — a second coordinator would reintroduce the race this removes.
+   *
+   * @param hook - the event name to control.
+   * @returns a disposer that removes the coordinator(s) and forgets the hook.
+   * @throws {HookControlError} when the hook is already controlled.
+   */
+  control(hook: string): () => void;
+  /**
+   * Shared registration: push the entry into the hook's phase list as a fiber
+   * effect, refreshing the DAG log on add and remove.
+   *
+   * @returns a disposer that unregisters this participant.
+   * @throws {HookControlError} when the hook has not been controlled.
+   */
+  protected registerEntry(hook: string, phase: Phase, entry: E): () => void;
+  /**
+   * Compute the ordered participant names for one hook phase without running
+   * them. Reflects current registrations; useful for tests and diagnostics.
+   *
+   * @throws {HookControlError} when the hook has not been controlled.
+   */
+  plan(hook: string, phase: Phase): string[];
+  /**
+   * Serialize the constraint DAG of every controlled hook (all phases) as
+   * pretty-printed JSON. Pure read: does not write the log file or throw on
+   * cycles — the graph is most useful precisely when constraints conflict.
+   */
+  dumpDag(): string;
+  /** Flatten every controlled hook into its `front`/`back` DAG sections. */
+  protected dagSections(): DagSection[];
+  /**
+   * Best-effort write of the current DAG to the configured `log` file. Never
+   * throws: a failure (e.g. unwritable path) is reported via `console.warn`,
+   * because this runs inside registration effects and disposers, where an
+   * exception would corrupt fiber teardown.
+   */
+  protected refreshLog(): void;
+}
+//#endregion
+export { Phase as a, HookOrderingLogConfig as i, HookControlError as n, HookOrderingBase as r, ControlledHook as t };
+//# sourceMappingURL=service-base-CCmIBwnB.d.ts.map

package/lib/service-base-CCmIBwnB.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-base-CCmIBwnB.d.ts","names":[],"sources":["../src/service-base.ts"],"sourcesContent":[],"mappings":";;;;;;AAyDA;;;;;AAWmB,KA/CP,KAAA,GA+CO,OAAA,GAAA,MAAA;;AAS+B,cArDrC,gBAAA,SAAyB,KAAA,CAqDY;EAAW;;;EA8DjC,WAAA,CAAA,OAAA,EAAA,MAAA;;;AAlF+C,UAtB1D,qBAAA,CAsB0D;;;;;;;;;UAZ1D,yBAAyB;kBACxB;iBACD;;;;;;;;;uBAUK,2BAA2B,mBAAmB,OAAA;4BAC1C,YAAA,eAAA;;;;;;;;;mBAUP,gCAA+B;;;;;kDASA,WAAW;;;;;;;;;;;;;;;;;;+CAmCd,cAAc;;;;;;;4BA2BjC;;;;;;;;2BAgBD"}

package/lib/service-base-a5vKg62S.js

@@ -0,0 +1,139 @@
+import { t as buildDag } from "./dag-DVhoBjBG.js";
+import { r as topoSort } from "./topo-sort-CfwYPY4U.js";
+import { writeFileSync } from "node:fs";
+import { Service } from "@deepseek-ai/cordis";
+
+//#region src/service-base.ts
+/** Thrown when registering into, or double-controlling, a hook in an unsupported state. */
+var HookControlError = class extends Error {
+	/**
+	* @param message - the specific control-state violation.
+	*/
+	constructor(message) {
+		super(`hooks-ordering: ${message}`);
+		this.name = "HookControlError";
+	}
+};
+/**
+* Common base for the hook-ordering services. Subclasses implement
+* {@link install} (register the coordinator listener(s) for one hook and return
+* their disposer) and expose a typed `register`; everything else is shared.
+* @typeParam E - the participant entry type stored per phase.
+*/
+var HookOrderingBase = class extends Service {
+	hooks = /* @__PURE__ */ new Map();
+	/** File the DAG is logged to on every registration change, if configured. */
+	log;
+	/**
+	* @param ctx - the Cordis context to register the service in.
+	* @param name - the service name exposed on `ctx`.
+	* @param config - optional `log` file for the constraint DAG. May be `null`:
+	* a loader row whose `config:` key holds only comments parses as YAML null.
+	*/
+	constructor(ctx, name, config = {}) {
+		super(ctx, name);
+		this.log = config?.log;
+	}
+	/**
+	* Take control of a hook by installing the coordinator listener(s). Called
+	* once per hook; participants then register into it. Controlling twice is
+	* rejected — a second coordinator would reintroduce the race this removes.
+	*
+	* @param hook - the event name to control.
+	* @returns a disposer that removes the coordinator(s) and forgets the hook.
+	* @throws {HookControlError} when the hook is already controlled.
+	*/
+	control(hook) {
+		if (this.hooks.has(hook)) throw new HookControlError(`hook ${JSON.stringify(hook)} is already controlled`);
+		const front = [];
+		const back = [];
+		const removeListeners = this.install(hook, front, back);
+		const dispose = () => {
+			removeListeners();
+			this.hooks.delete(hook);
+			this.refreshLog();
+		};
+		this.hooks.set(hook, {
+			front,
+			back,
+			dispose
+		});
+		this.refreshLog();
+		return dispose;
+	}
+	/**
+	* Shared registration: push the entry into the hook's phase list as a fiber
+	* effect, refreshing the DAG log on add and remove.
+	*
+	* @returns a disposer that unregisters this participant.
+	* @throws {HookControlError} when the hook has not been controlled.
+	*/
+	registerEntry(hook, phase, entry) {
+		const controlled = this.hooks.get(hook);
+		if (controlled === void 0) throw new HookControlError(`hook ${JSON.stringify(hook)} is not controlled; call control(${JSON.stringify(hook)}) first`);
+		const list = controlled[phase];
+		return this.ctx.effect(() => {
+			list.push(entry);
+			this.refreshLog();
+			return () => {
+				const at = list.indexOf(entry);
+				if (at >= 0) list.splice(at, 1);
+				this.refreshLog();
+			};
+		}, `${this.name}.register(${JSON.stringify(hook)}, ${JSON.stringify(phase)}, ${JSON.stringify(entry.name)})`);
+	}
+	/**
+	* Compute the ordered participant names for one hook phase without running
+	* them. Reflects current registrations; useful for tests and diagnostics.
+	*
+	* @throws {HookControlError} when the hook has not been controlled.
+	*/
+	plan(hook, phase) {
+		const controlled = this.hooks.get(hook);
+		if (controlled === void 0) throw new HookControlError(`hook ${JSON.stringify(hook)} is not controlled`);
+		return topoSort(controlled[phase]).map((entry) => entry.name);
+	}
+	/**
+	* Serialize the constraint DAG of every controlled hook (all phases) as
+	* pretty-printed JSON. Pure read: does not write the log file or throw on
+	* cycles — the graph is most useful precisely when constraints conflict.
+	*/
+	dumpDag() {
+		return JSON.stringify(buildDag(this.dagSections()), null, 2);
+	}
+	/** Flatten every controlled hook into its `front`/`back` DAG sections. */
+	dagSections() {
+		const sections = [];
+		for (const [hook, controlled] of this.hooks) {
+			sections.push({
+				hook,
+				phase: "front",
+				entries: controlled.front
+			});
+			sections.push({
+				hook,
+				phase: "back",
+				entries: controlled.back
+			});
+		}
+		return sections;
+	}
+	/**
+	* Best-effort write of the current DAG to the configured `log` file. Never
+	* throws: a failure (e.g. unwritable path) is reported via `console.warn`,
+	* because this runs inside registration effects and disposers, where an
+	* exception would corrupt fiber teardown.
+	*/
+	refreshLog() {
+		if (this.log === void 0) return;
+		try {
+			writeFileSync(this.log, `${this.dumpDag()}\n`);
+		} catch (error) {
+			console.warn(`hooks-ordering: failed to write DAG log to ${JSON.stringify(this.log)}:`, error);
+		}
+	}
+};
+
+//#endregion
+export { HookOrderingBase as n, HookControlError as t };
+//# sourceMappingURL=service-base-a5vKg62S.js.map

package/lib/service-base-a5vKg62S.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-base-a5vKg62S.js","names":["front: E[]","back: E[]","sections: DagSection[]"],"sources":["../src/service-base.ts"],"sourcesContent":["/**\n * Shared coordinator machinery for the waterfall and serial hook-ordering\n * services. Both manage, per controlled hook, two ordered participant lists\n * (`front`/`back`) plus the disposer for the installed coordinator(s); they\n * differ only in HOW the coordinator listeners are installed and HOW a phase\n * runs (waterfall wraps the native chain via `next()`; serial runs participants\n * ahead of it with bail short-circuiting). Registration, planning, DAG dumping,\n * and optional file logging are identical, so they live here.\n * @module dsh-hooks-ordering/service-base\n */\n\nimport { writeFileSync } from 'node:fs'\nimport { type Context, Service } from '@deepseek-ai/cordis'\nimport { type DagSection, buildDag } from './dag.ts'\nimport { type Orderable, topoSort } from './topo-sort.ts'\n\n/**\n * Where a participant runs relative to the native hook chain.\n * - `front`: ahead of every native listener (and, for waterfall, the built-in default).\n * - `back`: behind the native chain (waterfall) / best-effort last (serial).\n */\nexport type Phase = 'front' | 'back'\n\n/** Thrown when registering into, or double-controlling, a hook in an unsupported state. */\nexport class HookControlError extends Error {\n  /**\n   * @param message - the specific control-state violation.\n   */\n  constructor(message: string) {\n    super(`hooks-ordering: ${message}`)\n    this.name = 'HookControlError'\n  }\n}\n\n/** Optional file logging shared by both services. */\nexport interface HookOrderingLogConfig {\n  /**\n   * When set, the constraint DAG (JSON) is written to this file on every\n   * registration change, so it always reflects current state. Write failures\n   * are reported via `console.warn` and never thrown back into the fiber.\n   */\n  readonly log?: string\n}\n\n/** Per-hook coordinator state: the two ordered phases and the disposer for the installed coordinator(s). */\nexport interface ControlledHook<E extends Orderable> {\n  readonly front: E[]\n  readonly back: E[]\n  readonly dispose: () => void\n}\n\n/**\n * Common base for the hook-ordering services. Subclasses implement\n * {@link install} (register the coordinator listener(s) for one hook and return\n * their disposer) and expose a typed `register`; everything else is shared.\n * @typeParam E - the participant entry type stored per phase.\n */\nexport abstract class HookOrderingBase<E extends Orderable> extends Service {\n  protected readonly hooks = new Map<string, ControlledHook<E>>()\n  /** File the DAG is logged to on every registration change, if configured. */\n  readonly log: string | undefined\n\n  /**\n   * @param ctx - the Cordis context to register the service in.\n   * @param name - the service name exposed on `ctx`.\n   * @param config - optional `log` file for the constraint DAG. May be `null`:\n   * a loader row whose `config:` key holds only comments parses as YAML null.\n   */\n  constructor(ctx: Context, name: string, config: HookOrderingLogConfig | null = {}) {\n    super(ctx, name)\n    this.log = config?.log\n  }\n\n  /**\n   * Install the coordinator listener(s) for one hook, capturing its `front`/\n   * `back` lists, and return a disposer removing them. Subclass-specific.\n   */\n  protected abstract install(hook: string, front: E[], back: E[]): () => void\n\n  /**\n   * Take control of a hook by installing the coordinator listener(s). Called\n   * once per hook; participants then register into it. Controlling twice is\n   * rejected — a second coordinator would reintroduce the race this removes.\n   *\n   * @param hook - the event name to control.\n   * @returns a disposer that removes the coordinator(s) and forgets the hook.\n   * @throws {HookControlError} when the hook is already controlled.\n   */\n  control(hook: string): () => void {\n    if (this.hooks.has(hook)) throw new HookControlError(`hook ${JSON.stringify(hook)} is already controlled`)\n\n    const front: E[] = []\n    const back: E[] = []\n    const removeListeners = this.install(hook, front, back)\n\n    const dispose = (): void => {\n      removeListeners()\n      this.hooks.delete(hook)\n      this.refreshLog()\n    }\n    this.hooks.set(hook, { front, back, dispose })\n    this.refreshLog()\n    return dispose\n  }\n\n  /**\n   * Shared registration: push the entry into the hook's phase list as a fiber\n   * effect, refreshing the DAG log on add and remove.\n   *\n   * @returns a disposer that unregisters this participant.\n   * @throws {HookControlError} when the hook has not been controlled.\n   */\n  protected registerEntry(hook: string, phase: Phase, entry: E): () => void {\n    const controlled = this.hooks.get(hook)\n    if (controlled === undefined)\n      throw new HookControlError(\n        `hook ${JSON.stringify(hook)} is not controlled; call control(${JSON.stringify(hook)}) first`,\n      )\n    const list = controlled[phase]\n    return this.ctx.effect(\n      () => {\n        list.push(entry)\n        this.refreshLog()\n        return () => {\n          const at = list.indexOf(entry)\n          if (at >= 0) list.splice(at, 1)\n          this.refreshLog()\n        }\n      },\n      `${this.name}.register(${JSON.stringify(hook)}, ${JSON.stringify(phase)}, ${JSON.stringify(entry.name)})`,\n    )\n  }\n\n  /**\n   * Compute the ordered participant names for one hook phase without running\n   * them. Reflects current registrations; useful for tests and diagnostics.\n   *\n   * @throws {HookControlError} when the hook has not been controlled.\n   */\n  plan(hook: string, phase: Phase): string[] {\n    const controlled = this.hooks.get(hook)\n    if (controlled === undefined) throw new HookControlError(`hook ${JSON.stringify(hook)} is not controlled`)\n    return topoSort(controlled[phase]).map((entry) => entry.name)\n  }\n\n  /**\n   * Serialize the constraint DAG of every controlled hook (all phases) as\n   * pretty-printed JSON. Pure read: does not write the log file or throw on\n   * cycles — the graph is most useful precisely when constraints conflict.\n   */\n  dumpDag(): string {\n    return JSON.stringify(buildDag(this.dagSections()), null, 2)\n  }\n\n  /** Flatten every controlled hook into its `front`/`back` DAG sections. */\n  protected dagSections(): DagSection[] {\n    const sections: DagSection[] = []\n    for (const [hook, controlled] of this.hooks) {\n      sections.push({ hook, phase: 'front', entries: controlled.front })\n      sections.push({ hook, phase: 'back', entries: controlled.back })\n    }\n    return sections\n  }\n\n  /**\n   * Best-effort write of the current DAG to the configured `log` file. Never\n   * throws: a failure (e.g. unwritable path) is reported via `console.warn`,\n   * because this runs inside registration effects and disposers, where an\n   * exception would corrupt fiber teardown.\n   */\n  protected refreshLog(): void {\n    if (this.log === undefined) return\n    try {\n      writeFileSync(this.log, `${this.dumpDag()}\\n`)\n    } catch (error) {\n      console.warn(`hooks-ordering: failed to write DAG log to ${JSON.stringify(this.log)}:`, error)\n    }\n  }\n}\n"],"mappings":";;;;;;;AAwBA,IAAa,mBAAb,cAAsC,MAAM;;;;CAI1C,YAAY,SAAiB;AAC3B,QAAM,mBAAmB,UAAU;AACnC,OAAK,OAAO;;;;;;;;;AA2BhB,IAAsB,mBAAtB,cAAoE,QAAQ;CAC1E,AAAmB,wBAAQ,IAAI,KAAgC;;CAE/D,AAAS;;;;;;;CAQT,YAAY,KAAc,MAAc,SAAuC,EAAE,EAAE;AACjF,QAAM,KAAK,KAAK;AAChB,OAAK,MAAM,QAAQ;;;;;;;;;;;CAkBrB,QAAQ,MAA0B;AAChC,MAAI,KAAK,MAAM,IAAI,KAAK,CAAE,OAAM,IAAI,iBAAiB,QAAQ,KAAK,UAAU,KAAK,CAAC,wBAAwB;EAE1G,MAAMA,QAAa,EAAE;EACrB,MAAMC,OAAY,EAAE;EACpB,MAAM,kBAAkB,KAAK,QAAQ,MAAM,OAAO,KAAK;EAEvD,MAAM,gBAAsB;AAC1B,oBAAiB;AACjB,QAAK,MAAM,OAAO,KAAK;AACvB,QAAK,YAAY;;AAEnB,OAAK,MAAM,IAAI,MAAM;GAAE;GAAO;GAAM;GAAS,CAAC;AAC9C,OAAK,YAAY;AACjB,SAAO;;;;;;;;;CAUT,AAAU,cAAc,MAAc,OAAc,OAAsB;EACxE,MAAM,aAAa,KAAK,MAAM,IAAI,KAAK;AACvC,MAAI,eAAe,OACjB,OAAM,IAAI,iBACR,QAAQ,KAAK,UAAU,KAAK,CAAC,mCAAmC,KAAK,UAAU,KAAK,CAAC,SACtF;EACH,MAAM,OAAO,WAAW;AACxB,SAAO,KAAK,IAAI,aACR;AACJ,QAAK,KAAK,MAAM;AAChB,QAAK,YAAY;AACjB,gBAAa;IACX,MAAM,KAAK,KAAK,QAAQ,MAAM;AAC9B,QAAI,MAAM,EAAG,MAAK,OAAO,IAAI,EAAE;AAC/B,SAAK,YAAY;;KAGrB,GAAG,KAAK,KAAK,YAAY,KAAK,UAAU,KAAK,CAAC,IAAI,KAAK,UAAU,MAAM,CAAC,IAAI,KAAK,UAAU,MAAM,KAAK,CAAC,GACxG;;;;;;;;CASH,KAAK,MAAc,OAAwB;EACzC,MAAM,aAAa,KAAK,MAAM,IAAI,KAAK;AACvC,MAAI,eAAe,OAAW,OAAM,IAAI,iBAAiB,QAAQ,KAAK,UAAU,KAAK,CAAC,oBAAoB;AAC1G,SAAO,SAAS,WAAW,OAAO,CAAC,KAAK,UAAU,MAAM,KAAK;;;;;;;CAQ/D,UAAkB;AAChB,SAAO,KAAK,UAAU,SAAS,KAAK,aAAa,CAAC,EAAE,MAAM,EAAE;;;CAI9D,AAAU,cAA4B;EACpC,MAAMC,WAAyB,EAAE;AACjC,OAAK,MAAM,CAAC,MAAM,eAAe,KAAK,OAAO;AAC3C,YAAS,KAAK;IAAE;IAAM,OAAO;IAAS,SAAS,WAAW;IAAO,CAAC;AAClE,YAAS,KAAK;IAAE;IAAM,OAAO;IAAQ,SAAS,WAAW;IAAM,CAAC;;AAElE,SAAO;;;;;;;;CAST,AAAU,aAAmB;AAC3B,MAAI,KAAK,QAAQ,OAAW;AAC5B,MAAI;AACF,iBAAc,KAAK,KAAK,GAAG,KAAK,SAAS,CAAC,IAAI;WACvC,OAAO;AACd,WAAQ,KAAK,8CAA8C,KAAK,UAAU,KAAK,IAAI,CAAC,IAAI,MAAM"}

package/lib/service-base.d.ts

@@ -0,0 +1,4 @@
+import "./topo-sort-BZ1fFcTs.js";
+import "./dag-Bqx-sl71.js";
+import { a as Phase, i as HookOrderingLogConfig, n as HookControlError, r as HookOrderingBase, t as ControlledHook } from "./service-base-CCmIBwnB.js";
+export { ControlledHook, HookControlError, HookOrderingBase, HookOrderingLogConfig, Phase };

package/lib/service-base.js

@@ -0,0 +1,5 @@
+import "./dag-DVhoBjBG.js";
+import "./topo-sort-CfwYPY4U.js";
+import { n as HookOrderingBase, t as HookControlError } from "./service-base-a5vKg62S.js";
+
+export { HookControlError, HookOrderingBase };

package/lib/topo-sort-BZ1fFcTs.d.ts

@@ -0,0 +1,54 @@
+//#region src/topo-sort.d.ts
+/**
+ * Deterministic topological sort for named entries carrying `before`/`after`
+ * ordering constraints. Zero runtime dependencies: the sort is a pure function
+ * of its input, independent of any Cordis context or plugin load order.
+ * @module dsh-hooks-ordering/topo-sort
+ */
+/** An entry that can be ordered relative to others by name. */
+interface Orderable {
+  /** Unique identifier within one hook phase. Referenced by other entries' `before`/`after`. */
+  readonly name: string;
+  /** Names this entry must run before. An unknown name imposes no constraint (see {@link topoSort}). */
+  readonly before?: readonly string[];
+  /** Names this entry must run after. An unknown name imposes no constraint (see {@link topoSort}). */
+  readonly after?: readonly string[];
+}
+/** Thrown when `before`/`after` constraints form a cycle, so no total order exists. */
+declare class OrderingCycleError extends Error {
+  /** The names still blocked when the sort stalled — the entries on and behind the cycle. */
+  readonly cycle: readonly string[];
+  /**
+   * @param cycle - the names left unresolved by the cycle.
+   */
+  constructor(cycle: readonly string[]);
+}
+/** Thrown when two entries in one phase share a `name`, which would make references ambiguous. */
+declare class DuplicateNameError extends Error {
+  /** The duplicated entry name. */
+  readonly duplicate: string;
+  /**
+   * @param duplicate - the name registered more than once.
+   */
+  constructor(duplicate: string);
+}
+/**
+ * Order entries so every `after` target precedes the entry and every `before`
+ * target follows it. Ties (entries with no constraint between them) keep their
+ * input order, so the result is stable and independent of registration timing.
+ *
+ * An unknown name in `before`/`after` (no registered entry owns it) imposes no
+ * constraint rather than failing: cross-vendor entries reference optional peers
+ * that may not be loaded, so a missing target is a legitimate no-op, not a
+ * misconfiguration. A cycle among present entries is fatal — it has no valid
+ * order — and throws {@link OrderingCycleError}.
+ *
+ * @param entries - the entries to order; each `name` must be unique.
+ * @returns a new array of the same entries in a constraint-respecting order.
+ * @throws {DuplicateNameError} when two entries share a `name`.
+ * @throws {OrderingCycleError} when present entries form an ordering cycle.
+ */
+declare function topoSort<T extends Orderable>(entries: readonly T[]): T[];
+//#endregion
+export { topoSort as i, Orderable as n, OrderingCycleError as r, DuplicateNameError as t };
+//# sourceMappingURL=topo-sort-BZ1fFcTs.d.ts.map

package/lib/topo-sort-BZ1fFcTs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-sort-BZ1fFcTs.d.ts","names":[],"sources":["../src/topo-sort.ts"],"sourcesContent":[],"mappings":";;AAQA;AAUA;AAcA;AA6BA;;;AAAsE,UArDrD,SAAA,CAqDqD;EAAC;;;;;;;;cA3C1D,kBAAA,SAA2B,KAAA;;;;;;;;;cAc3B,kBAAA,SAA2B,KAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA6BxB,mBAAmB,6BAA6B,MAAM"}

package/lib/topo-sort-CfwYPY4U.js

@@ -0,0 +1,83 @@
+//#region src/topo-sort.ts
+/** Thrown when `before`/`after` constraints form a cycle, so no total order exists. */
+var OrderingCycleError = class extends Error {
+	/** The names still blocked when the sort stalled — the entries on and behind the cycle. */
+	cycle;
+	/**
+	* @param cycle - the names left unresolved by the cycle.
+	*/
+	constructor(cycle) {
+		super(`hooks-ordering: constraints form a cycle among: ${cycle.join(", ")}`);
+		this.name = "OrderingCycleError";
+		this.cycle = cycle;
+	}
+};
+/** Thrown when two entries in one phase share a `name`, which would make references ambiguous. */
+var DuplicateNameError = class extends Error {
+	/** The duplicated entry name. */
+	duplicate;
+	/**
+	* @param duplicate - the name registered more than once.
+	*/
+	constructor(duplicate) {
+		super(`hooks-ordering: duplicate entry name ${JSON.stringify(duplicate)}`);
+		this.name = "DuplicateNameError";
+		this.duplicate = duplicate;
+	}
+};
+/**
+* Order entries so every `after` target precedes the entry and every `before`
+* target follows it. Ties (entries with no constraint between them) keep their
+* input order, so the result is stable and independent of registration timing.
+*
+* An unknown name in `before`/`after` (no registered entry owns it) imposes no
+* constraint rather than failing: cross-vendor entries reference optional peers
+* that may not be loaded, so a missing target is a legitimate no-op, not a
+* misconfiguration. A cycle among present entries is fatal — it has no valid
+* order — and throws {@link OrderingCycleError}.
+*
+* @param entries - the entries to order; each `name` must be unique.
+* @returns a new array of the same entries in a constraint-respecting order.
+* @throws {DuplicateNameError} when two entries share a `name`.
+* @throws {OrderingCycleError} when present entries form an ordering cycle.
+*/
+function topoSort(entries) {
+	const index = /* @__PURE__ */ new Map();
+	entries.forEach((entry, position) => {
+		if (index.has(entry.name)) throw new DuplicateNameError(entry.name);
+		index.set(entry.name, position);
+	});
+	const successors = entries.map(() => []);
+	const indegree = entries.map(() => 0);
+	const addEdge = (fromName, toName) => {
+		const from = index.get(fromName);
+		const to = index.get(toName);
+		if (from === void 0 || to === void 0 || from === to) return;
+		successors[from].push(to);
+		indegree[to]++;
+	};
+	entries.forEach((entry) => {
+		for (const target of entry.after ?? []) addEdge(target, entry.name);
+		for (const target of entry.before ?? []) addEdge(entry.name, target);
+	});
+	const ready = [];
+	const pushReady = (node) => {
+		ready.push(node);
+		ready.sort((left, right) => left - right);
+	};
+	indegree.forEach((count, node) => {
+		if (count === 0) pushReady(node);
+	});
+	const result = [];
+	while (ready.length > 0) {
+		const node = ready.shift();
+		result.push(entries[node]);
+		for (const successor of successors[node]) if (--indegree[successor] === 0) pushReady(successor);
+	}
+	if (result.length !== entries.length) throw new OrderingCycleError(entries.filter((_, node) => indegree[node] > 0).map((entry) => entry.name));
+	return result;
+}
+
+//#endregion
+export { OrderingCycleError as n, topoSort as r, DuplicateNameError as t };
+//# sourceMappingURL=topo-sort-CfwYPY4U.js.map

package/lib/topo-sort-CfwYPY4U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-sort-CfwYPY4U.js","names":["successors: number[][]","indegree: number[]","ready: number[]","result: T[]"],"sources":["../src/topo-sort.ts"],"sourcesContent":["/**\n * Deterministic topological sort for named entries carrying `before`/`after`\n * ordering constraints. Zero runtime dependencies: the sort is a pure function\n * of its input, independent of any Cordis context or plugin load order.\n * @module dsh-hooks-ordering/topo-sort\n */\n\n/** An entry that can be ordered relative to others by name. */\nexport interface Orderable {\n  /** Unique identifier within one hook phase. Referenced by other entries' `before`/`after`. */\n  readonly name: string\n  /** Names this entry must run before. An unknown name imposes no constraint (see {@link topoSort}). */\n  readonly before?: readonly string[]\n  /** Names this entry must run after. An unknown name imposes no constraint (see {@link topoSort}). */\n  readonly after?: readonly string[]\n}\n\n/** Thrown when `before`/`after` constraints form a cycle, so no total order exists. */\nexport class OrderingCycleError extends Error {\n  /** The names still blocked when the sort stalled — the entries on and behind the cycle. */\n  readonly cycle: readonly string[]\n  /**\n   * @param cycle - the names left unresolved by the cycle.\n   */\n  constructor(cycle: readonly string[]) {\n    super(`hooks-ordering: constraints form a cycle among: ${cycle.join(', ')}`)\n    this.name = 'OrderingCycleError'\n    this.cycle = cycle\n  }\n}\n\n/** Thrown when two entries in one phase share a `name`, which would make references ambiguous. */\nexport class DuplicateNameError extends Error {\n  /** The duplicated entry name. */\n  readonly duplicate: string\n  /**\n   * @param duplicate - the name registered more than once.\n   */\n  constructor(duplicate: string) {\n    super(`hooks-ordering: duplicate entry name ${JSON.stringify(duplicate)}`)\n    this.name = 'DuplicateNameError'\n    this.duplicate = duplicate\n  }\n}\n\n/**\n * Order entries so every `after` target precedes the entry and every `before`\n * target follows it. Ties (entries with no constraint between them) keep their\n * input order, so the result is stable and independent of registration timing.\n *\n * An unknown name in `before`/`after` (no registered entry owns it) imposes no\n * constraint rather than failing: cross-vendor entries reference optional peers\n * that may not be loaded, so a missing target is a legitimate no-op, not a\n * misconfiguration. A cycle among present entries is fatal — it has no valid\n * order — and throws {@link OrderingCycleError}.\n *\n * @param entries - the entries to order; each `name` must be unique.\n * @returns a new array of the same entries in a constraint-respecting order.\n * @throws {DuplicateNameError} when two entries share a `name`.\n * @throws {OrderingCycleError} when present entries form an ordering cycle.\n */\nexport function topoSort<T extends Orderable>(entries: readonly T[]): T[] {\n  const index = new Map<string, number>()\n  entries.forEach((entry, position) => {\n    if (index.has(entry.name)) throw new DuplicateNameError(entry.name)\n    index.set(entry.name, position)\n  })\n\n  // successors[i] = entries that must run after entry i. indegree[i] = number\n  // of entries that must run before entry i.\n  const successors: number[][] = entries.map(() => [])\n  const indegree: number[] = entries.map(() => 0)\n\n  const addEdge = (fromName: string, toName: string): void => {\n    const from = index.get(fromName)\n    const to = index.get(toName)\n    // Unknown endpoint: the referenced peer is not loaded, so no ordering\n    // relation exists to enforce.\n    if (from === undefined || to === undefined || from === to) return\n    successors[from]!.push(to)\n    indegree[to]!++\n  }\n\n  entries.forEach((entry) => {\n    for (const target of entry.after ?? []) addEdge(target, entry.name)\n    for (const target of entry.before ?? []) addEdge(entry.name, target)\n  })\n\n  // Kahn's algorithm. The ready set holds nodes with no unmet predecessor; it\n  // is kept in ascending input position so equal candidates emit in input\n  // order, giving a deterministic, stable result. Per-phase entry counts are\n  // small, so a sort on each insertion is simpler than a hand-rolled heap.\n  const ready: number[] = []\n  const pushReady = (node: number): void => {\n    ready.push(node)\n    ready.sort((left, right) => left - right)\n  }\n  indegree.forEach((count, node) => {\n    if (count === 0) pushReady(node)\n  })\n\n  const result: T[] = []\n  while (ready.length > 0) {\n    const node = ready.shift()!\n    result.push(entries[node]!)\n    for (const successor of successors[node]!) {\n      if (--indegree[successor]! === 0) pushReady(successor)\n    }\n  }\n\n  if (result.length !== entries.length) {\n    // The entries still carrying an unmet predecessor are exactly those on or\n    // behind the cycle; naming them all is more useful than one arbitrary loop.\n    const blocked = entries.filter((_, node) => indegree[node]! > 0).map((entry) => entry.name)\n    throw new OrderingCycleError(blocked)\n  }\n  return result\n}\n"],"mappings":";;AAkBA,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;;;CAIT,YAAY,OAA0B;AACpC,QAAM,mDAAmD,MAAM,KAAK,KAAK,GAAG;AAC5E,OAAK,OAAO;AACZ,OAAK,QAAQ;;;;AAKjB,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;;;CAIT,YAAY,WAAmB;AAC7B,QAAM,wCAAwC,KAAK,UAAU,UAAU,GAAG;AAC1E,OAAK,OAAO;AACZ,OAAK,YAAY;;;;;;;;;;;;;;;;;;;AAoBrB,SAAgB,SAA8B,SAA4B;CACxE,MAAM,wBAAQ,IAAI,KAAqB;AACvC,SAAQ,SAAS,OAAO,aAAa;AACnC,MAAI,MAAM,IAAI,MAAM,KAAK,CAAE,OAAM,IAAI,mBAAmB,MAAM,KAAK;AACnE,QAAM,IAAI,MAAM,MAAM,SAAS;GAC/B;CAIF,MAAMA,aAAyB,QAAQ,UAAU,EAAE,CAAC;CACpD,MAAMC,WAAqB,QAAQ,UAAU,EAAE;CAE/C,MAAM,WAAW,UAAkB,WAAyB;EAC1D,MAAM,OAAO,MAAM,IAAI,SAAS;EAChC,MAAM,KAAK,MAAM,IAAI,OAAO;AAG5B,MAAI,SAAS,UAAa,OAAO,UAAa,SAAS,GAAI;AAC3D,aAAW,MAAO,KAAK,GAAG;AAC1B,WAAS;;AAGX,SAAQ,SAAS,UAAU;AACzB,OAAK,MAAM,UAAU,MAAM,SAAS,EAAE,CAAE,SAAQ,QAAQ,MAAM,KAAK;AACnE,OAAK,MAAM,UAAU,MAAM,UAAU,EAAE,CAAE,SAAQ,MAAM,MAAM,OAAO;GACpE;CAMF,MAAMC,QAAkB,EAAE;CAC1B,MAAM,aAAa,SAAuB;AACxC,QAAM,KAAK,KAAK;AAChB,QAAM,MAAM,MAAM,UAAU,OAAO,MAAM;;AAE3C,UAAS,SAAS,OAAO,SAAS;AAChC,MAAI,UAAU,EAAG,WAAU,KAAK;GAChC;CAEF,MAAMC,SAAc,EAAE;AACtB,QAAO,MAAM,SAAS,GAAG;EACvB,MAAM,OAAO,MAAM,OAAO;AAC1B,SAAO,KAAK,QAAQ,MAAO;AAC3B,OAAK,MAAM,aAAa,WAAW,MACjC,KAAI,EAAE,SAAS,eAAgB,EAAG,WAAU,UAAU;;AAI1D,KAAI,OAAO,WAAW,QAAQ,OAI5B,OAAM,IAAI,mBADM,QAAQ,QAAQ,GAAG,SAAS,SAAS,QAAS,EAAE,CAAC,KAAK,UAAU,MAAM,KAAK,CACtD;AAEvC,QAAO"}

package/lib/topo-sort.d.ts

@@ -0,0 +1,2 @@
+import { i as topoSort, n as Orderable, r as OrderingCycleError, t as DuplicateNameError } from "./topo-sort-BZ1fFcTs.js";
+export { DuplicateNameError, Orderable, OrderingCycleError, topoSort };

package/lib/topo-sort.js

@@ -0,0 +1,3 @@
+import { n as OrderingCycleError, r as topoSort, t as DuplicateNameError } from "./topo-sort-CfwYPY4U.js";
+
+export { DuplicateNameError, OrderingCycleError, topoSort };

package/lib/waterfall-Bu6m9gYc.js

@@ -0,0 +1,83 @@
+import { r as topoSort } from "./topo-sort-CfwYPY4U.js";
+import { n as HookOrderingBase, t as HookControlError } from "./service-base-a5vKg62S.js";
+
+//#region src/waterfall.ts
+/**
+* Coordinator service registered at `ctx.hooksOrdering`. One instance controls
+* any number of waterfall hooks; each controlled hook owns one bracket listener
+* and two ordered participant lists.
+*/
+var HookOrdering = class extends HookOrderingBase {
+	/**
+	* Hooks that must never carry a participant: their return value is consumed
+	* synchronously by the host, so the bracket's await would corrupt it.
+	* @see HookOrderingConfig.syncReturnHooks
+	*/
+	syncReturnHooks;
+	/**
+	* @param ctx - the Cordis context to register the service in.
+	* @param config - optional `log` file for the constraint DAG (JSON) and the
+	* `syncReturnHooks` admission list; `null` means defaults.
+	*/
+	constructor(ctx, config = {}) {
+		super(ctx, "hooksOrdering", config);
+		this.syncReturnHooks = new Set(config?.syncReturnHooks ?? []);
+	}
+	/**
+	* Install the single bracket listener. `prepend` places it first among
+	* current listeners so its `next()` encloses the rest of the native chain;
+	* the listener is an effect on this service's fiber and is removed with it or
+	* with the disposer {@link control} returns.
+	*
+	* The bracket is deliberately NOT `async` at its outermost level. Cordis'
+	* `waterfall` returns the outermost listener's value *synchronously*, so an
+	* `async` bracket would turn the hook's return value into a Promise for every
+	* caller — breaking any hook whose result the caller consumes without
+	* awaiting (dsh's `llm/stream` returns an AsyncIterable, and wraps with
+	* "not async iterable"). While both phases are empty there is nothing to
+	* order, so the chain is handed straight through and the hook's return type
+	* is exactly what it was before control was taken.
+	*/
+	install(hook, front, back) {
+		const bracket = (...args) => {
+			const next = args[args.length - 1];
+			if (front.length === 0 && back.length === 0) return next();
+			const payload = args.slice(0, -1);
+			return (async () => {
+				await runPhase(front, payload);
+				const result = await next();
+				await runPhase(back, payload);
+				return result;
+			})();
+		};
+		return this.ctx.on(hook, bracket, { prepend: true });
+	}
+	/**
+	* Register a participant into a controlled hook phase.
+	*
+	* @param hook - the controlled waterfall event name.
+	* @param phase - `front` to run ahead of the native chain, `back` to run behind it.
+	* @param entry - the participant, with optional `before`/`after` names and its `run` callback.
+	* @returns a disposer that unregisters this participant.
+	* @throws {HookControlError} when the hook has not been {@link control}led, or
+	* when it is declared in `syncReturnHooks` — there the participant would work
+	* but the host's return value would change type, which is the worse failure.
+	*/
+	register(hook, phase, entry) {
+		if (this.syncReturnHooks.has(hook)) throw new HookControlError(`hook ${JSON.stringify(hook)} returns to a caller that does not await it, so ordering participants would turn its return value into a Promise and break that caller; remove ${JSON.stringify(hook)} from syncReturnHooks only once the host awaits it`);
+		return this.registerEntry(hook, phase, entry);
+	}
+};
+/**
+* Run one phase's participants in stable topological order, awaiting each.
+* @param entries - the phase's registered participants.
+* @param payload - the hook payload passed to each `run` callback.
+*/
+async function runPhase(entries, payload) {
+	for (const entry of topoSort(entries)) await entry.run(...payload);
+}
+var waterfall_default = HookOrdering;
+
+//#endregion
+export { waterfall_default as n, HookOrdering as t };
+//# sourceMappingURL=waterfall-Bu6m9gYc.js.map

package/lib/waterfall-Bu6m9gYc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterfall-Bu6m9gYc.js","names":[],"sources":["../src/waterfall.ts"],"sourcesContent":["/**\n * `HookOrdering` — deterministic before/after ordering for Cordis waterfall\n * hooks whose participants are contributed by independent plugins.\n *\n * Cordis runs waterfall listeners in registration order (array position, with\n * `prepend` as the only lever), and registration order is driven by\n * inject-dependency activation — non-deterministic between unrelated plugins.\n * A plugin therefore cannot reliably say \"run me after that other plugin\",\n * especially across vendors that do not depend on each other.\n *\n * This service brackets a chosen waterfall hook with ONE prepended listener\n * that exploits the onion model: code before its `next()` runs ahead of the\n * whole native chain, code after runs behind it. Participants register into\n * this coordinator instead of the raw hook, declaring `before`/`after` names,\n * and the coordinator runs them in a stable topological order it fully\n * controls. The serial-dispatch twin lives in `./serial.ts`.\n *\n * @module dsh-hooks-ordering/waterfall\n */\n\nimport { type Context } from '@deepseek-ai/cordis'\nimport { HookControlError, HookOrderingBase, type HookOrderingLogConfig, type Phase } from './service-base.ts'\nimport { type Orderable, topoSort } from './topo-sort.ts'\n\n/**\n * One ordered participant in a controlled waterfall hook phase.\n * @typeParam A - the hook's payload argument tuple (the dispatched args without Cordis' trailing `next`).\n */\nexport interface HookEntry<A extends readonly unknown[] = readonly unknown[]> extends Orderable {\n  /** Run this participant with the hook payload. Awaited before the phase proceeds. */\n  readonly run: (...args: A) => void | Promise<void>\n}\n\n/** Configuration for the {@link HookOrdering} service. */\nexport interface HookOrderingConfig extends HookOrderingLogConfig {\n  /**\n   * Hook names whose dispatch return value the CALLER consumes without\n   * awaiting — dsh's `llm/stream` (an AsyncIterable iterated directly) and\n   * `session-telemetry/record` (a record handed straight to a backend) are the\n   * two in the shipped build.\n   *\n   * A participant cannot be ordered on such a hook. The bracket only preserves\n   * the native return value while both phases are empty; with a participant it\n   * must await, so it returns a Promise where the caller expects a value — a\n   * broken stream or a corrupted record, silently. {@link HookOrdering.register}\n   * therefore refuses those hooks, and *controlling* them stays allowed: the\n   * bracket is a transparent pass-through and may become useful the day the\n   * host starts awaiting that hook (then pass `[]` here, or a set without it).\n   */\n  readonly syncReturnHooks?: readonly string[]\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    hooksOrdering: HookOrdering\n  }\n}\n\n/**\n * Coordinator service registered at `ctx.hooksOrdering`. One instance controls\n * any number of waterfall hooks; each controlled hook owns one bracket listener\n * and two ordered participant lists.\n */\nexport class HookOrdering extends HookOrderingBase<HookEntry> {\n  /**\n   * Hooks that must never carry a participant: their return value is consumed\n   * synchronously by the host, so the bracket's await would corrupt it.\n   * @see HookOrderingConfig.syncReturnHooks\n   */\n  private readonly syncReturnHooks: ReadonlySet<string>\n\n  /**\n   * @param ctx - the Cordis context to register the service in.\n   * @param config - optional `log` file for the constraint DAG (JSON) and the\n   * `syncReturnHooks` admission list; `null` means defaults.\n   */\n  constructor(ctx: Context, config: HookOrderingConfig | null = {}) {\n    super(ctx, 'hooksOrdering', config)\n    this.syncReturnHooks = new Set(config?.syncReturnHooks ?? [])\n  }\n\n  /**\n   * Install the single bracket listener. `prepend` places it first among\n   * current listeners so its `next()` encloses the rest of the native chain;\n   * the listener is an effect on this service's fiber and is removed with it or\n   * with the disposer {@link control} returns.\n   *\n   * The bracket is deliberately NOT `async` at its outermost level. Cordis'\n   * `waterfall` returns the outermost listener's value *synchronously*, so an\n   * `async` bracket would turn the hook's return value into a Promise for every\n   * caller — breaking any hook whose result the caller consumes without\n   * awaiting (dsh's `llm/stream` returns an AsyncIterable, and wraps with\n   * \"not async iterable\"). While both phases are empty there is nothing to\n   * order, so the chain is handed straight through and the hook's return type\n   * is exactly what it was before control was taken.\n   */\n  protected install(hook: string, front: HookEntry[], back: HookEntry[]): () => void {\n    const bracket = (...args: unknown[]): unknown => {\n      const next = args[args.length - 1] as () => unknown\n      // Transparent fast path: no participants, so no await is needed and the\n      // native return value (promise or not) passes through unchanged.\n      if (front.length === 0 && back.length === 0) return next()\n      const payload = args.slice(0, -1)\n      // With participants the phases must be awaited, so the bracket can only\n      // return a promise from here on — inherent to ordering, not a choice.\n      return (async (): Promise<unknown> => {\n        await runPhase(front, payload)\n        const result = await next()\n        await runPhase(back, payload)\n        return result\n      })()\n    }\n    return this.ctx.on(hook as never, bracket as never, { prepend: true })\n  }\n\n  /**\n   * Register a participant into a controlled hook phase.\n   *\n   * @param hook - the controlled waterfall event name.\n   * @param phase - `front` to run ahead of the native chain, `back` to run behind it.\n   * @param entry - the participant, with optional `before`/`after` names and its `run` callback.\n   * @returns a disposer that unregisters this participant.\n   * @throws {HookControlError} when the hook has not been {@link control}led, or\n   * when it is declared in `syncReturnHooks` — there the participant would work\n   * but the host's return value would change type, which is the worse failure.\n   */\n  register<A extends readonly unknown[] = readonly unknown[]>(\n    hook: string,\n    phase: Phase,\n    entry: HookEntry<A>,\n  ): () => void {\n    if (this.syncReturnHooks.has(hook)) {\n      throw new HookControlError(\n        `hook ${JSON.stringify(hook)} returns to a caller that does not await it, so ordering participants would turn its return value into a Promise and break that caller; ` +\n          `remove ${JSON.stringify(hook)} from syncReturnHooks only once the host awaits it`,\n      )\n    }\n    return this.registerEntry(hook, phase, entry as unknown as HookEntry)\n  }\n}\n\n/**\n * Run one phase's participants in stable topological order, awaiting each.\n * @param entries - the phase's registered participants.\n * @param payload - the hook payload passed to each `run` callback.\n */\nasync function runPhase(entries: readonly HookEntry[], payload: readonly unknown[]): Promise<void> {\n  for (const entry of topoSort(entries)) {\n    await entry.run(...payload)\n  }\n}\n\nexport default HookOrdering\n"],"mappings":";;;;;;;;;AA+DA,IAAa,eAAb,cAAkC,iBAA4B;;;;;;CAM5D,AAAiB;;;;;;CAOjB,YAAY,KAAc,SAAoC,EAAE,EAAE;AAChE,QAAM,KAAK,iBAAiB,OAAO;AACnC,OAAK,kBAAkB,IAAI,IAAI,QAAQ,mBAAmB,EAAE,CAAC;;;;;;;;;;;;;;;;;CAkB/D,AAAU,QAAQ,MAAc,OAAoB,MAA+B;EACjF,MAAM,WAAW,GAAG,SAA6B;GAC/C,MAAM,OAAO,KAAK,KAAK,SAAS;AAGhC,OAAI,MAAM,WAAW,KAAK,KAAK,WAAW,EAAG,QAAO,MAAM;GAC1D,MAAM,UAAU,KAAK,MAAM,GAAG,GAAG;AAGjC,WAAQ,YAA8B;AACpC,UAAM,SAAS,OAAO,QAAQ;IAC9B,MAAM,SAAS,MAAM,MAAM;AAC3B,UAAM,SAAS,MAAM,QAAQ;AAC7B,WAAO;OACL;;AAEN,SAAO,KAAK,IAAI,GAAG,MAAe,SAAkB,EAAE,SAAS,MAAM,CAAC;;;;;;;;;;;;;CAcxE,SACE,MACA,OACA,OACY;AACZ,MAAI,KAAK,gBAAgB,IAAI,KAAK,CAChC,OAAM,IAAI,iBACR,QAAQ,KAAK,UAAU,KAAK,CAAC,iJACjB,KAAK,UAAU,KAAK,CAAC,oDAClC;AAEH,SAAO,KAAK,cAAc,MAAM,OAAO,MAA8B;;;;;;;;AASzE,eAAe,SAAS,SAA+B,SAA4C;AACjG,MAAK,MAAM,SAAS,SAAS,QAAQ,CACnC,OAAM,MAAM,IAAI,GAAG,QAAQ;;AAI/B,wBAAe"}

package/lib/waterfall-_5HkptkS.d.ts

@@ -0,0 +1,87 @@
+import { n as Orderable } from "./topo-sort-BZ1fFcTs.js";
+import { a as Phase, i as HookOrderingLogConfig, r as HookOrderingBase } from "./service-base-CCmIBwnB.js";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/waterfall.d.ts
+
+/**
+ * One ordered participant in a controlled waterfall hook phase.
+ * @typeParam A - the hook's payload argument tuple (the dispatched args without Cordis' trailing `next`).
+ */
+interface HookEntry<A extends readonly unknown[] = readonly unknown[]> extends Orderable {
+  /** Run this participant with the hook payload. Awaited before the phase proceeds. */
+  readonly run: (...args: A) => void | Promise<void>;
+}
+/** Configuration for the {@link HookOrdering} service. */
+interface HookOrderingConfig extends HookOrderingLogConfig {
+  /**
+   * Hook names whose dispatch return value the CALLER consumes without
+   * awaiting — dsh's `llm/stream` (an AsyncIterable iterated directly) and
+   * `session-telemetry/record` (a record handed straight to a backend) are the
+   * two in the shipped build.
+   *
+   * A participant cannot be ordered on such a hook. The bracket only preserves
+   * the native return value while both phases are empty; with a participant it
+   * must await, so it returns a Promise where the caller expects a value — a
+   * broken stream or a corrupted record, silently. {@link HookOrdering.register}
+   * therefore refuses those hooks, and *controlling* them stays allowed: the
+   * bracket is a transparent pass-through and may become useful the day the
+   * host starts awaiting that hook (then pass `[]` here, or a set without it).
+   */
+  readonly syncReturnHooks?: readonly string[];
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    hooksOrdering: HookOrdering;
+  }
+}
+/**
+ * Coordinator service registered at `ctx.hooksOrdering`. One instance controls
+ * any number of waterfall hooks; each controlled hook owns one bracket listener
+ * and two ordered participant lists.
+ */
+declare class HookOrdering extends HookOrderingBase<HookEntry> {
+  /**
+   * Hooks that must never carry a participant: their return value is consumed
+   * synchronously by the host, so the bracket's await would corrupt it.
+   * @see HookOrderingConfig.syncReturnHooks
+   */
+  private readonly syncReturnHooks;
+  /**
+   * @param ctx - the Cordis context to register the service in.
+   * @param config - optional `log` file for the constraint DAG (JSON) and the
+   * `syncReturnHooks` admission list; `null` means defaults.
+   */
+  constructor(ctx: Context, config?: HookOrderingConfig | null);
+  /**
+   * Install the single bracket listener. `prepend` places it first among
+   * current listeners so its `next()` encloses the rest of the native chain;
+   * the listener is an effect on this service's fiber and is removed with it or
+   * with the disposer {@link control} returns.
+   *
+   * The bracket is deliberately NOT `async` at its outermost level. Cordis'
+   * `waterfall` returns the outermost listener's value *synchronously*, so an
+   * `async` bracket would turn the hook's return value into a Promise for every
+   * caller — breaking any hook whose result the caller consumes without
+   * awaiting (dsh's `llm/stream` returns an AsyncIterable, and wraps with
+   * "not async iterable"). While both phases are empty there is nothing to
+   * order, so the chain is handed straight through and the hook's return type
+   * is exactly what it was before control was taken.
+   */
+  protected install(hook: string, front: HookEntry[], back: HookEntry[]): () => void;
+  /**
+   * Register a participant into a controlled hook phase.
+   *
+   * @param hook - the controlled waterfall event name.
+   * @param phase - `front` to run ahead of the native chain, `back` to run behind it.
+   * @param entry - the participant, with optional `before`/`after` names and its `run` callback.
+   * @returns a disposer that unregisters this participant.
+   * @throws {HookControlError} when the hook has not been {@link control}led, or
+   * when it is declared in `syncReturnHooks` — there the participant would work
+   * but the host's return value would change type, which is the worse failure.
+   */
+  register<A extends readonly unknown[] = readonly unknown[]>(hook: string, phase: Phase, entry: HookEntry<A>): () => void;
+}
+//#endregion
+export { HookOrdering as n, HookOrderingConfig as r, HookEntry as t };
+//# sourceMappingURL=waterfall-_5HkptkS.d.ts.map

package/lib/waterfall-_5HkptkS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterfall-_5HkptkS.d.ts","names":[],"sources":["../src/waterfall.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA+DkD,UAnCjC,SAmCiC,CAAA,UAAA,SAAA,OAAA,EAAA,GAAA,SAAA,OAAA,EAAA,CAAA,SAnCoC,SAmCpC,CAAA;;0BAjCxB,aAAa;;;UAItB,kBAAA,SAA2B;;;;;;;;;;;;;;;;;;;mBAoBzB;;;;;;;;cASN,YAAA,SAAqB,iBAAiB;;;;;;;;;;;;mBAahC,kBAAiB;;;;;;;;;;;;;;;;yCAoBK,mBAAmB;;;;;;;;;;;;mFAgCjD,cACA,UAAU"}

package/lib/waterfall.d.ts

@@ -0,0 +1,5 @@
+import "./topo-sort-BZ1fFcTs.js";
+import "./dag-Bqx-sl71.js";
+import "./service-base-CCmIBwnB.js";
+import { n as HookOrdering, r as HookOrderingConfig, t as HookEntry } from "./waterfall-_5HkptkS.js";
+export { HookEntry, HookOrdering, HookOrdering as default, HookOrderingConfig };

package/lib/waterfall.js

@@ -0,0 +1,6 @@
+import "./dag-DVhoBjBG.js";
+import "./topo-sort-CfwYPY4U.js";
+import "./service-base-a5vKg62S.js";
+import { n as waterfall_default, t as HookOrdering } from "./waterfall-Bu6m9gYc.js";
+
+export { HookOrdering, waterfall_default as default };