gazetta 0.6.0 → 0.8.0

package/dist/history.d.ts

@@ -56,6 +56,17 @@ export interface HistoryRetention {
     /** Keep at most N most-recent revisions. Default: 50. Oldest evicted. */
     maxRevisions?: number;
 }
+/**
+ * Content carried in a revision snapshot — either UTF-8 text (for JSON
+ * manifests, YAML, HTML, CSS, JS) or raw bytes (asset bytes, variants,
+ * fonts). The provider hashes either via SHA-256 over the raw bytes
+ * (text encoded as UTF-8 first), so dedup works uniformly: identical
+ * text and identical bytes share a blob.
+ *
+ * Per Q9 lock, one blob store, mixed content. The public `readBlob`
+ * always returns bytes; callers that expect text decode on read.
+ */
+export type BlobContent = string | Uint8Array;
 /** Input to `recordRevision` — metadata plus the current content tree. */
 export interface RevisionInput {
     operation: RevisionOperation;
@@ -68,16 +79,14 @@ export interface RevisionInput {
     /** For rollback/restore: the revision id this one restored from. */
     restoredFrom?: string;
     /**
-     * Full content tree snapshot at this revision: `itemPath → content string`.
-     * Content is stored as UTF-8 text — covers every item type Gazetta
-     * tracks today (JSON manifests, YAML, HTML, CSS, JS). Binary assets
-     * (images, fonts) would need a separate mechanism; revisit when those
-     * become first-class.
+     * Full content tree snapshot at this revision: `itemPath → content`.
+     * Content is `string | Uint8Array` — text and binary first-class
+     * (asset bytes, variants, fonts; per Q9 lock).
      *
      * Unchanged items should carry identical content across calls so the
      * provider can dedupe via content-addressing.
      */
-    items: Map<string, string>;
+    items: Map<string, BlobContent>;
 }
 /**
  * Uniform history API. Implemented on top of any StorageProvider — reads
@@ -100,8 +109,17 @@ export interface HistoryProvider {
     listRevisions(limit?: number): Promise<Revision[]>;
     /** Read a revision's full manifest (metadata + snapshot). */
     readRevision(id: string): Promise<RevisionManifest>;
-    /** Read a content blob by hash (e.g. to restore an item's state). */
-    readBlob(hash: string): Promise<string>;
+    /**
+     * Read a content blob by hash. Returns raw bytes — callers that
+     * expect text (page/fragment manifests, site.config.ts) decode UTF-8 on
+     * receipt. Callers that expect binary (asset bytes, variants) use
+     * the bytes as-is.
+     *
+     * The pre-step-20 signature returned `string`. The widening to
+     * `Uint8Array` is a foundation contract change; existing string
+     * consumers must wrap with `new TextDecoder().decode(bytes)`.
+     */
+    readBlob(hash: string): Promise<Uint8Array>;
     /**
      * Delete a revision and its manifest. Orphaned blobs are garbage-
      * collected by the implementation (lazy or immediate, adapter's choice).

package/dist/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAA;AAE/D,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,iBAAiB,CAAA;IAC5B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;OASG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEvD,gEAAgE;IAChE,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAElD,6DAA6D;IAC7D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAEnD,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEvC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAA;AAE/D,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAE7C,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,iBAAiB,CAAA;IAC5B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEvD,gEAAgE;IAChE,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAElD,6DAA6D;IAC7D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAEnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE3C;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C"}

package/dist/hooks/audit-emitter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Hook firing audit emitter — the seam between the hooks
+ * dispatcher and the audit recorder.
+ *
+ * Per design-hooks.md "Audit events" + design-audit.md's locked
+ * `action: 'hook-fired'` + `outcome: 'hook-cancelled' | 'timeout'`
+ * extensions:
+ *
+ *   - Every hook firing emits an audit event with hook name +
+ *     priority + phase + durationMs.
+ *   - `outcome` reflects the hook firing's result:
+ *       'success'         — completed within timeout
+ *       'hook-cancelled'  — `before*` threw (or non-cancellation
+ *                            error wrapped as HookCancellation)
+ *       'timeout'         — per-handler timeout fired before
+ *                            resolve
+ *   - One firing = one event; correlation across firings in the
+ *     same operation is via shared `requestId` (audit + log).
+ *
+ * # Why a callback, not a direct audit dependency
+ *
+ * dispatch.ts must stay independent of audit-context wiring so
+ * the same code path runs in tests (no audit) and in production
+ * (full audit). The callback shape lets the caller decide
+ * whether/how to record. When the callback is undefined, dispatch
+ * is silent.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the emitter contract; doesn't construct
+ *     audit providers, doesn't run hooks.
+ *   - DIP: dispatch depends on the `HookFiringEmitter` callback;
+ *     callers (admin-api wiring) supply an implementation that
+ *     forwards to `c.var.audit.record(...)`.
+ */
+import type { HookContext, HookPhase, HookRegistration } from './types.js';
+/**
+ * One audit-emittable hook firing event. Captured by the
+ * dispatcher and forwarded to the caller-supplied emitter.
+ */
+export interface HookFiringEvent {
+    /** Phase the hook fired in. */
+    phase: HookPhase;
+    /** Hook name (from registration meta or file basename). */
+    hookName: string;
+    /** Source identity ('site-local', plugin name, 'built-in'). */
+    source: string;
+    /** Priority at registration time. */
+    priority: number;
+    /**
+     * Outcome of the firing. `'success'` for handlers that resolved
+     * within the timeout window; `'hook-cancelled'` for `before*`
+     * handlers that threw; `'timeout'` for handlers that exceeded
+     * their per-handler timeout.
+     */
+    outcome: 'success' | 'hook-cancelled' | 'timeout';
+    /** Wall-clock duration (ms) from invocation to resolve / throw. */
+    durationMs: number;
+    /** Triggering request's HookContext (carries actor, requestId, etc.). */
+    ctx: HookContext;
+}
+/**
+ * Caller-supplied audit emitter. Invoked synchronously per hook
+ * firing; consumer typically forwards to `c.var.audit.record(...)`.
+ *
+ * The emitter MUST NOT throw — failures isolate to the dispatcher
+ * via try/catch. Consumers wanting to surface emit failures use
+ * their own logging.
+ */
+export type HookFiringEmitter = (event: HookFiringEvent) => void | Promise<void>;
+/** Helper for registrations — extracts the metadata the emitter needs. */
+export declare function eventFromRegistration<P extends HookPhase>(reg: HookRegistration<P>, ctx: HookContext, outcome: HookFiringEvent['outcome'], durationMs: number): HookFiringEvent;
+//# sourceMappingURL=audit-emitter.d.ts.map

package/dist/hooks/audit-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-emitter.d.ts","sourceRoot":"","sources":["../../src/hooks/audit-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE1E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,KAAK,EAAE,SAAS,CAAA;IAChB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;IACd,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAA;IACjD,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,GAAG,EAAE,WAAW,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEhF,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,SAAS,EACvD,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,EACxB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,EACnC,UAAU,EAAE,MAAM,GACjB,eAAe,CAUjB"}

package/dist/hooks/audit-emitter.js

@@ -0,0 +1,13 @@
+/** Helper for registrations — extracts the metadata the emitter needs. */
+export function eventFromRegistration(reg, ctx, outcome, durationMs) {
+    return {
+        phase: reg.phase,
+        hookName: reg.name,
+        source: reg.source,
+        priority: reg.priority,
+        outcome,
+        durationMs,
+        ctx,
+    };
+}
+//# sourceMappingURL=audit-emitter.js.map

package/dist/hooks/audit-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-emitter.js","sourceRoot":"","sources":["../../src/hooks/audit-emitter.ts"],"names":[],"mappings":"AAyEA,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CACnC,GAAwB,EACxB,GAAgB,EAChB,OAAmC,EACnC,UAAkB;IAElB,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,IAAI;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,OAAO;QACP,UAAU;QACV,GAAG;KACJ,CAAA;AACH,CAAC"}

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