@zfdx123/dsh-hooks-ordering 1.0.1

package/src/service-base.ts

@@ -0,0 +1,179 @@
+/**
+ * Shared coordinator machinery for the waterfall and serial hook-ordering
+ * services. Both manage, per controlled hook, two ordered participant lists
+ * (`front`/`back`) plus the disposer for the installed coordinator(s); they
+ * differ only in HOW the coordinator listeners are installed and HOW a phase
+ * runs (waterfall wraps the native chain via `next()`; serial runs participants
+ * ahead of it with bail short-circuiting). Registration, planning, DAG dumping,
+ * and optional file logging are identical, so they live here.
+ * @module dsh-hooks-ordering/service-base
+ */
+
+import { writeFileSync } from 'node:fs'
+import { type Context, Service } from '@deepseek-ai/cordis'
+import { type DagSection, buildDag } from './dag.ts'
+import { type Orderable, topoSort } from './topo-sort.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).
+ */
+export type Phase = 'front' | 'back'
+
+/** Thrown when registering into, or double-controlling, a hook in an unsupported state. */
+export class HookControlError extends Error {
+  /**
+   * @param message - the specific control-state violation.
+   */
+  constructor(message: string) {
+    super(`hooks-ordering: ${message}`)
+    this.name = 'HookControlError'
+  }
+}
+
+/** Optional file logging shared by both services. */
+export 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). */
+export 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.
+ */
+export abstract class HookOrderingBase<E extends Orderable> extends Service {
+  protected readonly hooks = new 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 = {}) {
+    super(ctx, name)
+    this.log = config?.log
+  }
+
+  /**
+   * 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 {
+    if (this.hooks.has(hook)) throw new HookControlError(`hook ${JSON.stringify(hook)} is already controlled`)
+
+    const front: E[] = []
+    const back: E[] = []
+    const removeListeners = this.install(hook, front, back)
+
+    const dispose = (): void => {
+      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.
+   */
+  protected registerEntry(hook: string, phase: Phase, entry: E): () => void {
+    const controlled = this.hooks.get(hook)
+    if (controlled === undefined)
+      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: string, phase: Phase): string[] {
+    const controlled = this.hooks.get(hook)
+    if (controlled === undefined) 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(): string {
+    return JSON.stringify(buildDag(this.dagSections()), null, 2)
+  }
+
+  /** Flatten every controlled hook into its `front`/`back` DAG sections. */
+  protected dagSections(): DagSection[] {
+    const sections: DagSection[] = []
+    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.
+   */
+  protected refreshLog(): void {
+    if (this.log === undefined) 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)
+    }
+  }
+}

package/src/settings.ts

@@ -0,0 +1,97 @@
+/**
+ * The dsh settings namespace for this plugin: the three fields a user can edit
+ * from the Settings page instead of a `cordis.patch.yml` row.
+ *
+ * Two constraints are load-bearing and easy to get wrong:
+ *
+ * - The schema handed to `settings.register` must be a **callable** schemastery
+ *   schema. dsh resolves a namespace by calling `schema(merged)` and reads
+ *   `schema.toJSON()` for the form, so a plain object throws
+ *   `schema is not a function` — during plugin assembly, which takes the whole
+ *   profile down rather than failing one form.
+ * - That is also why registration is wrapped in `try/catch` here: an optional
+ *   settings form must never be able to stop the harness from booting.
+ *
+ * @module dsh-hooks-ordering/settings
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+
+/** The three fields this plugin exposes for configuration. */
+export interface HooksOrderingSettings {
+  /** Waterfall hooks to control; `[]` disables the waterfall service entirely. */
+  readonly hooks: readonly string[]
+  /** Serial hooks to control; `[]` disables the serial service entirely. */
+  readonly serialHooks: readonly string[]
+  /** Constraint-DAG log file; the empty string means "do not log". */
+  readonly log: string
+}
+
+/** Namespace name — dsh requires a lowercase hyphenated identifier. */
+export 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.
+ */
+export const HooksOrderingSettingsSchema = Schema.object({
+  hooks: Schema.array(Schema.string()).default([]),
+  serialHooks: Schema.array(Schema.string()).default([]),
+  log: Schema.string().default(''),
+})
+
+/**
+ * The slice of dsh's `settings` service this plugin uses.
+ *
+ * Structural rather than imported from `@deepseek-ai/dsh-settings`: it describes
+ * exactly the contract this plugin relies on without adding a build-time
+ * dependency on a dsh package, whose internals are still 0.1.x-rc.
+ */
+export interface SettingsServiceLike {
+  /**
+   * @param ns - the namespace to register; must be a lowercase hyphenated identifier.
+   * @param schema - a callable schemastery schema, not a plain object.
+   * @param options - `base` is the composition layer, `applies` says whether an
+   * edit takes effect live or needs a restart.
+   * @returns a scope whose `get()` is the resolved value (schema defaults, then `base`, then the user layer).
+   */
+  register(
+    ns: string,
+    schema: unknown,
+    options?: { readonly base?: unknown; readonly applies?: 'live' | 'restart' },
+  ): { get(): HooksOrderingSettings }
+}
+
+/**
+ * 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`.
+ */
+export function resolveSettings(ctx: Context, base: HooksOrderingSettings): HooksOrderingSettings | undefined {
+  const settings = ctx.get('settings') as SettingsServiceLike | undefined
+  if (settings === undefined) return undefined
+  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 undefined
+  }
+}

