gazetta 0.7.0 → 0.8.0

package/dist/hooks/context.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `HookContext` builder — per-request factory that admin-api route
+ * handlers call to construct the context passed to dispatch.
+ *
+ * The HookContext is built ONCE per request (not per-hook) and
+ * shared across every dispatch in that request. This is the
+ * "deterministic timestamp" invariant from design-hooks.md "Locked
+ * invariants" — `now` is computed when the context is built so all
+ * hooks in the request see the same wall clock.
+ *
+ * # Why a builder, not a middleware
+ *
+ * Earlier drafts considered a `hooksMiddleware` that attaches the
+ * context to `c.var.hooks`. The reason that doesn't work as
+ * cleanly: HookContext needs the SCOPE of each operation
+ * (page name, fragment name, locale, etc.) which the middleware
+ * can't know — only the route handler does. Route handlers
+ * already have everything they need (principal from
+ * `c.var.principal`, headers from `c.req`, source from the
+ * resolver); a tiny builder function bundles them into a
+ * HookContext per-call.
+ *
+ * # Read-only storage proxy
+ *
+ * The HookContext exposes `storage` as `ReadOnlyStorageProvider`.
+ * v1 uses a Proxy that forwards read methods only; write methods
+ * are absent from the type and would throw at the proxy layer if
+ * called via type assertion. This is the "Proxy implementation"
+ * design open question 2 from design-hooks.md — accepted with the
+ * Proxy approach for less code duplication.
+ *
+ * # Logger fallback
+ *
+ * Until the logging foundation lands, the context's `log` field is
+ * a no-op logger. design-hooks.md notes this: "v1 hooks dispatch
+ * supplies a no-op logger or pino child as available."
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: builder constructs the context; doesn't dispatch
+ *     (Cut 2's concern), doesn't discover handlers (Cut 3's), and
+ *     doesn't audit hook firings (Cut 7's).
+ *   - DIP: builder takes a Principal + StorageProvider + ID
+ *     generator + clock; doesn't reach into Hono internals.
+ */
+import type { Principal } from '../auth/types.js';
+import type { StorageProvider } from '../types.js';
+import type { HookFiringEmitter } from './audit-emitter.js';
+import type { HookContext, HookLogger, ReadOnlySiteConfig } from './types.js';
+export interface BuildHookContextOptions {
+    principal: Principal;
+    storage: StorageProvider;
+    /** Active target name when the operation is target-scoped. */
+    target?: string;
+    /** Per-request correlation ID; matches audit + log ids. */
+    requestId: string;
+    /** Request timestamp; deterministic for all hooks in this request. */
+    now?: Date;
+    /** Logger; defaults to no-op until logging foundation lands. */
+    log?: HookLogger;
+    /** Read-only site config. */
+    site: ReadOnlySiteConfig;
+    /**
+     * Optional audit firing emitter. When set, dispatch records
+     * one `action: 'hook-fired'` audit event per hook firing per
+     * design-hooks.md "Audit events". Production wires this to
+     * `c.var.audit`; tests omit for silent firing.
+     */
+    auditEmit?: HookFiringEmitter;
+}
+/**
+ * Build a HookContext for one request. Construct once per request
+ * and pass to every dispatch in that request — the `now` and
+ * `requestId` fields are deterministic across the per-request
+ * dispatches.
+ */
+export declare function buildHookContext(opts: BuildHookContextOptions): HookContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/hooks/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/hooks/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAS7E,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,eAAe,CAAA;IACxB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,IAAI,CAAA;IACV,gEAAgE;IAChE,GAAG,CAAC,EAAE,UAAU,CAAA;IAChB,6BAA6B;IAC7B,IAAI,EAAE,kBAAkB,CAAA;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,WAAW,CAW3E"}

package/dist/hooks/context.js

@@ -0,0 +1,56 @@
+const NOOP_LOGGER = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * Build a HookContext for one request. Construct once per request
+ * and pass to every dispatch in that request — the `now` and
+ * `requestId` fields are deterministic across the per-request
+ * dispatches.
+ */
+export function buildHookContext(opts) {
+    return {
+        principal: opts.principal,
+        target: opts.target,
+        requestId: opts.requestId,
+        auditEmit: opts.auditEmit,
+        now: opts.now ?? new Date(),
+        log: opts.log ?? NOOP_LOGGER,
+        site: opts.site,
+        storage: makeReadOnlyStorage(opts.storage),
+    };
+}
+/**
+ * Wrap a `StorageProvider` in a read-only Proxy. The returned
+ * value satisfies `ReadOnlyStorageProvider`; the wrapped read
+ * methods forward to the underlying provider; the write methods
+ * are absent from the type AND would throw if invoked via type
+ * assertion.
+ *
+ * Why Proxy instead of a copy of read methods: Proxy preserves
+ * `this` for any inherited methods + future read methods (e.g.,
+ * `stat()` if added later) flow through automatically.
+ */
+function makeReadOnlyStorage(storage) {
+    const READ_METHODS = new Set(['readFile', 'readDir', 'exists', 'readBytes', 'readStream']);
+    const handler = {
+        get(target, prop, receiver) {
+            if (typeof prop !== 'string')
+                return Reflect.get(target, prop, receiver);
+            if (READ_METHODS.has(prop)) {
+                const method = Reflect.get(target, prop, receiver);
+                if (typeof method === 'function')
+                    return method.bind(target);
+                return method;
+            }
+            // Write methods + anything else: throw to surface the
+            // contract violation. Hooks should never reach for
+            // writeFile/writeBytes/writeStream/mkdir/rm via ctx.storage.
+            throw new TypeError(`Hook context's storage is read-only — "${prop}" is not available. Writes go through the operation that fired the hook.`);
+        },
+    };
+    return new Proxy(storage, handler);
+}
+//# sourceMappingURL=context.js.map

package/dist/hooks/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/hooks/context.ts"],"names":[],"mappings":"AAmDA,MAAM,WAAW,GAAe;IAC9B,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAA;AAwBD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA6B;IAC5D,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE;QAC3B,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,WAAW;QAC5B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;KAC3C,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,mBAAmB,CAAC,OAAwB;IACnD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAA;IAC1F,MAAM,OAAO,GAAkC;QAC7C,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACxB,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;YACxE,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;gBAClD,IAAI,OAAO,MAAM,KAAK,UAAU;oBAAE,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBAC5D,OAAO,MAAM,CAAA;YACf,CAAC;YACD,sDAAsD;YACtD,mDAAmD;YACnD,6DAA6D;YAC7D,MAAM,IAAI,SAAS,CACjB,0CAA0C,IAAI,0EAA0E,CACzH,CAAA;QACH,CAAC;KACF,CAAA;IACD,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,OAAO,CAAuC,CAAA;AAC1E,CAAC"}

package/dist/hooks/contribution.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `HookContribution` — what a hook factory returns.
+ *
+ * Operators add factory contributions to `site.config.ts`'s
+ * `admin.hooks` array; the boot path calls each contribution's
+ * `hooks[]` entries against the same registry that picks up
+ * site-local file discovery.
+ *
+ * Per design-hooks.md Cut 9 + grilling-with-docs locked Q1
+ * (bundled-object shape):
+ *
+ *   - `source` is package-level metadata (e.g.,
+ *     '@example/cdn-purge'). Captured once per contribution; the
+ *     loader stamps it on every registered HookEntry's source
+ *     field for audit + diagnostics.
+ *   - `hooks` is an array because one package may contribute
+ *     multiple handlers across phases (e.g., a CDN-purge plugin
+ *     wires both afterSave and afterPublish).
+ *
+ * # Why bundle vs. flat array
+ *
+ *   - SRP: source is per-package; hook entries are per-handler.
+ *     Bundling reflects the ontology — one factory call = one
+ *     logical plugin contributing N handlers.
+ *   - DRY: source declared once per package, not stamped on
+ *     every entry.
+ *
+ * # Why source is required
+ *
+ *   - Audit log records source per firing; defaulting to
+ *     'site-local' would lie when the contribution actually came
+ *     from a named package.
+ *   - Plugin authors writing distributables always know their
+ *     package name; declaring it is one line.
+ *   - Site-local hooks (admin/hooks/*.ts) get 'site-local' from
+ *     the file walker, not from this type.
+ *
+ * # Why duplicate sources allowed
+ *
+ *   - Operators legitimately invoke the same factory twice with
+ *     different config (e.g., two CDN-purge instances for
+ *     different regions). Both register; audit log records both
+ *     events with the same source. Per-handler `options.name`
+ *     distinguishes them where needed.
+ *   - Locked grilling-with-docs Q5.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: type owns the contribution shape; doesn't construct
+ *     handlers, doesn't register against the registry.
+ *   - LSP: every plugin's factory returns `HookContribution`;
+ *     the loader treats them all uniformly.
+ */
+import type { HookHandler, HookOptions, HookPhase } from './types.js';
+/**
+ * One entry in a contribution's `hooks` array. Carries the phase,
+ * the handler, and per-handler options (priority / name /
+ * timeout).
+ *
+ * `source` is intentionally absent — it lives on the parent
+ * `HookContribution` and gets stamped at registration time.
+ * Per-entry override would defeat the bundling rationale.
+ */
+export interface HookEntry {
+    readonly phase: HookPhase;
+    readonly handler: HookHandler;
+    readonly options?: HookOptions;
+}
+/**
+ * What a hook factory returns. Operators add to
+ * `site.config.ts`'s `admin.hooks` array; one entry per factory
+ * invocation.
+ */
+export interface HookContribution {
+    /**
+     * Source identity for diagnostics + audit. Conventional values:
+     *
+     *   - `'@scope/package-name'` — npm-distributed plugin
+     *   - `'github.com/org/repo'` — git-distributed plugin
+     *   - any other unambiguous string the plugin author prefers
+     *
+     * The reserved value `'site-local'` is auto-applied by the
+     * file-discovery walker (admin/hooks/*.ts) and SHOULD NOT be
+     * used by factory-supplied contributions.
+     */
+    readonly source: string;
+    /** One or more handlers contributed by this package. */
+    readonly hooks: ReadonlyArray<HookEntry>;
+}
+//# sourceMappingURL=contribution.d.ts.map

package/dist/hooks/contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution.d.ts","sourceRoot":"","sources":["../../src/hooks/contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CACzC"}

package/dist/hooks/contribution.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contribution.js.map

package/dist/hooks/contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution.js","sourceRoot":"","sources":["../../src/hooks/contribution.ts"],"names":[],"mappings":""}

package/dist/hooks/dispatch.d.ts

@@ -0,0 +1,30 @@
+import type { HookRegistry } from './registry.js';
+import type { HookContext, HookScope, PublishHookResult, PublishItem, SaveResult, UploadHookAsset, UploadHookPayload, UploadHookResult } from './types.js';
+/**
+ * Chain `beforeSave` handlers. Returns the final payload after
+ * every handler has run (or throws `HookCancellation` on first
+ * failing handler).
+ */
+export declare function dispatchBeforeSave<T>(registry: HookRegistry, scope: HookScope, payload: T, ctx: HookContext): Promise<T>;
+/**
+ * Fan out `afterSave` handlers in parallel. Failures logged;
+ * never propagated.
+ */
+export declare function dispatchAfterSave<T>(registry: HookRegistry, scope: HookScope, result: SaveResult<T>, ctx: HookContext): Promise<void>;
+/**
+ * Chain `afterLoad` handlers. Although the phase fires after
+ * load (not before save), it's a mutating chain: each handler
+ * may transform the loaded payload. Same shape as `beforeSave`.
+ */
+export declare function dispatchAfterLoad<T>(registry: HookRegistry, scope: HookScope, payload: T, ctx: HookContext): Promise<T>;
+/**
+ * Chain `beforePublish` handlers. Returns the final item array.
+ */
+export declare function dispatchBeforePublish(registry: HookRegistry, target: string, items: ReadonlyArray<PublishItem>, ctx: HookContext): Promise<ReadonlyArray<PublishItem>>;
+/** Fan-out `afterPublish` parallel. */
+export declare function dispatchAfterPublish(registry: HookRegistry, target: string, result: PublishHookResult, ctx: HookContext): Promise<void>;
+/** Chain `beforeUpload` handlers. Returns the final asset + bytes. */
+export declare function dispatchBeforeUpload(registry: HookRegistry, asset: UploadHookAsset, bytes: Uint8Array, ctx: HookContext): Promise<UploadHookPayload>;
+/** Fan-out `afterUpload` parallel. */
+export declare function dispatchAfterUpload(registry: HookRegistry, asset: UploadHookAsset, result: UploadHookResult, ctx: HookContext): Promise<void>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/hooks/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/hooks/dispatch.ts"],"names":[],"mappings":"AAoDA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,OAAO,KAAK,EAQV,WAAW,EAGX,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,CAAC,CAAC,CASZ;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,CAAC,CAAC,CASZ;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EACjC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CASrC;AAED,uCAAuC;AACvC,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,sEAAsE;AACtE,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED,sCAAsC;AACtC,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/hooks/dispatch.js

@@ -0,0 +1,252 @@
+/**
+ * Hook dispatch — chains `before*` handlers, fans out `after*`
+ * handlers, enforces per-handler timeout.
+ *
+ * Per design-hooks.md "Composition (Q3 locked)":
+ *
+ *   - `before*` chain: output of handler N = input of handler N+1.
+ *     Final output proceeds to the operation. One handler throws
+ *     → operation cancels; subsequent handlers don't fire.
+ *   - `after*` parallel: each handler receives the same operation
+ *     result. Independent (no chaining). Failures logged but
+ *     don't stop other `after*` handlers from running.
+ *   - Per-hook timeout (default 5s, configurable per registration):
+ *     `before*` timeout = throw = cancel operation; `after*`
+ *     timeout = logged + counted; chain continues.
+ *
+ * # Why two dispatch functions, not one
+ *
+ * `dispatchBefore` returns `Promise<T>` (the chained payload).
+ * `dispatchAfter` returns `Promise<void>` (nothing to chain).
+ * Same generic shape would force `dispatchAfter` consumers to
+ * discard a meaningless return value, and `dispatchBefore`'s
+ * cancellation semantics would force `after*` callers to handle
+ * a throw they can never produce. Two functions, two contracts.
+ *
+ * # Timeout implementation
+ *
+ * `Promise.race(handler, timeoutPromise)` where the timeout
+ * promise rejects with `HookTimeout`. The handler may still be
+ * resolving in the background after timeout — Node's process
+ * keeps running until handles drain. v1 doesn't `AbortController`
+ * the handler; the design notes this as acceptable for v1
+ * (handler completion after timeout is harmless because the
+ * dispatcher already moved on).
+ *
+ * # Promise.allSettled vs Promise.all for `after*`
+ *
+ * `allSettled` so one failing handler doesn't prevent siblings
+ * from firing. Each rejection is logged via `ctx.log.error` with
+ * the hook name + phase + duration. The dispatcher itself never
+ * rejects from `dispatchAfter`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: dispatch owns the orchestration logic. Per-handler
+ *     timeout is one concern (private helper). Cancellation
+ *     wrapping is one concern (private helper).
+ *   - DIP: callers depend on the dispatch functions; the
+ *     registry's storage layout is opaque.
+ *   - LSP: every dispatcher behaves identically across phases.
+ */
+import { HookCancellation, HookTimeout } from './errors.js';
+import { eventFromRegistration } from './audit-emitter.js';
+/**
+ * Chain `beforeSave` handlers. Returns the final payload after
+ * every handler has run (or throws `HookCancellation` on first
+ * failing handler).
+ */
+export async function dispatchBeforeSave(registry, scope, payload, ctx) {
+    const handlers = registry.getByPhase('beforeSave');
+    let current = payload;
+    for (const reg of handlers) {
+        current = await runWithTimeout('beforeSave', reg, ctx, async () => reg.handler(scope, current, ctx));
+    }
+    return current;
+}
+/**
+ * Fan out `afterSave` handlers in parallel. Failures logged;
+ * never propagated.
+ */
+export async function dispatchAfterSave(registry, scope, result, ctx) {
+    const handlers = registry.getByPhase('afterSave');
+    await runAfterChain(handlers, ctx, async (reg) => reg.handler(scope, result, ctx));
+}
+/**
+ * Chain `afterLoad` handlers. Although the phase fires after
+ * load (not before save), it's a mutating chain: each handler
+ * may transform the loaded payload. Same shape as `beforeSave`.
+ */
+export async function dispatchAfterLoad(registry, scope, payload, ctx) {
+    const handlers = registry.getByPhase('afterLoad');
+    let current = payload;
+    for (const reg of handlers) {
+        current = await runWithTimeout('afterLoad', reg, ctx, async () => reg.handler(scope, current, ctx));
+    }
+    return current;
+}
+/**
+ * Chain `beforePublish` handlers. Returns the final item array.
+ */
+export async function dispatchBeforePublish(registry, target, items, ctx) {
+    const handlers = registry.getByPhase('beforePublish');
+    let current = items;
+    for (const reg of handlers) {
+        current = await runWithTimeout('beforePublish', reg, ctx, async () => reg.handler(target, current, ctx));
+    }
+    return current;
+}
+/** Fan-out `afterPublish` parallel. */
+export async function dispatchAfterPublish(registry, target, result, ctx) {
+    const handlers = registry.getByPhase('afterPublish');
+    await runAfterChain(handlers, ctx, async (reg) => reg.handler(target, result, ctx));
+}
+/** Chain `beforeUpload` handlers. Returns the final asset + bytes. */
+export async function dispatchBeforeUpload(registry, asset, bytes, ctx) {
+    const handlers = registry.getByPhase('beforeUpload');
+    let current = { asset, bytes };
+    for (const reg of handlers) {
+        current = await runWithTimeout('beforeUpload', reg, ctx, async () => reg.handler(current.asset, current.bytes, ctx));
+    }
+    return current;
+}
+/** Fan-out `afterUpload` parallel. */
+export async function dispatchAfterUpload(registry, asset, result, ctx) {
+    const handlers = registry.getByPhase('afterUpload');
+    await runAfterChain(handlers, ctx, async (reg) => reg.handler(asset, result, ctx));
+}
+/**
+ * Run a handler with a per-handler timeout. Wraps non-
+ * cancellation errors as `HookCancellation` so call sites can
+ * `instanceof HookCancellation` uniformly.
+ *
+ * Used by `before*` chains. Throws to cancel the operation.
+ */
+async function runWithTimeout(phase, reg, ctx, handler) {
+    let timer;
+    const start = Date.now();
+    try {
+        const handlerPromise = handler();
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new HookTimeout({ hookName: reg.name, phase, timeoutMs: reg.timeout }));
+            }, reg.timeout);
+            // unref() so a hung handler doesn't keep the process alive.
+            // Available on Node setTimeout return; not on browser.
+            const t = timer;
+            t.unref?.();
+        });
+        const result = await Promise.race([handlerPromise, timeoutPromise]);
+        // Audit: success firing. Per design-hooks.md "Audit events".
+        await safeEmit(ctx, reg, 'success', Date.now() - start);
+        return result;
+    }
+    catch (err) {
+        // HookTimeout and HookCancellation already carry the right
+        // shape; rewrap anything else as a HookCancellation so
+        // `instanceof HookCancellation` covers both "explicit cancel"
+        // and "handler crashed."
+        const durationMs = Date.now() - start;
+        if (err instanceof HookTimeout) {
+            await safeEmit(ctx, reg, 'timeout', durationMs);
+            throw err;
+        }
+        if (err instanceof HookCancellation) {
+            await safeEmit(ctx, reg, 'hook-cancelled', durationMs);
+            throw err;
+        }
+        await safeEmit(ctx, reg, 'hook-cancelled', durationMs);
+        throw new HookCancellation({
+            hookName: reg.name,
+            phase,
+            message: err instanceof Error ? err.message : String(err),
+            cause: err,
+        });
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Forward a hook firing event to ctx.auditEmit. Wrapped in
+ * try/catch so emitter failures don't break dispatch.
+ */
+async function safeEmit(ctx, reg, outcome, durationMs) {
+    if (!ctx.auditEmit)
+        return;
+    try {
+        await ctx.auditEmit(eventFromRegistration(reg, ctx, outcome, durationMs));
+    }
+    catch {
+        // Emitter failures isolate to the dispatcher; we don't want
+        // a crashing audit recorder to cancel an operation. Failure
+        // is silently ignored; audit pipeline has its own structured
+        // log surface for emitter problems.
+    }
+}
+/**
+ * Run an `after*` chain: parallel via `Promise.allSettled`,
+ * per-handler timeout, failures logged via ctx.log without
+ * propagating.
+ */
+async function runAfterChain(handlers, ctx, invoke) {
+    if (handlers.length === 0)
+        return;
+    const results = await Promise.allSettled(handlers.map(reg => runWithTimeoutAfter(reg, ctx, () => invoke(reg))));
+    for (const [i, r] of results.entries()) {
+        if (r.status === 'rejected') {
+            const reg = handlers[i];
+            const reason = r.reason;
+            const isTimeout = reason instanceof HookTimeout;
+            ctx.log.error({
+                hookName: reg.name,
+                phase: reg.phase,
+                source: reg.source,
+                timeout: isTimeout,
+                err: reason instanceof Error ? { name: reason.name, message: reason.message } : { message: String(reason) },
+            }, `Hook "${reg.name}" failed in ${reg.phase}`);
+        }
+    }
+}
+/**
+ * Variant of `runWithTimeout` for `after*` handlers — preserves
+ * `HookTimeout` for the logger to discriminate, but doesn't wrap
+ * crashes as `HookCancellation` (after-handlers can't cancel).
+ *
+ * Audit emit fires the same way as `runWithTimeout`; outcome
+ * `'timeout'` distinguishes per-handler timeouts; non-timeout
+ * crashes record as `'hook-cancelled'` (closest semantic — handler
+ * threw, even if the operation didn't cancel).
+ */
+async function runWithTimeoutAfter(reg, ctx, handler) {
+    let timer;
+    const start = Date.now();
+    try {
+        const handlerPromise = handler();
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new HookTimeout({ hookName: reg.name, phase: reg.phase, timeoutMs: reg.timeout }));
+            }, reg.timeout);
+            const t = timer;
+            t.unref?.();
+        });
+        await Promise.race([handlerPromise, timeoutPromise]);
+        await safeEmit(ctx, reg, 'success', Date.now() - start);
+    }
+    catch (err) {
+        const durationMs = Date.now() - start;
+        if (err instanceof HookTimeout) {
+            await safeEmit(ctx, reg, 'timeout', durationMs);
+        }
+        else {
+            await safeEmit(ctx, reg, 'hook-cancelled', durationMs);
+        }
+        throw err;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/hooks/dispatch.js.map

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

package/dist/hooks/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Hook error taxonomy.
+ *
+ * Per design-hooks.md, three distinct error classes carry different
+ * dispatcher semantics:
+ *
+ *   - `HookCancellation`: a `before*` hook threw to cancel the
+ *     operation. Operation aborts; audit records
+ *     `outcome: 'hook-cancelled'`. The original error (if not a
+ *     `HookCancellation`) is wrapped so call sites can distinguish
+ *     "hook explicitly cancelled" from "hook crashed."
+ *
+ *   - `HookTimeout`: a hook's per-handler timeout fired before the
+ *     handler resolved. For `before*` hooks this cancels the
+ *     operation (same handling as `HookCancellation`); for `after*`
+ *     hooks it's logged + counted but doesn't propagate.
+ *
+ *   - `RegistrationAfterInitError`: thrown when code tries to
+ *     register a hook after the boot-time registration phase has
+ *     finished. `buildHooksRegistry({ contributions })` registers
+ *     all factory contributions then calls `seal()`. Any subsequent
+ *     `register(...)` surfaces this error — a deferred Promise that
+ *     registers from inside a hook handler, for example, leaks past
+ *     the registration window.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: each error class names one failure mode; consumers
+ *     branch on `instanceof` to discriminate.
+ *   - LSP: each subclass `extends HookError` so a `catch (err: HookError)`
+ *     handler covers every hook-layer failure.
+ *   - DIP: callers depend on the abstract `HookError` for catch-all
+ *     handling; specific subclasses for fine-grained recovery.
+ */
+/** Base class for all hook-layer errors. */
+export declare class HookError extends Error {
+    readonly name: string;
+}
+/**
+ * A `before*` hook threw to cancel the operation, OR a hook handler
+ * threw a non-cancellation error that the dispatcher wraps for
+ * uniform handling.
+ *
+ * The originating handler's name is captured for audit metadata.
+ * The original error (if any) is exposed via `cause` so operators
+ * can investigate handler crashes vs. explicit cancellations.
+ */
+export declare class HookCancellation extends HookError {
+    readonly name = "HookCancellation";
+    /** The hook that cancelled — either `meta.name` or the file basename. */
+    readonly hookName: string;
+    /** The phase the hook was firing in. */
+    readonly phase: string;
+    constructor(opts: {
+        hookName: string;
+        phase: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * A hook's per-handler timeout fired. The handler may still be
+ * resolving (the dispatcher races the handler against a setTimeout-
+ * backed promise) — but the operation can't wait for it.
+ */
+export declare class HookTimeout extends HookError {
+    readonly name = "HookTimeout";
+    readonly hookName: string;
+    readonly phase: string;
+    readonly timeoutMs: number;
+    constructor(opts: {
+        hookName: string;
+        phase: string;
+        timeoutMs: number;
+    });
+}
+/**
+ * Thrown when `register(...)` is called on a sealed `HookRegistry`
+ * (post-boot).
+ *
+ * Registration window per ADR-0009 + `design-plugins.md`:
+ * `buildHooksRegistry({ contributions })` walks `admin.hooks`
+ * factory contributions at boot, registers each entry, then calls
+ * `seal()`. Any subsequent `register(...)` surfaces this error —
+ * for instance a deferred Promise inside a factory that resolves
+ * after the registration window closed, or a hook handler that
+ * tries to register additional hooks at runtime.
+ */
+export declare class RegistrationAfterInitError extends HookError {
+    readonly name = "RegistrationAfterInitError";
+    /** Source identity (plugin name / `'site-local'`) attempting late registration. */
+    readonly source: string;
+    /** Phase the late registration targeted. */
+    readonly phase: string;
+    constructor(opts: {
+        source: string;
+        phase: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/hooks/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/hooks/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,4CAA4C;AAC5C,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,EAAE,MAAM,CAAc;CAC7C;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,SAAkB,IAAI,sBAAqB;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;gBAEV,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOzF;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,SAAS;IACxC,SAAkB,IAAI,iBAAgB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAEd,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAMzE;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,SAAkB,IAAI,gCAA+B;IACrD,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;gBAEV,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAOpD"}