@zfdx123/dsh-hooks-ordering 1.0.1

package/lib/dag-Bqx-sl71.d.ts

@@ -0,0 +1,55 @@
+import { n as Orderable } from "./topo-sort-BZ1fFcTs.js";
+
+//#region src/dag.d.ts
+
+/** One `(hook, phase)` slice of the constraint graph to render. */
+interface DagSection {
+  /** The controlled hook event name. */
+  readonly hook: string;
+  /** The phase within the hook (e.g. `front`/`back`). */
+  readonly phase: string;
+  /** The participants and their `before`/`after` constraints. */
+  readonly entries: readonly Orderable[];
+}
+/** A directed ordering relation: `from` runs before `to`. */
+interface DagEdge {
+  /** The participant that runs first. */
+  readonly from: string;
+  /** The participant that runs after `from`. */
+  readonly to: string;
+}
+/** The constraint graph of one `(hook, phase)` slice. */
+interface DagSectionGraph {
+  /** The controlled hook event name. */
+  readonly hook: string;
+  /** The phase within the hook. */
+  readonly phase: string;
+  /** Every participant name, including ones with no constraint edges. */
+  readonly nodes: readonly string[];
+  /** The ordering relations; `from` runs before `to`. Deduplicated. */
+  readonly edges: readonly DagEdge[];
+}
+/** The whole constraint graph: one entry per controlled `(hook, phase)`. */
+interface Dag {
+  readonly sections: readonly DagSectionGraph[];
+}
+/**
+ * Build the constraint graph of the given sections as a plain object suitable
+ * for `JSON.stringify`.
+ *
+ * Each section becomes a {@link DagSectionGraph}: `nodes` lists every entry
+ * name (constraint-free entries included), and `edges` carries the ordering
+ * relations. An edge `from -> to` reads "from runs before to": an entry's
+ * `before` target yields `{ from: entry, to: target }`, and its `after` source
+ * yields `{ from: source, to: entry }`. A reference whose peer is absent from
+ * the section imposes no edge — mirroring {@link topoSort}'s unknown-target
+ * no-op — and a relation stated from both ends (e.g. `A.before: ['B']` and
+ * `B.after: ['A']`) appears once.
+ *
+ * @param sections - the `(hook, phase)` slices to render, in output order.
+ * @returns the graph object; an empty input yields `{ sections: [] }`.
+ */
+declare function buildDag(sections: readonly DagSection[]): Dag;
+//#endregion
+export { buildDag as a, DagSectionGraph as i, DagEdge as n, DagSection as r, Dag as t };
+//# sourceMappingURL=dag-Bqx-sl71.d.ts.map

package/lib/dag-Bqx-sl71.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-Bqx-sl71.d.ts","names":[],"sources":["../src/dag.ts"],"sourcesContent":[],"mappings":";;;;;UAYiB,UAAA;;;;;;6BAMY;;;UAIZ,OAAA;;;;;;;UAQA,eAAA;;;;;;;;2BAQU;;;UAIV,GAAA;8BACa;;;;;;;;;;;;;;;;;;iBAmBd,QAAA,oBAA4B,eAAe"}

package/lib/dag-DVhoBjBG.js

@@ -0,0 +1,48 @@
+//#region src/dag.ts
+/**
+* Build the constraint graph of the given sections as a plain object suitable
+* for `JSON.stringify`.
+*
+* Each section becomes a {@link DagSectionGraph}: `nodes` lists every entry
+* name (constraint-free entries included), and `edges` carries the ordering
+* relations. An edge `from -> to` reads "from runs before to": an entry's
+* `before` target yields `{ from: entry, to: target }`, and its `after` source
+* yields `{ from: source, to: entry }`. A reference whose peer is absent from
+* the section imposes no edge — mirroring {@link topoSort}'s unknown-target
+* no-op — and a relation stated from both ends (e.g. `A.before: ['B']` and
+* `B.after: ['A']`) appears once.
+*
+* @param sections - the `(hook, phase)` slices to render, in output order.
+* @returns the graph object; an empty input yields `{ sections: [] }`.
+*/
+function buildDag(sections) {
+	return { sections: sections.map((section) => {
+		const present = new Set(section.entries.map((entry) => entry.name));
+		const seen = /* @__PURE__ */ new Set();
+		const edges = [];
+		const addEdge = (from, to) => {
+			if (!present.has(from) || !present.has(to) || from === to) return;
+			const key = `${from} -> ${to}`;
+			if (seen.has(key)) return;
+			seen.add(key);
+			edges.push({
+				from,
+				to
+			});
+		};
+		for (const entry of section.entries) {
+			for (const target of entry.before ?? []) addEdge(entry.name, target);
+			for (const source of entry.after ?? []) addEdge(source, entry.name);
+		}
+		return {
+			hook: section.hook,
+			phase: section.phase,
+			nodes: section.entries.map((entry) => entry.name),
+			edges
+		};
+	}) };
+}
+
+//#endregion
+export { buildDag as t };
+//# sourceMappingURL=dag-DVhoBjBG.js.map

