gazetta 0.6.0 → 0.8.0

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"}

package/dist/hooks/errors.js

@@ -0,0 +1,103 @@
+/**
+ * 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 class HookError extends Error {
+    name = 'HookError';
+}
+/**
+ * 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 class HookCancellation extends HookError {
+    name = 'HookCancellation';
+    /** The hook that cancelled — either `meta.name` or the file basename. */
+    hookName;
+    /** The phase the hook was firing in. */
+    phase;
+    constructor(opts) {
+        super(opts.message ?? `Hook "${opts.hookName}" cancelled the ${opts.phase} operation`, {
+            cause: opts.cause,
+        });
+        this.hookName = opts.hookName;
+        this.phase = opts.phase;
+    }
+}
+/**
+ * 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 class HookTimeout extends HookError {
+    name = 'HookTimeout';
+    hookName;
+    phase;
+    timeoutMs;
+    constructor(opts) {
+        super(`Hook "${opts.hookName}" timed out after ${opts.timeoutMs}ms in ${opts.phase}`);
+        this.hookName = opts.hookName;
+        this.phase = opts.phase;
+        this.timeoutMs = opts.timeoutMs;
+    }
+}
+/**
+ * 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 class RegistrationAfterInitError extends HookError {
+    name = 'RegistrationAfterInitError';
+    /** Source identity (plugin name / `'site-local'`) attempting late registration. */
+    source;
+    /** Phase the late registration targeted. */
+    phase;
+    constructor(opts) {
+        super(`Hook registration window has closed. Source "${opts.source}" attempted to register a "${opts.phase}" handler after admin init completed. Move the registration into the plugin's init() function.`);
+        this.source = opts.source;
+        this.phase = opts.phase;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/hooks/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/hooks/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,4CAA4C;AAC5C,MAAM,OAAO,SAAU,SAAQ,KAAK;IAChB,IAAI,GAAW,WAAW,CAAA;CAC7C;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC3B,IAAI,GAAG,kBAAkB,CAAA;IAC3C,yEAAyE;IAChE,QAAQ,CAAQ;IACzB,wCAAwC;IAC/B,KAAK,CAAQ;IAEtB,YAAY,IAA4E;QACtF,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,SAAS,IAAI,CAAC,QAAQ,mBAAmB,IAAI,CAAC,KAAK,YAAY,EAAE;YACrF,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAA;QACF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,SAAS;IACtB,IAAI,GAAG,aAAa,CAAA;IAC7B,QAAQ,CAAQ;IAChB,KAAK,CAAQ;IACb,SAAS,CAAQ;IAE1B,YAAY,IAA4D;QACtE,KAAK,CAAC,SAAS,IAAI,CAAC,QAAQ,qBAAqB,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAA;IACjC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IACrC,IAAI,GAAG,4BAA4B,CAAA;IACrD,mFAAmF;IAC1E,MAAM,CAAQ;IACvB,4CAA4C;IACnC,KAAK,CAAQ;IAEtB,YAAY,IAAuC;QACjD,KAAK,CACH,gDAAgD,IAAI,CAAC,MAAM,8BAA8B,IAAI,CAAC,KAAK,gGAAgG,CACpM,CAAA;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;CACF"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hooks barrel. Cut 1 ships the type-only foundation; subsequent
+ * cuts add the registry (Cut 2), wired lifecycle phases (Cuts 4-6),
+ * audit integration (Cut 7), review phases (Cut 8), and the
+ * factory-contribution registration path (Cut 9).
+ */
+export type { HookPhase, HookScope, HookContext, HookLogger, ReadOnlySiteConfig, HookHandler, HookOptions, HookRegistration, BeforeSaveHook, AfterSaveHook, AfterLoadHook, SaveResult, BeforePublishHook, AfterPublishHook, PublishItem, PublishHookResult, BeforeUploadHook, AfterUploadHook, UploadHookAsset, UploadHookPayload, UploadHookResult, ReviewTransition, BeforeReviewTransitionHook, AfterReviewTransitionHook, } from './types.js';
+export type { ReadOnlyStorageProvider } from './storage.js';
+export { HookError, HookCancellation, HookTimeout, RegistrationAfterInitError } from './errors.js';
+export { HookRegistry } from './registry.js';
+export { dispatchBeforeSave, dispatchAfterSave, dispatchAfterLoad, dispatchBeforePublish, dispatchAfterPublish, dispatchBeforeUpload, dispatchAfterUpload, } from './dispatch.js';
+export type { HookContribution, HookEntry } from './contribution.js';
+export { buildHookContext, type BuildHookContextOptions } from './context.js';
+export { eventFromRegistration, type HookFiringEmitter, type HookFiringEvent, } from './audit-emitter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EACL,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA"}

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { HookError, HookCancellation, HookTimeout, RegistrationAfterInitError } from './errors.js';
+export { HookRegistry } from './registry.js';
+export { dispatchBeforeSave, dispatchAfterSave, dispatchAfterLoad, dispatchBeforePublish, dispatchAfterPublish, dispatchBeforeUpload, dispatchAfterUpload, } from './dispatch.js';
+export { buildHookContext } from './context.js';
+export { eventFromRegistration, } from './audit-emitter.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,gBAAgB,EAAgC,MAAM,cAAc,CAAA;AAC7E,OAAO,EACL,qBAAqB,GAGtB,MAAM,oBAAoB,CAAA"}

package/dist/hooks/registry.d.ts

@@ -0,0 +1,53 @@
+import type { HookHandler, HookOptions, HookPhase, HookRegistration } from './types.js';
+/**
+ * In-process registry for hook handlers. v1 scope: one instance
+ * per admin process, constructed at boot, sealed after plugin
+ * init resolves. Tests construct their own.
+ */
+export declare class HookRegistry {
+    /**
+     * Per-phase registration arrays. Insertion order = original
+     * registration order; sort happens lazily on `getByPhase()` calls
+     * so concurrent registrations don't pay the sort cost N times.
+     */
+    private readonly storage;
+    /** Stable monotonic counter for tie-breaking equal-priority entries. */
+    private nextSequence;
+    /** Once true, `register()` throws RegistrationAfterInitError. */
+    private sealed;
+    /**
+     * Register a handler for a phase.
+     *
+     * Throws `RegistrationAfterInitError` after `seal()` was called.
+     *
+     * `source` identifies who owns the handler (`'site-local'`,
+     * plugin name, `'built-in'`). Surfaces in audit metadata + error
+     * messages.
+     */
+    register<P extends HookPhase>(phase: P, handler: HookHandler<P>, options?: HookOptions, source?: string): void;
+    /**
+     * Retrieve every registration for a phase in priority order
+     * (lower priority first). Stable: same-priority entries
+     * preserve registration order.
+     *
+     * Returns a fresh array; callers can mutate without affecting
+     * registry state.
+     */
+    getByPhase<P extends HookPhase>(phase: P): ReadonlyArray<HookRegistration<P>>;
+    /**
+     * Total registration count. Used by diagnostics; tests pin via
+     * this rather than reaching into private state.
+     */
+    size(phase?: HookPhase): number;
+    /**
+     * Seal the registry — subsequent registrations throw. Idempotent
+     * (calling twice is a no-op; doesn't unseal).
+     */
+    seal(): void;
+    /**
+     * True after `seal()` has been called. Used by tests + plugin
+     * loader diagnostics.
+     */
+    isSealed(): boolean;
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAKvF;;;;GAIG;AACH,qBAAa,YAAY;IACvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IACxE,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAAI;IACxB,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAQ;IAEtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,SAAS,SAAS,EAC1B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,WAAgB,EACzB,MAAM,GAAE,MAAqB,GAC5B,IAAI;IAkBP;;;;;;;OAOG;IACH,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAkB7E;;;OAGG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM;IAS/B;;;OAGG;IACH,IAAI,IAAI,IAAI;IAIZ;;;OAGG;IACH,QAAQ,IAAI,OAAO;CAGpB"}