gazetta 0.7.0 → 0.8.0

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

package/dist/hooks/registry.js

@@ -0,0 +1,139 @@
+/**
+ * `HookRegistry` — priority-sorted, phase-keyed registration store.
+ *
+ * Per design-hooks.md "Composition (Q3 locked)":
+ *
+ *   - Lower priority runs earlier; default 100
+ *   - Same priority resolves to registration order (stable sort)
+ *   - Priority bands (convention only): 0-99 built-in, 100-999
+ *     plugins, 1000+ site-local
+ *
+ * # Why a single registry per process, not per-phase
+ *
+ * Each phase has its own handler signature, but the registry's
+ * job (sort by priority, look up by phase, seal post-init) is
+ * uniform. One class with `Map<HookPhase, HookRegistration[]>`
+ * internally is simpler than seven phase-specific registry
+ * classes and makes "all phases see the same seal" trivially
+ * true.
+ *
+ * # Sealing semantics
+ *
+ * `seal()` flips a flag; any subsequent `register(...)` call
+ * throws `RegistrationAfterInitError`. Per ADR-0009 +
+ * `design-plugins.md`, `buildHooksRegistry({ contributions })`
+ * walks `admin.hooks` factory contributions at boot, registers
+ * each entry, then calls `seal()`. Tests construct an unsealed
+ * registry directly.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: registry owns (a) storage of registrations and (b)
+ *     priority-sorted retrieval. Dispatch is a peer module that
+ *     READS from the registry; doesn't mutate.
+ *   - OCP: adding a new phase extends the type-level union; the
+ *     registry's storage shape (`Map<HookPhase, ...>`) covers
+ *     new entries without code changes.
+ *   - DIP: dispatcher depends on `HookRegistry`'s public surface;
+ *     storage layout is the implementation detail.
+ */
+import { RegistrationAfterInitError } from './errors.js';
+const DEFAULT_PRIORITY = 100;
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * 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 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.
+     */
+    storage = new Map();
+    /** Stable monotonic counter for tie-breaking equal-priority entries. */
+    nextSequence = 0;
+    /** Once true, `register()` throws RegistrationAfterInitError. */
+    sealed = false;
+    /**
+     * 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(phase, handler, options = {}, source = 'site-local') {
+        if (this.sealed) {
+            throw new RegistrationAfterInitError({ source, phase });
+        }
+        const registration = {
+            phase,
+            handler,
+            priority: options.priority ?? DEFAULT_PRIORITY,
+            name: options.name ?? source,
+            timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+            sequence: this.nextSequence++,
+            source,
+        };
+        const list = this.storage.get(phase) ?? [];
+        list.push(registration);
+        this.storage.set(phase, list);
+    }
+    /**
+     * 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(phase) {
+        const list = this.storage.get(phase) ?? [];
+        // Sort a copy so concurrent registrations during iteration
+        // don't reorder the in-place array. Stable sort: tie-break
+        // by sequence preserves registration order for same-priority
+        // entries.
+        //
+        // Cast through `unknown`: each phase-keyed Map slot only
+        // contains registrations matching its key (enforced at
+        // `register()`), but TS conditional types don't propagate
+        // through Map's value variance. The runtime invariant holds.
+        const sorted = [...list].sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.sequence - b.sequence;
+        });
+        return sorted;
+    }
+    /**
+     * Total registration count. Used by diagnostics; tests pin via
+     * this rather than reaching into private state.
+     */
+    size(phase) {
+        if (phase === undefined) {
+            let total = 0;
+            for (const list of this.storage.values())
+                total += list.length;
+            return total;
+        }
+        return this.storage.get(phase)?.length ?? 0;
+    }
+    /**
+     * Seal the registry — subsequent registrations throw. Idempotent
+     * (calling twice is a no-op; doesn't unseal).
+     */
+    seal() {
+        this.sealed = true;
+    }
+    /**
+     * True after `seal()` has been called. Used by tests + plugin
+     * loader diagnostics.
+     */
+    isSealed() {
+        return this.sealed;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/hooks/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAGxD,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAC5B,MAAM,kBAAkB,GAAG,IAAI,CAAA;AAE/B;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACvB;;;;OAIG;IACc,OAAO,GAAuC,IAAI,GAAG,EAAE,CAAA;IACxE,wEAAwE;IAChE,YAAY,GAAG,CAAC,CAAA;IACxB,iEAAiE;IACzD,MAAM,GAAG,KAAK,CAAA;IAEtB;;;;;;;;OAQG;IACH,QAAQ,CACN,KAAQ,EACR,OAAuB,EACvB,UAAuB,EAAE,EACzB,SAAiB,YAAY;QAE7B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,0BAA0B,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QACzD,CAAC;QACD,MAAM,YAAY,GAAwB;YACxC,KAAK;YACL,OAAO;YACP,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,gBAAgB;YAC9C,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,kBAAkB;YAC9C,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE;YAC7B,MAAM;SACP,CAAA;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAC1C,IAAI,CAAC,IAAI,CAAC,YAAgC,CAAC,CAAA;QAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CAAsB,KAAQ;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAC1C,2DAA2D;QAC3D,2DAA2D;QAC3D,6DAA6D;QAC7D,WAAW;QACX,EAAE;QACF,yDAAyD;QACzD,uDAAuD;QACvD,0DAA0D;QAC1D,6DAA6D;QAC7D,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACrC,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;gBAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAA;YAC7D,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAA;QAChC,CAAC,CAAC,CAAA;QACF,OAAO,MAAuD,CAAA;IAChE,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,KAAiB;QACpB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,KAAK,GAAG,CAAC,CAAA;YACb,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;gBAAE,KAAK,IAAI,IAAI,CAAC,MAAM,CAAA;YAC9D,OAAO,KAAK,CAAA;QACd,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACpB,CAAC;IAED;;;OAGG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;CACF"}

package/dist/hooks/storage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Read-only storage view for HookContext.
+ *
+ * Per design-hooks.md "Mutation rules" #6: hooks can read but not
+ * write storage. Writes go through the operation that fired the
+ * hook (mutating the returned payload). Prevents hook-vs-operation
+ * write races.
+ *
+ * # Why a separate type, not a Proxy at this stage
+ *
+ * Cut 1 ships TYPES only. The dispatcher (Cut 2) constructs the
+ * read-only view at HookContext build time — design open question 2
+ * recommends a Proxy implementation for less code duplication, but
+ * the TYPE we expose to handlers is a structural subset of
+ * `StorageProvider`. Whether the runtime uses Proxy filtering or a
+ * dedicated wrapper class is the dispatcher's concern; the type
+ * stays narrow either way.
+ *
+ * # Why narrow, not extending StorageProvider
+ *
+ *   - SRP: hooks don't need write APIs. Exposing them via Pick<>
+ *     would require hooks to know which methods are forbidden.
+ *   - LSP: a hook receiving `ReadOnlyStorageProvider` can't acci-
+ *     dentally pass it to a function expecting full `StorageProvider`
+ *     and have a runtime mutation succeed.
+ *   - Forward-compatible: future read-only methods (e.g., `stat()`)
+ *     extend this type; write methods stay on the full
+ *     `StorageProvider`.
+ */
+import type { DirEntry, ByteRange } from '../types.js';
+/**
+ * Read-only subset of `StorageProvider`. Hooks consuming this type
+ * cannot write — `writeFile`, `writeBytes`, `writeStream`, `mkdir`,
+ * `rm` are all absent.
+ */
+export interface ReadOnlyStorageProvider {
+    readFile(path: string): Promise<string>;
+    readDir(path: string): Promise<DirEntry[]>;
+    exists(path: string): Promise<boolean>;
+    readBytes(path: string): Promise<Uint8Array>;
+    readStream(path: string, range?: ByteRange): Promise<ReadableStream<Uint8Array>>;
+}
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/hooks/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEtD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAA;CACjF"}

package/dist/hooks/storage.js

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

package/dist/hooks/storage.js.map

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