package/lib/dag-DVhoBjBG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-DVhoBjBG.js","names":["edges: DagEdge[]"],"sources":["../src/dag.ts"],"sourcesContent":["/**\n * JSON rendering of the `before`/`after` constraint graph across controlled\n * hook phases. Pure and dependency-free: the output is a function of the input\n * sections alone. Deliberately NOT a topological sort — a cycle is represented\n * faithfully rather than throwing, because the graph is most useful precisely\n * when the constraints conflict and `topoSort` would fail.\n * @module dsh-hooks-ordering/dag\n */\n\nimport type { Orderable } from './topo-sort.ts'\n\n/** One `(hook, phase)` slice of the constraint graph to render. */\nexport interface DagSection {\n  /** The controlled hook event name. */\n  readonly hook: string\n  /** The phase within the hook (e.g. `front`/`back`). */\n  readonly phase: string\n  /** The participants and their `before`/`after` constraints. */\n  readonly entries: readonly Orderable[]\n}\n\n/** A directed ordering relation: `from` runs before `to`. */\nexport interface DagEdge {\n  /** The participant that runs first. */\n  readonly from: string\n  /** The participant that runs after `from`. */\n  readonly to: string\n}\n\n/** The constraint graph of one `(hook, phase)` slice. */\nexport interface DagSectionGraph {\n  /** The controlled hook event name. */\n  readonly hook: string\n  /** The phase within the hook. */\n  readonly phase: string\n  /** Every participant name, including ones with no constraint edges. */\n  readonly nodes: readonly string[]\n  /** The ordering relations; `from` runs before `to`. Deduplicated. */\n  readonly edges: readonly DagEdge[]\n}\n\n/** The whole constraint graph: one entry per controlled `(hook, phase)`. */\nexport interface Dag {\n  readonly sections: readonly DagSectionGraph[]\n}\n\n/**\n * Build the constraint graph of the given sections as a plain object suitable\n * for `JSON.stringify`.\n *\n * Each section becomes a {@link DagSectionGraph}: `nodes` lists every entry\n * name (constraint-free entries included), and `edges` carries the ordering\n * relations. An edge `from -> to` reads \"from runs before to\": an entry's\n * `before` target yields `{ from: entry, to: target }`, and its `after` source\n * yields `{ from: source, to: entry }`. A reference whose peer is absent from\n * the section imposes no edge — mirroring {@link topoSort}'s unknown-target\n * no-op — and a relation stated from both ends (e.g. `A.before: ['B']` and\n * `B.after: ['A']`) appears once.\n *\n * @param sections - the `(hook, phase)` slices to render, in output order.\n * @returns the graph object; an empty input yields `{ sections: [] }`.\n */\nexport function buildDag(sections: readonly DagSection[]): Dag {\n  return {\n    sections: sections.map((section) => {\n      const present = new Set(section.entries.map((entry) => entry.name))\n      // Collect edges keyed by \"from->to\" to drop the same relation stated from\n      // both ends, preserving first-seen order.\n      const seen = new Set<string>()\n      const edges: DagEdge[] = []\n      const addEdge = (from: string, to: string): void => {\n        // Unknown endpoint: the referenced peer is not in this section, so\n        // there is no relation to record; a self-reference is likewise a no-op.\n        if (!present.has(from) || !present.has(to) || from === to) return\n        const key = `${from} -> ${to}`\n        if (seen.has(key)) return\n        seen.add(key)\n        edges.push({ from, to })\n      }\n      for (const entry of section.entries) {\n        for (const target of entry.before ?? []) addEdge(entry.name, target)\n        for (const source of entry.after ?? []) addEdge(source, entry.name)\n      }\n      return {\n        hook: section.hook,\n        phase: section.phase,\n        nodes: section.entries.map((entry) => entry.name),\n        edges,\n      }\n    }),\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA8DA,SAAgB,SAAS,UAAsC;AAC7D,QAAO,EACL,UAAU,SAAS,KAAK,YAAY;EAClC,MAAM,UAAU,IAAI,IAAI,QAAQ,QAAQ,KAAK,UAAU,MAAM,KAAK,CAAC;EAGnE,MAAM,uBAAO,IAAI,KAAa;EAC9B,MAAMA,QAAmB,EAAE;EAC3B,MAAM,WAAW,MAAc,OAAqB;AAGlD,OAAI,CAAC,QAAQ,IAAI,KAAK,IAAI,CAAC,QAAQ,IAAI,GAAG,IAAI,SAAS,GAAI;GAC3D,MAAM,MAAM,GAAG,KAAK,MAAM;AAC1B,OAAI,KAAK,IAAI,IAAI,CAAE;AACnB,QAAK,IAAI,IAAI;AACb,SAAM,KAAK;IAAE;IAAM;IAAI,CAAC;;AAE1B,OAAK,MAAM,SAAS,QAAQ,SAAS;AACnC,QAAK,MAAM,UAAU,MAAM,UAAU,EAAE,CAAE,SAAQ,MAAM,MAAM,OAAO;AACpE,QAAK,MAAM,UAAU,MAAM,SAAS,EAAE,CAAE,SAAQ,QAAQ,MAAM,KAAK;;AAErE,SAAO;GACL,MAAM,QAAQ;GACd,OAAO,QAAQ;GACf,OAAO,QAAQ,QAAQ,KAAK,UAAU,MAAM,KAAK;GACjD;GACD;GACD,EACH"}

package/lib/dag.d.ts

@@ -0,0 +1,3 @@
+import "./topo-sort-BZ1fFcTs.js";
+import { a as buildDag, i as DagSectionGraph, n as DagEdge, r as DagSection, t as Dag } from "./dag-Bqx-sl71.js";
+export { Dag, DagEdge, DagSection, DagSectionGraph, buildDag };

package/lib/dag.js

@@ -0,0 +1,3 @@
+import { t as buildDag } from "./dag-DVhoBjBG.js";
+
+export { buildDag };

package/lib/index.d.ts

@@ -0,0 +1,121 @@
+import { i as topoSort, n as Orderable, r as OrderingCycleError, t as DuplicateNameError } from "./topo-sort-BZ1fFcTs.js";
+import { a as buildDag, i as DagSectionGraph, n as DagEdge, r as DagSection, t as Dag } from "./dag-Bqx-sl71.js";
+import { a as Phase, i as HookOrderingLogConfig, n as HookControlError } from "./service-base-CCmIBwnB.js";
+import { n as HookOrdering, r as HookOrderingConfig, t as HookEntry } from "./waterfall-_5HkptkS.js";
+import { n as SerialHookOrdering, r as SerialHookOrderingConfig, t as SerialHookEntry } from "./serial-D8ZJCBKL.js";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/dsh.d.ts
+
+/** Cordis plugin name used by loader diagnostics. */
+declare const name = "hooks-ordering";
+/**
+ * `settings` is a **hard** dependency, and it has to be declared rather than
+ * probed.
+ *
+ * cordis activates a plugin as soon as the services it declares exist, and
+ * `ctx.get('settings')` reads the service store *without* creating that
+ * requirement. Without this line the dsh layer loads in the first wave — before
+ * the host has provided `settings` — the probe returns `undefined`, and the
+ * settings namespace is never registered. Silently: no form, no error.
+ *
+ * Declaring it makes cordis wait, which also lands this plugin's prepended
+ * brackets later in the boot, exactly where the ordering guarantee wants them.
+ *
+ * This entry targets dsh only — the hook names below are dsh's, and dsh always
+ * provides `settings`, so the dependency costs nothing here. `/waterfall` and
+ * `/serial` are the entries that carry no host-service requirement.
+ */
+declare const inject: string[];
+/**
+ * The dsh waterfall hooks this plugin controls by default — the ones multiple
+ * independent packages contribute to, where relative order matters. Controlling
+ * a hook with no registered participants is a no-op pass-through.
+ *
+ * Every name here was checked against the events dsh actually declares: each is
+ * a `@mode waterfall` event in the installed build, and each is dispatched with
+ * `await`, so the caller already handles a Promise and the bracket's async
+ * phases cannot change the hook's return type. `tools/code-dispatch-log` used
+ * to sit in this list and no dsh package declares it at all — controlling a
+ * name nothing dispatches "succeeds" and then does nothing forever, which is
+ * exactly the dead configuration this list must not carry.
+ *
+ * The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose
+ * value the caller consumes without awaiting cannot carry ordered participants,
+ * so controlling it by default would install a bracket nothing may ever
+ * register into — the same dead configuration by a different route.
+ */
+declare const DEFAULT_WATERFALL_HOOKS: readonly string[];
+/**
+ * dsh hooks whose dispatch return value is consumed by the caller without
+ * awaiting, and which therefore cannot carry ordered participants. Verified
+ * against the installed build:
+ *
+ * - `llm/stream` — `dsh-llm` dispatches it as
+ *   `return this.ctx.waterfall(this, "llm/stream", options, …)` (no await), and
+ *   `dsh-session-title-llm` iterates the result with
+ *   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws
+ *   "not async iterable". It is a genuine multi-contributor hook (dsh-agent-loop,
+ *   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),
+ *   so it is a real loss — but ordering it requires dsh to await the dispatch,
+ *   not a plugin-side workaround.
+ * - `session-telemetry/record` — `dsh-session-telemetry` returns the record
+ *   straight out of the waterfall and hands it to the backend, so a Promise
+ *   would be emitted as a record: silent corruption, no error anywhere.
+ * - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as
+ *   `recover: (…) => this.ctx.waterfall(this, "compaction/summary-error", …, () => false)`
+ *   (no await) and consumes the boolean synchronously in
+ *   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.
+ *   A Promise is always truthy, so `!recover(…)` is always false and every
+ *   summarizer failure is swallowed instead of rethrown — the compaction then
+ *   proceeds as if recovery had succeeded.
+ *
+ * Override per profile with `syncReturnHooks` once the host awaits one of them.
+ */
+declare const DEFAULT_SYNC_RETURN_HOOKS: readonly string[];
+/** The dsh serial hook controlled by default. */
+declare const DEFAULT_SERIAL_HOOKS: readonly string[];
+/** Plugin config. */
+interface Config {
+  /**
+   * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.
+   * Pass `[]` to disable the waterfall service entirely.
+   */
+  hooks?: readonly string[];
+  /**
+   * Serial hooks to control. Defaults to {@link DEFAULT_SERIAL_HOOKS}.
+   * Pass `[]` to disable the serial service entirely.
+   */
+  serialHooks?: readonly string[];
+  /**
+   * Hooks whose return value the host consumes without awaiting, and which must
+   * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.
+   * Pass `[]` — or a set without a given hook — to opt in to ordering it, once
+   * the host awaits that dispatch.
+   */
+  syncReturnHooks?: readonly string[];
+  /** When set, the constraint DAG (JSON) is logged to this file on every change. */
+  log?: string;
+}
+/**
+ * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the
+ * configured hooks once the services are active.
+ *
+ * `config` may be `null`, and that is the ordinary case rather than an edge
+ * case: a loader row whose `config:` key is followed only by comments parses as
+ * YAML null, and a default parameter covers `undefined` but not `null`. This
+ * package's own `cordis.patch.yml` is written exactly that way — every option
+ * commented out — so a null config must mean "all defaults", not a crash.
+ *
+ * The row is the *composition* layer of the settings namespace: the Settings
+ * page edits a user layer over it, and a namespace the user has not touched
+ * resolves back to this row (or to the built-in defaults). Without a settings
+ * provider — plain Cordis — the row is the whole answer.
+ *
+ * @param ctx - the Cordis context.
+ * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
+ */
+declare function apply(ctx: Context, config?: Config | null): void;
+//#endregion
+export { type Config, DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, type Dag, type DagEdge, type DagSection, type DagSectionGraph, DuplicateNameError, HookControlError, type HookEntry, HookOrdering, type HookOrderingConfig, type HookOrderingLogConfig, type Orderable, OrderingCycleError, type Phase, type SerialHookEntry, SerialHookOrdering, type SerialHookOrderingConfig, apply, buildDag, inject, name, topoSort };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/dsh.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAuBa,IAAA;;;;;;;;;;;;;;;;;;cAmBA;;;;;;;;;;;;;;;;;;;cAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuCA;;cAOA;;UAGI,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCD,KAAA,MAAW,kBAAiB"}

package/lib/index.js

@@ -0,0 +1,190 @@
+import { t as buildDag } from "./dag-DVhoBjBG.js";
+import { n as OrderingCycleError, r as topoSort, t as DuplicateNameError } from "./topo-sort-CfwYPY4U.js";
+import { t as HookControlError } from "./service-base-a5vKg62S.js";
+import { n as waterfall_default, t as HookOrdering } from "./waterfall-Bu6m9gYc.js";
+import { t as SerialHookOrdering } from "./serial-Cu7usHjI.js";
+import Schema from "@deepseek-ai/schemastery";
+
+//#region src/settings.ts
+/** Namespace name — dsh requires a lowercase hyphenated identifier. */
+const SETTINGS_NS = "hooks-ordering";
+/**
+* Schema for {@link SETTINGS_NS}.
+*
+* Every field defaults to its "off" value. The *meaningful* defaults — the
+* hooks this plugin controls when nothing overrides them — are supplied by the
+* caller as the composition `base` layer (see {@link resolveSettings}), so a
+* namespace the user has never touched still resolves to a complete object.
+*/
+const HooksOrderingSettingsSchema = Schema.object({
+	hooks: Schema.array(Schema.string()).default([]),
+	serialHooks: Schema.array(Schema.string()).default([]),
+	log: Schema.string().default("")
+});
+/**
+* Register the settings namespace and read its resolved value.
+*
+* `base` is the composition layer — what the row (or the built-in defaults)
+* asks for — so the user layer edits *over* it and a reset returns to it rather
+* than to an empty form.
+*
+* `applies: 'restart'` is deliberate. Changing `hooks`/`serialHooks` means
+* installing or removing bracket listeners on live hooks, and the coordinator
+* has no public "release one hook" operation; a restart applies the change
+* cleanly instead of re-wiring the dispatch chain mid-flight.
+*
+* @param ctx - the Cordis context to look the service up on.
+* @param base - the composition layer to register as the base value.
+* @returns the resolved settings, or `undefined` when the provider is missing
+* (which `inject: ['settings']` rules out in dsh — the guard is defensive) or
+* registration failed — the caller then uses `base`.
+*/
+function resolveSettings(ctx, base) {
+	const settings = ctx.get("settings");
+	if (settings === void 0) return void 0;
+	try {
+		return settings.register(SETTINGS_NS, HooksOrderingSettingsSchema, {
+			base,
+			applies: "restart"
+		}).get();
+	} catch (error) {
+		console.warn("hooks-ordering: settings registration failed; falling back to the composition config:", error);
+		return;
+	}
+}
+
+//#endregion
+//#region src/dsh.ts
+/** Cordis plugin name used by loader diagnostics. */
+const name = "hooks-ordering";
+/**
+* `settings` is a **hard** dependency, and it has to be declared rather than
+* probed.
+*
+* cordis activates a plugin as soon as the services it declares exist, and
+* `ctx.get('settings')` reads the service store *without* creating that
+* requirement. Without this line the dsh layer loads in the first wave — before
+* the host has provided `settings` — the probe returns `undefined`, and the
+* settings namespace is never registered. Silently: no form, no error.
+*
+* Declaring it makes cordis wait, which also lands this plugin's prepended
+* brackets later in the boot, exactly where the ordering guarantee wants them.
+*
+* This entry targets dsh only — the hook names below are dsh's, and dsh always
+* provides `settings`, so the dependency costs nothing here. `/waterfall` and
+* `/serial` are the entries that carry no host-service requirement.
+*/
+const inject = ["settings"];
+/**
+* The dsh waterfall hooks this plugin controls by default — the ones multiple
+* independent packages contribute to, where relative order matters. Controlling
+* a hook with no registered participants is a no-op pass-through.
+*
+* Every name here was checked against the events dsh actually declares: each is
+* a `@mode waterfall` event in the installed build, and each is dispatched with
+* `await`, so the caller already handles a Promise and the bracket's async
+* phases cannot change the hook's return type. `tools/code-dispatch-log` used
+* to sit in this list and no dsh package declares it at all — controlling a
+* name nothing dispatches "succeeds" and then does nothing forever, which is
+* exactly the dead configuration this list must not carry.
+*
+* The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose
+* value the caller consumes without awaiting cannot carry ordered participants,
+* so controlling it by default would install a bracket nothing may ever
+* register into — the same dead configuration by a different route.
+*/
+const DEFAULT_WATERFALL_HOOKS = [
+	"agent/pre-step",
+	"agent/request",
+	"agent/request-error",
+	"system-prompt/assemble",
+	"tools/pre-execute",
+	"tools/execute",
+	"tools/post-execute",
+	"fs/write-intent",
+	"fs/edit-intent",
+	"approval/request"
+];
+/**
+* dsh hooks whose dispatch return value is consumed by the caller without
+* awaiting, and which therefore cannot carry ordered participants. Verified
+* against the installed build:
+*
+* - `llm/stream` — `dsh-llm` dispatches it as
+*   `return this.ctx.waterfall(this, "llm/stream", options, …)` (no await), and
+*   `dsh-session-title-llm` iterates the result with
+*   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws
+*   "not async iterable". It is a genuine multi-contributor hook (dsh-agent-loop,
+*   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),
+*   so it is a real loss — but ordering it requires dsh to await the dispatch,
+*   not a plugin-side workaround.
+* - `session-telemetry/record` — `dsh-session-telemetry` returns the record
+*   straight out of the waterfall and hands it to the backend, so a Promise
+*   would be emitted as a record: silent corruption, no error anywhere.
+* - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as
+*   `recover: (…) => this.ctx.waterfall(this, "compaction/summary-error", …, () => false)`
+*   (no await) and consumes the boolean synchronously in
+*   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.
+*   A Promise is always truthy, so `!recover(…)` is always false and every
+*   summarizer failure is swallowed instead of rethrown — the compaction then
+*   proceeds as if recovery had succeeded.
+*
+* Override per profile with `syncReturnHooks` once the host awaits one of them.
+*/
+const DEFAULT_SYNC_RETURN_HOOKS = [
+	"llm/stream",
+	"session-telemetry/record",
+	"compaction/summary-error"
+];
+/** The dsh serial hook controlled by default. */
+const DEFAULT_SERIAL_HOOKS = ["agent/turn-stopping"];
+/**
+* Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the
+* configured hooks once the services are active.
+*
+* `config` may be `null`, and that is the ordinary case rather than an edge
+* case: a loader row whose `config:` key is followed only by comments parses as
+* YAML null, and a default parameter covers `undefined` but not `null`. This
+* package's own `cordis.patch.yml` is written exactly that way — every option
+* commented out — so a null config must mean "all defaults", not a crash.
+*
+* The row is the *composition* layer of the settings namespace: the Settings
+* page edits a user layer over it, and a namespace the user has not touched
+* resolves back to this row (or to the built-in defaults). Without a settings
+* provider — plain Cordis — the row is the whole answer.
+*
+* @param ctx - the Cordis context.
+* @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
+*/
+function apply(ctx, config = {}) {
+	const row = config ?? {};
+	const base = {
+		hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,
+		serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,
+		log: row.log ?? ""
+	};
+	const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base;
+	const serviceConfig = log === "" ? {} : { log };
+	const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS;
+	const deps = [];
+	if (hooks.length > 0) {
+		ctx.plugin(waterfall_default, {
+			...serviceConfig,
+			syncReturnHooks
+		});
+		deps.push("hooksOrdering");
+	}
+	if (serialHooks.length > 0) {
+		ctx.plugin(SerialHookOrdering, serviceConfig);
+		deps.push("serialHooksOrdering");
+	}
+	if (deps.length === 0) return;
+	ctx.inject(deps, (ready) => {
+		for (const hook of hooks) ready.hooksOrdering.control(hook);
+		for (const hook of serialHooks) ready.serialHooksOrdering.control(hook);
+	});
+}
+
+//#endregion
+export { DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, DuplicateNameError, HookControlError, HookOrdering, OrderingCycleError, SerialHookOrdering, apply, buildDag, inject, name, topoSort };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DEFAULT_WATERFALL_HOOKS: readonly string[]","DEFAULT_SYNC_RETURN_HOOKS: readonly string[]","DEFAULT_SERIAL_HOOKS: readonly string[]","base: HooksOrderingSettings","deps: string[]","HookOrdering"],"sources":["../src/settings.ts","../src/dsh.ts"],"sourcesContent":["/**\n * The dsh settings namespace for this plugin: the three fields a user can edit\n * from the Settings page instead of a `cordis.patch.yml` row.\n *\n * Two constraints are load-bearing and easy to get wrong:\n *\n * - The schema handed to `settings.register` must be a **callable** schemastery\n *   schema. dsh resolves a namespace by calling `schema(merged)` and reads\n *   `schema.toJSON()` for the form, so a plain object throws\n *   `schema is not a function` — during plugin assembly, which takes the whole\n *   profile down rather than failing one form.\n * - That is also why registration is wrapped in `try/catch` here: an optional\n *   settings form must never be able to stop the harness from booting.\n *\n * @module dsh-hooks-ordering/settings\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport Schema from '@deepseek-ai/schemastery'\n\n/** The three fields this plugin exposes for configuration. */\nexport interface HooksOrderingSettings {\n  /** Waterfall hooks to control; `[]` disables the waterfall service entirely. */\n  readonly hooks: readonly string[]\n  /** Serial hooks to control; `[]` disables the serial service entirely. */\n  readonly serialHooks: readonly string[]\n  /** Constraint-DAG log file; the empty string means \"do not log\". */\n  readonly log: string\n}\n\n/** Namespace name — dsh requires a lowercase hyphenated identifier. */\nexport const SETTINGS_NS = 'hooks-ordering'\n\n/**\n * Schema for {@link SETTINGS_NS}.\n *\n * Every field defaults to its \"off\" value. The *meaningful* defaults — the\n * hooks this plugin controls when nothing overrides them — are supplied by the\n * caller as the composition `base` layer (see {@link resolveSettings}), so a\n * namespace the user has never touched still resolves to a complete object.\n */\nexport const HooksOrderingSettingsSchema = Schema.object({\n  hooks: Schema.array(Schema.string()).default([]),\n  serialHooks: Schema.array(Schema.string()).default([]),\n  log: Schema.string().default(''),\n})\n\n/**\n * The slice of dsh's `settings` service this plugin uses.\n *\n * Structural rather than imported from `@deepseek-ai/dsh-settings`: it describes\n * exactly the contract this plugin relies on without adding a build-time\n * dependency on a dsh package, whose internals are still 0.1.x-rc.\n */\nexport interface SettingsServiceLike {\n  /**\n   * @param ns - the namespace to register; must be a lowercase hyphenated identifier.\n   * @param schema - a callable schemastery schema, not a plain object.\n   * @param options - `base` is the composition layer, `applies` says whether an\n   * edit takes effect live or needs a restart.\n   * @returns a scope whose `get()` is the resolved value (schema defaults, then `base`, then the user layer).\n   */\n  register(\n    ns: string,\n    schema: unknown,\n    options?: { readonly base?: unknown; readonly applies?: 'live' | 'restart' },\n  ): { get(): HooksOrderingSettings }\n}\n\n/**\n * Register the settings namespace and read its resolved value.\n *\n * `base` is the composition layer — what the row (or the built-in defaults)\n * asks for — so the user layer edits *over* it and a reset returns to it rather\n * than to an empty form.\n *\n * `applies: 'restart'` is deliberate. Changing `hooks`/`serialHooks` means\n * installing or removing bracket listeners on live hooks, and the coordinator\n * has no public \"release one hook\" operation; a restart applies the change\n * cleanly instead of re-wiring the dispatch chain mid-flight.\n *\n * @param ctx - the Cordis context to look the service up on.\n * @param base - the composition layer to register as the base value.\n * @returns the resolved settings, or `undefined` when the provider is missing\n * (which `inject: ['settings']` rules out in dsh — the guard is defensive) or\n * registration failed — the caller then uses `base`.\n */\nexport function resolveSettings(ctx: Context, base: HooksOrderingSettings): HooksOrderingSettings | undefined {\n  const settings = ctx.get('settings') as SettingsServiceLike | undefined\n  if (settings === undefined) return undefined\n  try {\n    return settings.register(SETTINGS_NS, HooksOrderingSettingsSchema, { base, applies: 'restart' }).get()\n  } catch (error) {\n    console.warn('hooks-ordering: settings registration failed; falling back to the composition config:', error)\n    return undefined\n  }\n}\n","/**\n * The DeepSeek-Harness layer: a dsh plugin that mounts the ordering services\n * and takes control of the real dsh hooks that multiple independent packages\n * contribute to, so a profile can opt into deterministic ordering with one row.\n *\n * dsh (deepseek-harness) ships waterfall hooks such as `agent/pre-step`\n * (subscribed by a dozen+ independent packages), `tools/post-execute`,\n * `llm/stream`, and `system-prompt/assemble`, plus the serial hook\n * `agent/turn-stopping`. Their relative listener order is load-bearing yet\n * today decided only by binary `prepend` and registration timing. This plugin\n * controls those hooks up front; controlling an empty hook is a transparent\n * pass-through, so nothing changes until participants register with\n * `before`/`after`.\n *\n * @module dsh-hooks-ordering/dsh\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport HookOrdering from './waterfall.ts'\nimport { SerialHookOrdering } from './serial.ts'\nimport { type HooksOrderingSettings, resolveSettings } from './settings.ts'\n\n/** Cordis plugin name used by loader diagnostics. */\nexport const name = 'hooks-ordering'\n\n/**\n * `settings` is a **hard** dependency, and it has to be declared rather than\n * probed.\n *\n * cordis activates a plugin as soon as the services it declares exist, and\n * `ctx.get('settings')` reads the service store *without* creating that\n * requirement. Without this line the dsh layer loads in the first wave — before\n * the host has provided `settings` — the probe returns `undefined`, and the\n * settings namespace is never registered. Silently: no form, no error.\n *\n * Declaring it makes cordis wait, which also lands this plugin's prepended\n * brackets later in the boot, exactly where the ordering guarantee wants them.\n *\n * This entry targets dsh only — the hook names below are dsh's, and dsh always\n * provides `settings`, so the dependency costs nothing here. `/waterfall` and\n * `/serial` are the entries that carry no host-service requirement.\n */\nexport const inject = ['settings']\n\n/**\n * The dsh waterfall hooks this plugin controls by default — the ones multiple\n * independent packages contribute to, where relative order matters. Controlling\n * a hook with no registered participants is a no-op pass-through.\n *\n * Every name here was checked against the events dsh actually declares: each is\n * a `@mode waterfall` event in the installed build, and each is dispatched with\n * `await`, so the caller already handles a Promise and the bracket's async\n * phases cannot change the hook's return type. `tools/code-dispatch-log` used\n * to sit in this list and no dsh package declares it at all — controlling a\n * name nothing dispatches \"succeeds\" and then does nothing forever, which is\n * exactly the dead configuration this list must not carry.\n *\n * The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose\n * value the caller consumes without awaiting cannot carry ordered participants,\n * so controlling it by default would install a bracket nothing may ever\n * register into — the same dead configuration by a different route.\n */\nexport const DEFAULT_WATERFALL_HOOKS: readonly string[] = [\n  'agent/pre-step',\n  'agent/request',\n  'agent/request-error',\n  'system-prompt/assemble',\n  'tools/pre-execute',\n  'tools/execute',\n  'tools/post-execute',\n  'fs/write-intent',\n  'fs/edit-intent',\n  'approval/request',\n]\n\n/**\n * dsh hooks whose dispatch return value is consumed by the caller without\n * awaiting, and which therefore cannot carry ordered participants. Verified\n * against the installed build:\n *\n * - `llm/stream` — `dsh-llm` dispatches it as\n *   `return this.ctx.waterfall(this, \"llm/stream\", options, …)` (no await), and\n *   `dsh-session-title-llm` iterates the result with\n *   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws\n *   \"not async iterable\". It is a genuine multi-contributor hook (dsh-agent-loop,\n *   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),\n *   so it is a real loss — but ordering it requires dsh to await the dispatch,\n *   not a plugin-side workaround.\n * - `session-telemetry/record` — `dsh-session-telemetry` returns the record\n *   straight out of the waterfall and hands it to the backend, so a Promise\n *   would be emitted as a record: silent corruption, no error anywhere.\n * - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as\n *   `recover: (…) => this.ctx.waterfall(this, \"compaction/summary-error\", …, () => false)`\n *   (no await) and consumes the boolean synchronously in\n *   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.\n *   A Promise is always truthy, so `!recover(…)` is always false and every\n *   summarizer failure is swallowed instead of rethrown — the compaction then\n *   proceeds as if recovery had succeeded.\n *\n * Override per profile with `syncReturnHooks` once the host awaits one of them.\n */\nexport const DEFAULT_SYNC_RETURN_HOOKS: readonly string[] = [\n  'llm/stream',\n  'session-telemetry/record',\n  'compaction/summary-error',\n]\n\n/** The dsh serial hook controlled by default. */\nexport const DEFAULT_SERIAL_HOOKS: readonly string[] = ['agent/turn-stopping']\n\n/** Plugin config. */\nexport interface Config {\n  /**\n   * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.\n   * Pass `[]` to disable the waterfall service entirely.\n   */\n  hooks?: readonly string[]\n  /**\n   * Serial hooks to control. Defaults to {@link DEFAULT_SERIAL_HOOKS}.\n   * Pass `[]` to disable the serial service entirely.\n   */\n  serialHooks?: readonly string[]\n  /**\n   * Hooks whose return value the host consumes without awaiting, and which must\n   * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.\n   * Pass `[]` — or a set without a given hook — to opt in to ordering it, once\n   * the host awaits that dispatch.\n   */\n  syncReturnHooks?: readonly string[]\n  /** When set, the constraint DAG (JSON) is logged to this file on every change. */\n  log?: string\n}\n\n/**\n * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the\n * configured hooks once the services are active.\n *\n * `config` may be `null`, and that is the ordinary case rather than an edge\n * case: a loader row whose `config:` key is followed only by comments parses as\n * YAML null, and a default parameter covers `undefined` but not `null`. This\n * package's own `cordis.patch.yml` is written exactly that way — every option\n * commented out — so a null config must mean \"all defaults\", not a crash.\n *\n * The row is the *composition* layer of the settings namespace: the Settings\n * page edits a user layer over it, and a namespace the user has not touched\n * resolves back to this row (or to the built-in defaults). Without a settings\n * provider — plain Cordis — the row is the whole answer.\n *\n * @param ctx - the Cordis context.\n * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.\n */\nexport function apply(ctx: Context, config: Config | null = {}): void {\n  const row = config ?? {}\n  const base: HooksOrderingSettings = {\n    hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,\n    serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,\n    log: row.log ?? '',\n  }\n  const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base\n  const serviceConfig = log === '' ? {} : { log }\n  // Not part of the settings namespace: the sync-return list describes the\n  // HOST's dispatch, not a user preference, so it is composition (row) only.\n  const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS\n\n  const deps: string[] = []\n  if (hooks.length > 0) {\n    ctx.plugin(HookOrdering, { ...serviceConfig, syncReturnHooks })\n    deps.push('hooksOrdering')\n  }\n  if (serialHooks.length > 0) {\n    ctx.plugin(SerialHookOrdering, serviceConfig)\n    deps.push('serialHooksOrdering')\n  }\n  if (deps.length === 0) return\n\n  // The services activate asynchronously; control the hooks once they exist.\n  ctx.inject(deps, (ready) => {\n    for (const hook of hooks) ready.hooksOrdering.control(hook)\n    for (const hook of serialHooks) ready.serialHooksOrdering.control(hook)\n  })\n}\n"],"mappings":";;;;;;;;;AA+BA,MAAa,cAAc;;;;;;;;;AAU3B,MAAa,8BAA8B,OAAO,OAAO;CACvD,OAAO,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;CAChD,aAAa,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;CACtD,KAAK,OAAO,QAAQ,CAAC,QAAQ,GAAG;CACjC,CAAC;;;;;;;;;;;;;;;;;;;AA0CF,SAAgB,gBAAgB,KAAc,MAAgE;CAC5G,MAAM,WAAW,IAAI,IAAI,WAAW;AACpC,KAAI,aAAa,OAAW,QAAO;AACnC,KAAI;AACF,SAAO,SAAS,SAAS,aAAa,6BAA6B;GAAE;GAAM,SAAS;GAAW,CAAC,CAAC,KAAK;UAC/F,OAAO;AACd,UAAQ,KAAK,yFAAyF,MAAM;AAC5G;;;;;;;ACvEJ,MAAa,OAAO;;;;;;;;;;;;;;;;;;AAmBpB,MAAa,SAAS,CAAC,WAAW;;;;;;;;;;;;;;;;;;;AAoBlC,MAAaA,0BAA6C;CACxD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BD,MAAaC,4BAA+C;CAC1D;CACA;CACA;CACD;;AAGD,MAAaC,uBAA0C,CAAC,sBAAsB;;;;;;;;;;;;;;;;;;;AA2C9E,SAAgB,MAAM,KAAc,SAAwB,EAAE,EAAQ;CACpE,MAAM,MAAM,UAAU,EAAE;CACxB,MAAMC,OAA8B;EAClC,OAAO,IAAI,SAAS;EACpB,aAAa,IAAI,eAAe;EAChC,KAAK,IAAI,OAAO;EACjB;CACD,MAAM,EAAE,OAAO,aAAa,QAAQ,gBAAgB,KAAK,KAAK,IAAI;CAClE,MAAM,gBAAgB,QAAQ,KAAK,EAAE,GAAG,EAAE,KAAK;CAG/C,MAAM,kBAAkB,IAAI,mBAAmB;CAE/C,MAAMC,OAAiB,EAAE;AACzB,KAAI,MAAM,SAAS,GAAG;AACpB,MAAI,OAAOC,mBAAc;GAAE,GAAG;GAAe;GAAiB,CAAC;AAC/D,OAAK,KAAK,gBAAgB;;AAE5B,KAAI,YAAY,SAAS,GAAG;AAC1B,MAAI,OAAO,oBAAoB,cAAc;AAC7C,OAAK,KAAK,sBAAsB;;AAElC,KAAI,KAAK,WAAW,EAAG;AAGvB,KAAI,OAAO,OAAO,UAAU;AAC1B,OAAK,MAAM,QAAQ,MAAO,OAAM,cAAc,QAAQ,KAAK;AAC3D,OAAK,MAAM,QAAQ,YAAa,OAAM,oBAAoB,QAAQ,KAAK;GACvE"}

package/lib/serial-Cu7usHjI.js

@@ -0,0 +1,65 @@
+import { r as topoSort } from "./topo-sort-CfwYPY4U.js";
+import { n as HookOrderingBase } from "./service-base-a5vKg62S.js";
+import { isBailed } from "@deepseek-ai/cordis";
+
+//#region src/serial.ts
+/**
+* Coordinator service registered at `ctx.serialHooksOrdering`. Controls any
+* number of serial hooks; each owns a prepended front coordinator, an appended
+* back coordinator, and two ordered participant lists.
+*/
+var SerialHookOrdering = class extends HookOrderingBase {
+	/**
+	* @param ctx - the Cordis context to register the service in.
+	* @param config - optional `log` file for the constraint DAG (JSON); `null` means defaults.
+	*/
+	constructor(ctx, config = {}) {
+		super(ctx, "serialHooksOrdering", config);
+	}
+	/**
+	* Install the two coordinator listeners. The front one is prepended so it
+	* runs ahead of the native chain; the back one is appended so it runs after
+	* the listeners present at control time. Both are effects on this service's
+	* fiber; the returned disposer removes both.
+	*/
+	install(hook, front, back) {
+		const frontCoordinator = (...args) => runSerialPhase(front, args);
+		const backCoordinator = (...args) => runSerialPhase(back, args);
+		const removeFront = this.ctx.on(hook, frontCoordinator, { prepend: true });
+		const removeBack = this.ctx.on(hook, backCoordinator, { prepend: false });
+		return () => {
+			removeFront();
+			removeBack();
+		};
+	}
+	/**
+	* Register a participant into a controlled hook phase.
+	*
+	* @param hook - the controlled serial event name.
+	* @param phase - `front` to run ahead of the native chain, `back` best-effort last.
+	* @param entry - the participant; its `run` may return a bail value to short-circuit.
+	* @returns a disposer that unregisters this participant.
+	* @throws {HookControlError} when the hook has not been {@link control}led.
+	*/
+	register(hook, phase, entry) {
+		return this.registerEntry(hook, phase, entry);
+	}
+};
+/**
+* Run one phase's participants in stable topological order, awaiting each,
+* until one bails.
+* @param entries - the phase's registered participants.
+* @param payload - the hook payload passed to each `run` callback.
+* @returns the first bail value, or `undefined` if no participant bailed (so
+* the serial dispatch continues to the next listener).
+*/
+async function runSerialPhase(entries, payload) {
+	for (const entry of topoSort(entries)) {
+		const result = await entry.run(...payload);
+		if (isBailed(result)) return result;
+	}
+}
+
+//#endregion
+export { SerialHookOrdering as t };
+//# sourceMappingURL=serial-Cu7usHjI.js.map

package/lib/serial-Cu7usHjI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-Cu7usHjI.js","names":[],"sources":["../src/serial.ts"],"sourcesContent":["/**\n * `SerialHookOrdering` — the serial-dispatch twin of {@link HookOrdering}.\n *\n * Cordis `serial` dispatch awaits listeners in registration order until one\n * *bails* (returns a value that is not `null`/`false`/`undefined`); the bail\n * value becomes the dispatch result and the remaining listeners never run.\n * There is no `next()` continuation, so unlike waterfall there is no onion to\n * wrap. This service instead brackets the hook with TWO coordinator listeners:\n *\n * - a `prepend`ed **front** coordinator that runs its participants ahead of\n *   every native listener; a bail there short-circuits the whole dispatch.\n * - an appended **back** coordinator that runs its participants best-effort\n *   last (see the limits below).\n *\n * Participants register into the coordinator (not the raw hook) with\n * `before`/`after` names and are run in a stable topological order.\n *\n * @module dsh-hooks-ordering/serial\n */\n\nimport { type Context, isBailed } from '@deepseek-ai/cordis'\nimport { 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 serial hook phase. Unlike the\n * waterfall entry, `run` may RETURN a value: a bail value (anything but\n * `null`/`false`/`undefined`) short-circuits the serial dispatch.\n * @typeParam A - the hook's payload argument tuple.\n */\nexport interface SerialHookEntry<A extends readonly unknown[] = readonly unknown[]> extends Orderable {\n  /** Run this participant with the hook payload. A bail return stops the chain. */\n  readonly run: (...args: A) => unknown | Promise<unknown>\n}\n\n/** Configuration for the {@link SerialHookOrdering} service. */\nexport type SerialHookOrderingConfig = HookOrderingLogConfig\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    serialHooksOrdering: SerialHookOrdering\n  }\n}\n\n/**\n * Coordinator service registered at `ctx.serialHooksOrdering`. Controls any\n * number of serial hooks; each owns a prepended front coordinator, an appended\n * back coordinator, and two ordered participant lists.\n */\nexport class SerialHookOrdering extends HookOrderingBase<SerialHookEntry> {\n  /**\n   * @param ctx - the Cordis context to register the service in.\n   * @param config - optional `log` file for the constraint DAG (JSON); `null` means defaults.\n   */\n  constructor(ctx: Context, config: SerialHookOrderingConfig | null = {}) {\n    super(ctx, 'serialHooksOrdering', config)\n  }\n\n  /**\n   * Install the two coordinator listeners. The front one is prepended so it\n   * runs ahead of the native chain; the back one is appended so it runs after\n   * the listeners present at control time. Both are effects on this service's\n   * fiber; the returned disposer removes both.\n   */\n  protected install(hook: string, front: SerialHookEntry[], back: SerialHookEntry[]): () => void {\n    const frontCoordinator = (...args: unknown[]): Promise<unknown> => runSerialPhase(front, args)\n    const backCoordinator = (...args: unknown[]): Promise<unknown> => runSerialPhase(back, args)\n    const removeFront = this.ctx.on(hook as never, frontCoordinator as never, { prepend: true })\n    const removeBack = this.ctx.on(hook as never, backCoordinator as never, { prepend: false })\n    return () => {\n      removeFront()\n      removeBack()\n    }\n  }\n\n  /**\n   * Register a participant into a controlled hook phase.\n   *\n   * @param hook - the controlled serial event name.\n   * @param phase - `front` to run ahead of the native chain, `back` best-effort last.\n   * @param entry - the participant; its `run` may return a bail value to short-circuit.\n   * @returns a disposer that unregisters this participant.\n   * @throws {HookControlError} when the hook has not been {@link control}led.\n   */\n  register<A extends readonly unknown[] = readonly unknown[]>(\n    hook: string,\n    phase: Phase,\n    entry: SerialHookEntry<A>,\n  ): () => void {\n    return this.registerEntry(hook, phase, entry as unknown as SerialHookEntry)\n  }\n}\n\n/**\n * Run one phase's participants in stable topological order, awaiting each,\n * until one bails.\n * @param entries - the phase's registered participants.\n * @param payload - the hook payload passed to each `run` callback.\n * @returns the first bail value, or `undefined` if no participant bailed (so\n * the serial dispatch continues to the next listener).\n */\nasync function runSerialPhase(entries: readonly SerialHookEntry[], payload: readonly unknown[]): Promise<unknown> {\n  for (const entry of topoSort(entries)) {\n    const result = await entry.run(...payload)\n    if (isBailed(result)) return result\n  }\n  return undefined\n}\n"],"mappings":";;;;;;;;;;AAiDA,IAAa,qBAAb,cAAwC,iBAAkC;;;;;CAKxE,YAAY,KAAc,SAA0C,EAAE,EAAE;AACtE,QAAM,KAAK,uBAAuB,OAAO;;;;;;;;CAS3C,AAAU,QAAQ,MAAc,OAA0B,MAAqC;EAC7F,MAAM,oBAAoB,GAAG,SAAsC,eAAe,OAAO,KAAK;EAC9F,MAAM,mBAAmB,GAAG,SAAsC,eAAe,MAAM,KAAK;EAC5F,MAAM,cAAc,KAAK,IAAI,GAAG,MAAe,kBAA2B,EAAE,SAAS,MAAM,CAAC;EAC5F,MAAM,aAAa,KAAK,IAAI,GAAG,MAAe,iBAA0B,EAAE,SAAS,OAAO,CAAC;AAC3F,eAAa;AACX,gBAAa;AACb,eAAY;;;;;;;;;;;;CAahB,SACE,MACA,OACA,OACY;AACZ,SAAO,KAAK,cAAc,MAAM,OAAO,MAAoC;;;;;;;;;;;AAY/E,eAAe,eAAe,SAAqC,SAA+C;AAChH,MAAK,MAAM,SAAS,SAAS,QAAQ,EAAE;EACrC,MAAM,SAAS,MAAM,MAAM,IAAI,GAAG,QAAQ;AAC1C,MAAI,SAAS,OAAO,CAAE,QAAO"}

package/lib/serial-D8ZJCBKL.d.ts

@@ -0,0 +1,55 @@
+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/serial.d.ts
+
+/**
+ * One ordered participant in a controlled serial hook phase. Unlike the
+ * waterfall entry, `run` may RETURN a value: a bail value (anything but
+ * `null`/`false`/`undefined`) short-circuits the serial dispatch.
+ * @typeParam A - the hook's payload argument tuple.
+ */
+interface SerialHookEntry<A extends readonly unknown[] = readonly unknown[]> extends Orderable {
+  /** Run this participant with the hook payload. A bail return stops the chain. */
+  readonly run: (...args: A) => unknown | Promise<unknown>;
+}
+/** Configuration for the {@link SerialHookOrdering} service. */
+type SerialHookOrderingConfig = HookOrderingLogConfig;
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    serialHooksOrdering: SerialHookOrdering;
+  }
+}
+/**
+ * Coordinator service registered at `ctx.serialHooksOrdering`. Controls any
+ * number of serial hooks; each owns a prepended front coordinator, an appended
+ * back coordinator, and two ordered participant lists.
+ */
+declare class SerialHookOrdering extends HookOrderingBase<SerialHookEntry> {
+  /**
+   * @param ctx - the Cordis context to register the service in.
+   * @param config - optional `log` file for the constraint DAG (JSON); `null` means defaults.
+   */
+  constructor(ctx: Context, config?: SerialHookOrderingConfig | null);
+  /**
+   * Install the two coordinator listeners. The front one is prepended so it
+   * runs ahead of the native chain; the back one is appended so it runs after
+   * the listeners present at control time. Both are effects on this service's
+   * fiber; the returned disposer removes both.
+   */
+  protected install(hook: string, front: SerialHookEntry[], back: SerialHookEntry[]): () => void;
+  /**
+   * Register a participant into a controlled hook phase.
+   *
+   * @param hook - the controlled serial event name.
+   * @param phase - `front` to run ahead of the native chain, `back` best-effort last.
+   * @param entry - the participant; its `run` may return a bail value to short-circuit.
+   * @returns a disposer that unregisters this participant.
+   * @throws {HookControlError} when the hook has not been {@link control}led.
+   */
+  register<A extends readonly unknown[] = readonly unknown[]>(hook: string, phase: Phase, entry: SerialHookEntry<A>): () => void;
+}
+//#endregion
+export { SerialHookOrdering as n, SerialHookOrderingConfig as r, SerialHookEntry as t };
+//# sourceMappingURL=serial-D8ZJCBKL.d.ts.map

package/lib/serial-D8ZJCBKL.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-D8ZJCBKL.d.ts","names":[],"sources":["../src/serial.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;UA8BiB,2EAA2E;;0BAElE,gBAAgB;;;KAI9B,wBAAA,GAA2B;;;yBAId;;;;;;;;cASZ,kBAAA,SAA2B,iBAAiB;;;;;mBAKtC,kBAAiB;;;;;;;yCAUK,yBAAyB;;;;;;;;;;mFAsBvD,cACA,gBAAgB"}

package/lib/serial.d.ts

@@ -0,0 +1,5 @@
+import "./topo-sort-BZ1fFcTs.js";
+import "./dag-Bqx-sl71.js";
+import "./service-base-CCmIBwnB.js";
+import { n as SerialHookOrdering, r as SerialHookOrderingConfig, t as SerialHookEntry } from "./serial-D8ZJCBKL.js";
+export { SerialHookEntry, SerialHookOrdering, SerialHookOrderingConfig };

package/lib/serial.js

@@ -0,0 +1,6 @@
+import "./dag-DVhoBjBG.js";
+import "./topo-sort-CfwYPY4U.js";
+import "./service-base-a5vKg62S.js";
+import { t as SerialHookOrdering } from "./serial-Cu7usHjI.js";
+
+export { SerialHookOrdering };