package/src/topo-sort.ts

@@ -0,0 +1,118 @@
+/**
+ * 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. */
+export 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. */
+export 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[]) {
+    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. */
+export class DuplicateNameError extends Error {
+  /** The duplicated entry name. */
+  readonly duplicate: string
+  /**
+   * @param duplicate - the name registered more than once.
+   */
+  constructor(duplicate: string) {
+    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.
+ */
+export function topoSort<T extends Orderable>(entries: readonly T[]): T[] {
+  const index = new Map<string, number>()
+  entries.forEach((entry, position) => {
+    if (index.has(entry.name)) throw new DuplicateNameError(entry.name)
+    index.set(entry.name, position)
+  })
+
+  // successors[i] = entries that must run after entry i. indegree[i] = number
+  // of entries that must run before entry i.
+  const successors: number[][] = entries.map(() => [])
+  const indegree: number[] = entries.map(() => 0)
+
+  const addEdge = (fromName: string, toName: string): void => {
+    const from = index.get(fromName)
+    const to = index.get(toName)
+    // Unknown endpoint: the referenced peer is not loaded, so no ordering
+    // relation exists to enforce.
+    if (from === undefined || to === undefined || 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)
+  })
+
+  // Kahn's algorithm. The ready set holds nodes with no unmet predecessor; it
+  // is kept in ascending input position so equal candidates emit in input
+  // order, giving a deterministic, stable result. Per-phase entry counts are
+  // small, so a sort on each insertion is simpler than a hand-rolled heap.
+  const ready: number[] = []
+  const pushReady = (node: number): void => {
+    ready.push(node)
+    ready.sort((left, right) => left - right)
+  }
+  indegree.forEach((count, node) => {
+    if (count === 0) pushReady(node)
+  })
+
+  const result: T[] = []
+  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) {
+    // The entries still carrying an unmet predecessor are exactly those on or
+    // behind the cycle; naming them all is more useful than one arbitrary loop.
+    const blocked = entries.filter((_, node) => indegree[node]! > 0).map((entry) => entry.name)
+    throw new OrderingCycleError(blocked)
+  }
+  return result
+}

package/src/waterfall.ts

@@ -0,0 +1,153 @@
+/**
+ * `HookOrdering` — deterministic before/after ordering for Cordis waterfall
+ * hooks whose participants are contributed by independent plugins.
+ *
+ * Cordis runs waterfall listeners in registration order (array position, with
+ * `prepend` as the only lever), and registration order is driven by
+ * inject-dependency activation — non-deterministic between unrelated plugins.
+ * A plugin therefore cannot reliably say "run me after that other plugin",
+ * especially across vendors that do not depend on each other.
+ *
+ * This service brackets a chosen waterfall hook with ONE prepended listener
+ * that exploits the onion model: code before its `next()` runs ahead of the
+ * whole native chain, code after runs behind it. Participants register into
+ * this coordinator instead of the raw hook, declaring `before`/`after` names,
+ * and the coordinator runs them in a stable topological order it fully
+ * controls. The serial-dispatch twin lives in `./serial.ts`.
+ *
+ * @module dsh-hooks-ordering/waterfall
+ */
+
+import { type Context } from '@deepseek-ai/cordis'
+import { HookControlError, HookOrderingBase, type HookOrderingLogConfig, type Phase } from './service-base.ts'
+import { type Orderable, topoSort } from './topo-sort.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`).
+ */
+export 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. */
+export 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.
+ */
+export 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: ReadonlySet<string>
+
+  /**
+   * @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 = {}) {
+    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.
+   */
+  protected install(hook: string, front: HookEntry[], back: HookEntry[]): () => void {
+    const bracket = (...args: unknown[]): unknown => {
+      const next = args[args.length - 1] as () => unknown
+      // Transparent fast path: no participants, so no await is needed and the
+      // native return value (promise or not) passes through unchanged.
+      if (front.length === 0 && back.length === 0) return next()
+      const payload = args.slice(0, -1)
+      // With participants the phases must be awaited, so the bracket can only
+      // return a promise from here on — inherent to ordering, not a choice.
+      return (async (): Promise<unknown> => {
+        await runPhase(front, payload)
+        const result = await next()
+        await runPhase(back, payload)
+        return result
+      })()
+    }
+    return this.ctx.on(hook as never, bracket as never, { 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<A extends readonly unknown[] = readonly unknown[]>(
+    hook: string,
+    phase: Phase,
+    entry: HookEntry<A>,
+  ): () => void {
+    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 as unknown as HookEntry)
+  }
+}
+
+/**
+ * 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: readonly HookEntry[], payload: readonly unknown[]): Promise<void> {
+  for (const entry of topoSort(entries)) {
+    await entry.run(...payload)
+  }
+}
+
+export default HookOrdering