gazetta 0.7.0 → 0.8.0

package/dist/cache/memory.js

@@ -0,0 +1,204 @@
+/**
+ * `MemoryCache` — process-internal `AdminCache` provider. v1 default.
+ *
+ * Per-instance scope; multi-instance-correct via independence (each
+ * instance receives SSE invalidation for its own writes via Cut 4's
+ * bridge). LRU eviction at configured caps; stats track operational
+ * counters.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the in-memory provider. Stats, LRU,
+ *     subscribe handling all live here because they're one cohesive
+ *     "memory cache" concern; splitting would fragment.
+ *   - LSP: substitutable for any future `AdminCache` provider via
+ *     the contract test helper (Cut 10).
+ *   - DIP: consumers depend on `AdminCache`, not `createMemoryCache`.
+ *
+ * # subscribe() — local emission per Cut 4
+ *
+ * The contract evolved during Cut 4. The original framing was "events
+ * from other instances," with single-instance providers as honest
+ * no-ops. Real consumers (the L4→L6 server-to-browser cascade per
+ * `design-cache.md` "Offline composition") need server-side L4
+ * invalidations to reach browser-side L6 caches. From the browser's
+ * POV the server IS another instance, so the right contract is
+ * "events from any source" — including local ones.
+ *
+ * `invalidate()` and `invalidatePrefix()` fire to subscribers with
+ * the **input** key/prefix (the consumer-facing form passed to the
+ * method). The `applyKeyPolicy` version prefix and overflow-hash are
+ * provider-internal storage details — they don't leak to event
+ * payloads.
+ *
+ * `forSite()` filters events whose prefix doesn't belong to the
+ * wrapping site (cross-site events from a future shared backing
+ * service); the SSE bridge subscribes to the forSite wrapper and
+ * sees consumer-facing prefixes.
+ */
+import { randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { applyKeyPolicy, applyPrefixPolicy } from './keys.js';
+/**
+ * Resolve the instance ID from the environment when the operator
+ * doesn't supply one. Exported for tests; callers should pass through
+ * `MemoryCacheOptions.instance`.
+ */
+export function resolveInstanceId(override) {
+    if (override)
+        return override;
+    const k = process.env.K_REVISION;
+    if (k)
+        return k;
+    const h = hostname();
+    if (h)
+        return h;
+    return randomBytes(4).toString('hex');
+}
+/** Default cap when operator config doesn't override. */
+const DEFAULT_MAX_ENTRIES = 10_000;
+/** Default cap when operator config doesn't override. */
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024; // 50 MB
+/**
+ * Build a `MemoryCache` instance. Internal factory — kept public for
+ * tests and advanced wiring. Operators use the operator-facing
+ * `memoryCache()` factory exported from `gazetta` (Path X), which
+ * delegates here.
+ */
+export function createMemoryCache(config = {}) {
+    const maxEntries = config.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES;
+    const instance = resolveInstanceId(config.instance);
+    // Map insertion order is the LRU order; access touches it via
+    // delete+set on hit (Map.set on existing key preserves order, so
+    // the explicit delete-then-set is required to bump recency).
+    const entries = new Map();
+    let totalBytes = 0;
+    // Cross-instance event subscribers. Cut 2 never invokes these
+    // (no SSE bridge yet); Cut 4 wires emit on incoming SSE messages.
+    const subscribers = new Set();
+    // Operational counters surfaced via stats() per design-cache.md Q5.
+    let hits = 0;
+    let misses = 0;
+    let evictions = 0;
+    let lastInvalidation;
+    function evictOldestIfOverCap() {
+        while (entries.size > maxEntries || totalBytes > maxBytes) {
+            const oldestKey = entries.keys().next().value;
+            if (oldestKey === undefined)
+                return;
+            const entry = entries.get(oldestKey);
+            entries.delete(oldestKey);
+            if (entry)
+                totalBytes -= entry.bytes;
+            evictions++;
+        }
+    }
+    /**
+     * Notify subscribers of an invalidation. `prefix` is the **input**
+     * form (what the consumer passed to invalidate / invalidatePrefix);
+     * the version-prefix + overflow-hash applied by `applyKeyPolicy` is
+     * a storage encoding detail and never reaches event payloads.
+     *
+     * Subscribers that throw shouldn't poison sibling subscribers —
+     * each notification is wrapped in a try/catch. The error is
+     * swallowed (subscribe is observational; failing-open keeps the
+     * invalidation honest from the caller's POV).
+     */
+    function emit(prefix) {
+        if (subscribers.size === 0)
+            return;
+        const event = {
+            prefix,
+            source: { instance, timestamp: new Date().toISOString() },
+        };
+        for (const handler of subscribers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Subscriber faults must not interfere with the
+                // invalidation that triggered them. Silently swallow.
+            }
+        }
+    }
+    return {
+        async get(key) {
+            const wrapped = applyKeyPolicy(key);
+            const entry = entries.get(wrapped);
+            if (!entry) {
+                misses++;
+                return null;
+            }
+            // LRU touch — delete + re-insert moves to end (most recent).
+            entries.delete(wrapped);
+            entries.set(wrapped, entry);
+            hits++;
+            return entry.value;
+        },
+        async set(key, value, _opts) {
+            // TTL is part of the AdminCache contract but MemoryCache v1
+            // doesn't honor it — eviction is LRU-only. A future TTL pass
+            // (or a TTL-aware provider) handles expiry.
+            const wrapped = applyKeyPolicy(key);
+            const bytes = JSON.stringify(value).length;
+            const existing = entries.get(wrapped);
+            if (existing) {
+                totalBytes -= existing.bytes;
+                entries.delete(wrapped);
+            }
+            entries.set(wrapped, { value, bytes });
+            totalBytes += bytes;
+            evictOldestIfOverCap();
+        },
+        async invalidate(key) {
+            const wrapped = applyKeyPolicy(key);
+            const entry = entries.get(wrapped);
+            if (!entry)
+                return;
+            entries.delete(wrapped);
+            totalBytes -= entry.bytes;
+            emit(key);
+        },
+        async invalidatePrefix(prefix) {
+            const wrapped = applyPrefixPolicy(prefix);
+            let cleared = 0;
+            for (const [key, entry] of entries) {
+                if (key.startsWith(wrapped)) {
+                    entries.delete(key);
+                    totalBytes -= entry.bytes;
+                    cleared++;
+                }
+            }
+            lastInvalidation = {
+                prefix,
+                at: new Date().toISOString(),
+                source: 'local',
+            };
+            // Emit even when cleared === 0 — subscribers (notably the
+            // L4→L6 SSE bridge) want every invalidation intent, not just
+            // those that hit something locally. A consumer's L6 cache may
+            // hold an entry the server's L4 already evicted via LRU.
+            emit(prefix);
+            return cleared;
+        },
+        subscribe(handler) {
+            subscribers.add(handler);
+            return () => {
+                subscribers.delete(handler);
+            };
+        },
+        async stats() {
+            return {
+                hits,
+                misses,
+                size: entries.size,
+                instance,
+                evictions,
+                bytesApproximate: totalBytes,
+                lastInvalidation,
+            };
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/cache/memory.js.map

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

package/dist/cache/per-site.d.ts

@@ -0,0 +1,22 @@
+import type { AdminCache } from './types.js';
+/**
+ * Wrap an `AdminCache` with per-site key scoping. Every key written,
+ * read, or invalidated through the returned cache is transparently
+ * prefixed with `site:{encoded-name}:`.
+ *
+ * Examples (with siteName = 'main'):
+ *   inner.set('site:main:pages:home', value)  ← stored
+ *   wrapped.set('pages:home', value)          ← what consumers see
+ *
+ * Prefix invalidation works through the wrapping uniformly:
+ *   wrapped.invalidatePrefix('pages:')        ← consumer call
+ *   inner.invalidatePrefix('site:main:pages:') ← actual mechanism
+ *
+ * The `subscribe()` handler receives events with the unwrapped
+ * (consumer-facing) prefix. Events for OTHER sites' invalidations
+ * reaching the same backing service are filtered out (they have a
+ * different `site:{other}:` prefix); cross-site events would be a
+ * leak otherwise.
+ */
+export declare function forSite(inner: AdminCache, siteName: string): AdminCache;
+//# sourceMappingURL=per-site.d.ts.map

package/dist/cache/per-site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-site.d.ts","sourceRoot":"","sources":["../../src/cache/per-site.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,UAAU,EAAiC,MAAM,YAAY,CAAA;AAS3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CA6DvE"}

package/dist/cache/per-site.js

@@ -0,0 +1,114 @@
+/**
+ * Per-site cache scoping per `design-cache.md` Gap 3.
+ *
+ * Wraps an `AdminCache` instance with a site-name prefix on every
+ * key. Two motivations:
+ *
+ *   1. **Future shared backing services** (Redis, Azure cache when
+ *      they ship) — a single Redis cluster shared across N Site
+ *      processes needs key isolation so site A's cache writes don't
+ *      collide with site B's. Per-site key prefix solves this at the
+ *      wrapper layer; the backing provider is unaware.
+ *
+ *   2. **Multi-site deployments evolving over time** — pre-1.0
+ *      Gazetta locks single-Site-per-process, so today there's no
+ *      collision risk in-process. But a future configuration could
+ *      legitimately host two Sites in one process; `forSite` makes
+ *      that change additive.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "scope an AdminCache to a site name."
+ *     Provider mechanics live in `memory.ts`; key encoding lives in
+ *     `keys.ts`. Three concerns, three files.
+ *   - OCP: a future `forPlugin(cache, pluginName)` wrapper composes
+ *     identically; no change to consumers.
+ *   - LSP: `forSite(cache, name)` returns an `AdminCache`. Any
+ *     caller depending on the interface keeps working.
+ *   - ISP: consumers see `AdminCache`, never the wrapping mechanism.
+ *   - DIP: `loadSite()` wraps once at construction; consumers depend
+ *     on `site.cache: AdminCache`.
+ */
+import { encodeRefName } from '../hash.js';
+/**
+ * Reserved prefix for the per-site key namespace. Documented as
+ * a built-in per `design-cache.md` Q1's "Reserved prefixes" rule —
+ * plugins must not write keys under `site:`.
+ */
+const SITE_NAMESPACE = 'site';
+/**
+ * Wrap an `AdminCache` with per-site key scoping. Every key written,
+ * read, or invalidated through the returned cache is transparently
+ * prefixed with `site:{encoded-name}:`.
+ *
+ * Examples (with siteName = 'main'):
+ *   inner.set('site:main:pages:home', value)  ← stored
+ *   wrapped.set('pages:home', value)          ← what consumers see
+ *
+ * Prefix invalidation works through the wrapping uniformly:
+ *   wrapped.invalidatePrefix('pages:')        ← consumer call
+ *   inner.invalidatePrefix('site:main:pages:') ← actual mechanism
+ *
+ * The `subscribe()` handler receives events with the unwrapped
+ * (consumer-facing) prefix. Events for OTHER sites' invalidations
+ * reaching the same backing service are filtered out (they have a
+ * different `site:{other}:` prefix); cross-site events would be a
+ * leak otherwise.
+ */
+export function forSite(inner, siteName) {
+    if (!siteName) {
+        throw new Error('forSite: siteName must be a non-empty string');
+    }
+    const encodedName = encodeRefName(siteName);
+    const sitePrefix = `${SITE_NAMESPACE}:${encodedName}:`;
+    function wrap(key) {
+        return `${sitePrefix}${key}`;
+    }
+    /**
+     * Strip the `site:{name}:` prefix from a stored key for handoff to
+     * a consumer subscriber. Returns null when the key isn't owned by
+     * this site (shared backing service receiving another site's event).
+     */
+    function unwrap(key) {
+        if (!key.startsWith(sitePrefix))
+            return null;
+        return key.slice(sitePrefix.length);
+    }
+    return {
+        async get(key) {
+            return inner.get(wrap(key));
+        },
+        async set(key, value, opts) {
+            return inner.set(wrap(key), value, opts);
+        },
+        async invalidate(key) {
+            return inner.invalidate(wrap(key));
+        },
+        async invalidatePrefix(prefix) {
+            return inner.invalidatePrefix(wrap(prefix));
+        },
+        subscribe(handler) {
+            // Forward only events that belong to this site; rewrite the
+            // prefix to the consumer-facing form before firing the handler.
+            return inner.subscribe(event => {
+                const unwrapped = unwrap(event.prefix);
+                if (unwrapped === null)
+                    return;
+                handler({ ...event, prefix: unwrapped });
+            });
+        },
+        async stats() {
+            // Stats are global to the underlying provider — there's no
+            // honest way to slice them per-site without scanning every
+            // entry, which defeats the cache. Surface the inner stats
+            // verbatim; operators interpret them with the knowledge that
+            // shared backing services pool stats across all sites.
+            const innerStats = inner.stats;
+            if (!innerStats) {
+                return { hits: 0, misses: 0, size: 0 };
+            }
+            return innerStats.call(inner);
+        },
+    };
+}
+//# sourceMappingURL=per-site.js.map

package/dist/cache/per-site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-site.js","sourceRoot":"","sources":["../../src/cache/per-site.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C;;;;GAIG;AACH,MAAM,cAAc,GAAG,MAAM,CAAA;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,OAAO,CAAC,KAAiB,EAAE,QAAgB;IACzD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAA;IACjE,CAAC;IACD,MAAM,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;IAC3C,MAAM,UAAU,GAAG,GAAG,cAAc,IAAI,WAAW,GAAG,CAAA;IAEtD,SAAS,IAAI,CAAC,GAAW;QACvB,OAAO,GAAG,UAAU,GAAG,GAAG,EAAE,CAAA;IAC9B,CAAC;IAED;;;;OAIG;IACH,SAAS,MAAM,CAAC,GAAW;QACzB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,CAAA;QAC5C,OAAO,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IACrC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,GAAG,CAAI,GAAW;YACtB,OAAO,KAAK,CAAC,GAAG,CAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,IAAuB;YACzD,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QAC1C,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,GAAW;YAC1B,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACpC,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,MAAc;YACnC,OAAO,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;QAC7C,CAAC;QAED,SAAS,CAAC,OAA2C;YACnD,4DAA4D;YAC5D,gEAAgE;YAChE,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;gBAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;gBACtC,IAAI,SAAS,KAAK,IAAI;oBAAE,OAAM;gBAC9B,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;YAC1C,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,KAAK;YACT,2DAA2D;YAC3D,2DAA2D;YAC3D,0DAA0D;YAC1D,6DAA6D;YAC7D,uDAAuD;YACvD,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAA;YAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;YACxC,CAAC;YACD,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC/B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/cache/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * `AdminCache` — provider-substitutable interface for the L4 cache
+ * tier (admin / origin server). One concrete implementation ships in
+ * v1: `MemoryCache` (Cut 2). Reserved for v2: `RedisCache`,
+ * `AzureCache`, `FileCache`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the cache contract (interface, stats,
+ *     invalidation event). Nothing else lives here.
+ *   - OCP: new providers implement `AdminCache` and slot into the
+ *     factory (Cut 9). No existing module changes.
+ *   - LSP: every provider honors the same contract. Substitutable
+ *     in tests via the `adminCacheContractTests` helper (Cut 10).
+ *   - ISP: callers depend on this interface, not on a specific
+ *     provider's mechanism (Map, Redis pub/sub, Service Bus).
+ *   - DIP: feature code calls `cache.get(key)` etc.; the seam to
+ *     concrete providers is the factory.
+ *
+ * Locked invariants per `design-cache.md`:
+ *   - Cached values MUST be JSON-serializable (no functions, no
+ *     Symbols, no top-level Maps/Sets) — required for L4 → L6
+ *     handoff via IndexedDB / localStorage.
+ *   - `subscribe()` delivers invalidation events from any source
+ *     (local OR cross-instance — Cut 4 contract evolution). The
+ *     `event.source.instance` field discriminates origin so
+ *     subscribers can filter as needed.
+ *   - `invalidatePrefix()` is best-effort with a time cap (~100ms
+ *     default per design-cache.md PWA-responsiveness principle);
+ *     un-cleared entries clear at TTL or on next invalidation.
+ */
+/**
+ * The cache contract. All providers implement this; consumers depend
+ * only on the interface.
+ */
+export interface AdminCache {
+    /** Get cached value or null on miss. */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set value with optional TTL (seconds). Provider may ignore TTL
+     * if it doesn't support expiry; `MemoryCache` ignores TTL in v1
+     * (LRU-only eviction).
+     */
+    set<T>(key: string, value: T, opts?: {
+        ttl?: number;
+    }): Promise<void>;
+    /** Invalidate one key. */
+    invalidate(key: string): Promise<void>;
+    /** Invalidate all keys matching a prefix. Returns count cleared. */
+    invalidatePrefix(prefix: string): Promise<number>;
+    /**
+     * Subscribe to invalidation events from any source. Returns disposer.
+     *
+     * Local invalidations (this instance's `invalidate` /
+     * `invalidatePrefix` calls) AND cross-instance invalidations
+     * (delivered via SSE bridge or shared backing service) both fire
+     * the handler. Discriminate via `event.source.instance` —
+     * subscribers that only care about cross-instance events can filter
+     * out their own.
+     *
+     * The L4→L6 server-to-browser cascade is the load-bearing consumer:
+     * server-side `invalidatePrefix('pages:')` fires to a subscribed
+     * SSE route, which forwards the event to connected browser admin
+     * clients, which invalidate their L6 caches. From the browser's
+     * POV the server IS another instance, so "events from any source"
+     * is the right contract.
+     *
+     * Event payloads carry the **consumer-facing** prefix (the form
+     * passed to the invalidate call). Provider-internal storage
+     * details (version prefix, overflow hash, per-site scope) don't
+     * leak into the event.
+     *
+     * **No replay on reconnect.** Subscribers (notably the SSE bridge
+     * forwarding to browsers) that lose their connection get no
+     * server-side replay of events they missed during the gap. The
+     * contract: on reconnect, treat your own cached state as
+     * potentially stale and reset (re-fetch from source). The L6 admin
+     * cache (`design-offline.md`) follows this rule via full reset on
+     * reconnect.
+     *
+     * **Handlers should be synchronous.** Providers fire subscribers
+     * with `handler(event)` — without `await`. TypeScript's `void`
+     * return type accepts async handlers for ergonomic reasons, but
+     * the cache won't await them; rejections from a returned Promise
+     * become unhandled. Subscribers needing async work should enqueue
+     * synchronously and process asynchronously elsewhere (e.g., the
+     * SSE bridge pushes to a buffer + drains from a stream loop).
+     */
+    subscribe(handler: (event: InvalidationEvent) => void): () => void;
+    /** Stats for diagnostics. Optional — not every provider exposes. */
+    stats?(): Promise<CacheStats>;
+}
+/**
+ * Event delivered to `subscribe()` handlers when another instance
+ * invalidates a cache prefix. Source identifies the originating
+ * instance for cross-instance correlation.
+ */
+export interface InvalidationEvent {
+    /** Key or prefix that was invalidated. */
+    prefix: string;
+    /** Originating instance + wall-clock timestamp (ISO 8601). */
+    source: {
+        instance: string;
+        timestamp: string;
+    };
+}
+/**
+ * Cache stats — minimum required + provider-specific extras allowed.
+ *
+ * The required floor (hits, misses, size) lets the
+ * `/api/system/cache/stats` route (Cut 7) report a useful baseline
+ * across all providers. Optional fields (errors, evictions,
+ * bytesApproximate, oldestEntryAt, lastInvalidation,
+ * subscribeReconnects) ship as the relevant provider tracks them.
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    /** Entry count. */
+    size: number;
+    /**
+     * Identity of the reporting cache instance — same value as
+     * `InvalidationEvent.source.instance` for events emitted by this
+     * provider. Operators querying `/api/system/cache/stats` in
+     * multi-instance deployments use this to know which pod / revision
+     * answered (the load balancer's choice can vary between requests).
+     * Optional because some providers may not have a meaningful
+     * identity (e.g., a no-op stub).
+     */
+    instance?: string;
+    errors?: number;
+    evictions?: number;
+    bytesApproximate?: number;
+    oldestEntryAt?: string;
+    lastInvalidation?: {
+        prefix: string;
+        at: string;
+        source: string;
+    };
+    subscribeReconnects?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACtC;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrE,0BAA0B;IAC1B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,oEAAoE;IACpE,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAClE,oEAAoE;IACpE,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAChD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B"}

package/dist/cache/types.js

@@ -0,0 +1,33 @@
+/**
+ * `AdminCache` — provider-substitutable interface for the L4 cache
+ * tier (admin / origin server). One concrete implementation ships in
+ * v1: `MemoryCache` (Cut 2). Reserved for v2: `RedisCache`,
+ * `AzureCache`, `FileCache`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the cache contract (interface, stats,
+ *     invalidation event). Nothing else lives here.
+ *   - OCP: new providers implement `AdminCache` and slot into the
+ *     factory (Cut 9). No existing module changes.
+ *   - LSP: every provider honors the same contract. Substitutable
+ *     in tests via the `adminCacheContractTests` helper (Cut 10).
+ *   - ISP: callers depend on this interface, not on a specific
+ *     provider's mechanism (Map, Redis pub/sub, Service Bus).
+ *   - DIP: feature code calls `cache.get(key)` etc.; the seam to
+ *     concrete providers is the factory.
+ *
+ * Locked invariants per `design-cache.md`:
+ *   - Cached values MUST be JSON-serializable (no functions, no
+ *     Symbols, no top-level Maps/Sets) — required for L4 → L6
+ *     handoff via IndexedDB / localStorage.
+ *   - `subscribe()` delivers invalidation events from any source
+ *     (local OR cross-instance — Cut 4 contract evolution). The
+ *     `event.source.instance` field discriminates origin so
+ *     subscribers can filter as needed.
+ *   - `invalidatePrefix()` is best-effort with a time cap (~100ms
+ *     default per design-cache.md PWA-responsiveness principle);
+ *     un-cleared entries clear at TTL or on next invalidation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/cli/archive.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `gazetta archive <subcommand>` runner — Cut 13 of the soft-delete
+ * implementation plan.
+ *
+ * Subcommands (per design-soft-delete.md Q13 L4 lock):
+ *   archive list [--kind=page|fragment]
+ *   archive purge <name> [--kind=page|fragment] [--force]
+ *   archive restore <name> [--kind=page|fragment]
+ *   archive rename <oldname> <newname> [--kind=page|fragment] [--no-keep-alias]
+ *
+ * Implementation strategy: the CLI invokes the same admin-api routes
+ * the admin UI uses, via `app.request()` against an in-process
+ * `createAdminApp`. This reuses every primitive (audit, capability,
+ * cache invalidation, sidecar writes) and avoids parallel CLI-only
+ * code paths that could drift from the route handlers.
+ *
+ * Cron-friendly output: structured per-line stdout, one line per
+ * archive in `list`, single result line per item in
+ * purge/restore/rename. Non-zero exit on any failure. NO_COLOR / non-
+ * TTY suppresses ANSI codes via the shared sink.
+ *
+ * SOLID lenses:
+ *   - SRP: one module per concern. Subcommand dispatch lives here;
+ *     archive primitives stay in `admin-api/routes/archive.ts` +
+ *     `rename.ts`. CLI only orchestrates I/O + dispatch.
+ *   - OCP: adding a subcommand = new handler + entry in dispatch map.
+ *   - DIP: depends on admin-api `app.request` interface, not on
+ *     individual route implementations.
+ */
+import type { OutputSink } from './assets-cli.js';
+export interface ArchiveSubcommandInput {
+    /** All argv after the `archive` keyword. e.g. `['list']`, `['purge', 'old-page']`. */
+    args: readonly string[];
+    /** Project site directory. */
+    siteDir: string;
+    /** Optional target name override. */
+    targetName?: string;
+    /** Sink for output. Defaults to `consoleSink`. */
+    sink?: OutputSink;
+    /** Test hook: skip `process.exit` on bad input. */
+    exitOnError?: (code: number) => void;
+}
+export declare function runArchiveSubcommand(input: ArchiveSubcommandInput): Promise<void>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/cli/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/cli/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGjD,MAAM,WAAW,sBAAsB;IACrC,sFAAsF;IACtF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mDAAmD;IACnD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC;AAMD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEvF"}