gazetta 0.7.0 → 0.8.0

package/dist/auth/types.js

@@ -0,0 +1,60 @@
+/**
+ * Auth + RBAC types — the load-bearing primitives every downstream
+ * foundation (audit, hooks, review-workflow) consumes.
+ *
+ * # Why these types live here
+ *
+ * Gazetta does NOT do authentication itself. Operators put admin
+ * behind upstream auth (Cloudflare Access, oauth2-proxy, Tailscale,
+ * etc.) and Gazetta reads identity from configured request headers.
+ * This module defines the shape of that identity AFTER the upstream
+ * layer has authenticated — what audit records, what hooks see, what
+ * the capability middleware checks.
+ *
+ * # Trust modes
+ *
+ * Each `TrustMode` corresponds to a documented upstream platform.
+ * The auth provider for that mode knows how to extract identity from
+ * that platform's request shape (signed JWT, custom header, etc.).
+ *
+ * # Single role per principal
+ *
+ * Per `design-auth-rbac.md` Q2 lock. Multi-role complexity (precedence
+ * conflicts, role intersection) deferred until concrete operator
+ * demand. Operators who need multi-role today compose custom roles
+ * with the union of needed capabilities.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the type vocabulary; doesn't read or
+ *     write storage; pure data shapes.
+ *   - DIP: downstream consumers (audit, hooks, middleware) depend on
+ *     `Principal` interface, not on which trust mode produced it.
+ *   - ISP: trust modes are a closed enum, not a capability interface
+ *     each provider must implement methods for.
+ */
+/**
+ * Reserved capability prefixes — first segment of a capability name
+ * (`read:pages` → `read`). Plugin-supplied capabilities use plugin-
+ * scoped prefixes (e.g., `@my-org/search:rebuild-index`).
+ */
+export const RESERVED_CAPABILITY_PREFIXES = [
+    'read',
+    'edit',
+    'delete',
+    'publish',
+    'configure',
+    'review',
+    'restore',
+];
+/**
+ * Built-in role aliases — predefined as capability sets. Custom
+ * roles in `site.config.ts admin.auth.roles` declare capabilities
+ * directly.
+ */
+export const BUILT_IN_ROLES = {
+    admin: ['*'],
+    editor: ['read:*', 'edit:*', 'publish:non-production'],
+    viewer: ['read:*'],
+};
+//# sourceMappingURL=types.js.map

package/dist/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAqGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,WAAW;IACX,QAAQ;IACR,SAAS;CACD,CAAA;AAsCV;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAA+D;IACxF,KAAK,EAAE,CAAC,GAAG,CAAC;IACZ,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,wBAAwB,CAAC;IACtD,MAAM,EAAE,CAAC,QAAQ,CAAC;CACnB,CAAA"}

package/dist/cache/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `CacheError` taxonomy per `design-cache.md` Gap 5.
+ *
+ * Two leaf classes today; more land as v2 providers ship and
+ * surface their own failure modes (e.g., Redis transport errors,
+ * Azure Service Bus reconnect failures).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes only. No logging, no retry policy.
+ *   - OCP: new failure classes extend `CacheError`; existing
+ *     handlers continue to catch the base class.
+ *   - LSP: every subclass IS a `CacheError`; `instanceof` checks
+ *     work uniformly.
+ */
+/** Base class for all cache errors. */
+export declare class CacheError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown at admin boot when cache config is invalid (missing env
+ * var for a remote provider, malformed connection string, unknown
+ * provider name). Admin won't start.
+ */
+export declare class CacheConfigurationError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a stored value can't be deserialized. Rare; consumers
+ * typically log + return null rather than propagate.
+ */
+export declare class CacheSchemaError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/cache/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,uCAAuC;AACvC,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,UAAU;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/cache/errors.js

@@ -0,0 +1,44 @@
+/**
+ * `CacheError` taxonomy per `design-cache.md` Gap 5.
+ *
+ * Two leaf classes today; more land as v2 providers ship and
+ * surface their own failure modes (e.g., Redis transport errors,
+ * Azure Service Bus reconnect failures).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes only. No logging, no retry policy.
+ *   - OCP: new failure classes extend `CacheError`; existing
+ *     handlers continue to catch the base class.
+ *   - LSP: every subclass IS a `CacheError`; `instanceof` checks
+ *     work uniformly.
+ */
+/** Base class for all cache errors. */
+export class CacheError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CacheError';
+    }
+}
+/**
+ * Thrown at admin boot when cache config is invalid (missing env
+ * var for a remote provider, malformed connection string, unknown
+ * provider name). Admin won't start.
+ */
+export class CacheConfigurationError extends CacheError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CacheConfigurationError';
+    }
+}
+/**
+ * Thrown when a stored value can't be deserialized. Rare; consumers
+ * typically log + return null rather than propagate.
+ */
+export class CacheSchemaError extends CacheError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CacheSchemaError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cache/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/cache/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,uCAAuC;AACvC,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IAC1B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,UAAU;IACrD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF"}

package/dist/cache/factories.d.ts

@@ -0,0 +1,17 @@
+import type { AdminCache } from './types.js';
+import { type MemoryCacheOptions } from './memory.js';
+/**
+ * Operator-facing cache provider factories. Operators import these into
+ * `site.config.ts` and call them inline at the `cache:` field; the field's
+ * value IS the constructed `AdminCache` instance (Path X — see
+ * `design-provider-config.md`).
+ *
+ * `gazetta.config.ts defaults.cache` is the documented Exception A: it
+ * accepts raw options (not a constructed instance) so each inheriting
+ * site builds its own per-site instance from the same defaults — required
+ * by `design-cache.md` Gap 3 (per-site cache isolation).
+ */
+/** In-process LRU cache. Default 10K entries / 50MB approximate cap. */
+export declare function memoryCache(opts?: MemoryCacheOptions): AdminCache;
+export type { MemoryCacheOptions };
+//# sourceMappingURL=factories.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/cache/factories.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAExE;;;;;;;;;;GAUG;AAEH,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,UAAU,CAErE;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/cache/factories.js

@@ -0,0 +1,17 @@
+import { createMemoryCache } from './memory.js';
+/**
+ * Operator-facing cache provider factories. Operators import these into
+ * `site.config.ts` and call them inline at the `cache:` field; the field's
+ * value IS the constructed `AdminCache` instance (Path X — see
+ * `design-provider-config.md`).
+ *
+ * `gazetta.config.ts defaults.cache` is the documented Exception A: it
+ * accepts raw options (not a constructed instance) so each inheriting
+ * site builds its own per-site instance from the same defaults — required
+ * by `design-cache.md` Gap 3 (per-site cache isolation).
+ */
+/** In-process LRU cache. Default 10K entries / 50MB approximate cap. */
+export function memoryCache(opts = {}) {
+    return createMemoryCache(opts);
+}
+//# sourceMappingURL=factories.js.map

package/dist/cache/factories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.js","sourceRoot":"","sources":["../../src/cache/factories.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAA2B,MAAM,aAAa,CAAA;AAExE;;;;;;;;;;GAUG;AAEH,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,OAA2B,EAAE;IACvD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAA;AAChC,CAAC"}

package/dist/cache/keys.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bump when the shape of cached values changes incompatibly. Old
+ * entries with a mismatched prefix are inaccessible and eventually
+ * evicted by LRU.
+ */
+export declare const CACHE_SCHEMA_VERSION = 1;
+/**
+ * Encode an array of components into a colon-separated cache key.
+ *
+ * Each component is passed through `encodeRefName`:
+ *   - `/` becomes `.` (path-style components round-trip)
+ *   - `.` in input throws (dot is reserved for the slash encoding)
+ *
+ * Examples:
+ *   encodeCacheKey(['pages', 'detail', 'home']) → 'pages:detail:home'
+ *   encodeCacheKey(['pages', 'detail', 'blog/[slug]']) → 'pages:detail:blog.[slug]'
+ *   encodeCacheKey(['pages', 'has.dot']) throws
+ */
+export declare function encodeCacheKey(parts: readonly string[]): string;
+/**
+ * Extract the prefix portion of a key for `invalidatePrefix()`
+ * convenience. Returns the first N components joined by `:`.
+ *
+ * Examples:
+ *   prefixOf('pages:detail:home', 1) → 'pages:'
+ *   prefixOf('pages:detail:home', 2) → 'pages:detail:'
+ *
+ * The trailing colon is included so prefix matches don't accidentally
+ * include `pagesx:...` style siblings — `'pages:'` matches `'pages:detail:home'`
+ * but not `'pages-archived:home'`.
+ */
+export declare function prefixOf(key: string, components: number): string;
+/**
+ * Apply the version + overflow-hash policy to a consumer-encoded key.
+ * Provider-internal — consumers don't see the result; they pass clean
+ * keys to `cache.get/set/invalidate`, and the provider wraps before
+ * storing or looking up.
+ *
+ * Two transforms:
+ *   1. Prepend `{CACHE_SCHEMA_VERSION}:` so a schema bump invalidates
+ *      every entry across the process atomically.
+ *   2. If the wrapped key exceeds `MAX_KEY_LENGTH`, keep everything up
+ *      to the last `:` boundary that fits in `MAX_KEY_LENGTH - 9`
+ *      chars, then append `:{8-char-sha256}`. Prefix-invalidation
+ *      still works on the kept prefix; only the tail is opaque.
+ *
+ * Examples:
+ *   applyKeyPolicy('pages:detail:home') → '1:pages:detail:home'
+ *   applyKeyPolicy(very-long-key) →
+ *     '1:pages:detail:long-prefix-portion:{hash8}'
+ */
+export declare function applyKeyPolicy(consumerKey: string): string;
+/**
+ * Apply the version prefix to a `invalidatePrefix()` argument.
+ * Provider-internal. Distinct from `applyKeyPolicy` because prefixes
+ * are not capped or hashed — `invalidatePrefix('pages:')` should
+ * match every stored `'1:pages:...'` key, not just keys that happen
+ * to fit under `MAX_KEY_LENGTH`. The cap-and-hash policy on `set/get`
+ * keeps long keys lookupable; prefix invalidation operates on the
+ * first chars, which the policy preserves verbatim up to the cap.
+ */
+export declare function applyPrefixPolicy(consumerPrefix: string): string;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAYrC;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA0B1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/cache/keys.js

@@ -0,0 +1,145 @@
+/**
+ * Cache key encoding per `design-cache.md` Q1 + Gap 2.
+ *
+ * Two layers:
+ *   1. Consumer-facing encoder (`encodeCacheKey`): colon-separated
+ *      `{domain}:{op}:{id?}:{dim1}:{dim2}...` with components passed
+ *      through `encodeRefName` (slashes → dots; dots in input throw).
+ *      Same encoding as sidecar filenames; page names like
+ *      `blog/[slug]` round-trip across both surfaces.
+ *   2. Provider-internal policy (`applyKeyPolicy`): prepends the
+ *      cache schema version and caps total length at 255 chars,
+ *      replacing the overflow tail with an 8-char sha256 hash so
+ *      prefix-invalidation still works when the prefix is below the
+ *      cap. Consumers never see the policy-wrapped form.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: encoder owns "consumer key shape"; policy owns "what the
+ *     provider stores." Two concerns, two functions.
+ *   - DIP: consumers call `encodeCacheKey(parts)`; providers call
+ *     `applyKeyPolicy(key)` internally before storing/looking up.
+ *     Neither leaks the version-prefix mechanism to callers.
+ *
+ * # Schema versioning
+ *
+ * `CACHE_SCHEMA_VERSION` is bumped manually when the on-the-wire
+ * shape of cached values changes in a way that makes old entries
+ * unreadable (e.g., a field removed from a summary type). NOT tied
+ * to the package version — patch releases can ship cache-shape
+ * changes; minor releases can be cache-compatible. Manual bumping
+ * keeps the trigger explicit.
+ */
+import { createHash } from 'node:crypto';
+import { encodeRefName } from '../hash.js';
+/**
+ * Bump when the shape of cached values changes incompatibly. Old
+ * entries with a mismatched prefix are inaccessible and eventually
+ * evicted by LRU.
+ */
+export const CACHE_SCHEMA_VERSION = 1;
+/**
+ * Maximum stored key length. 255 matches filesystem-provider key-as-
+ * filename ergonomics for future `FileCache` providers; safely under
+ * Redis's 512MB cap and Azure's 250-char path limits.
+ */
+const MAX_KEY_LENGTH = 255;
+/** sha256 hex prefix length used for overflow hashing. */
+const OVERFLOW_HASH_LENGTH = 8;
+/**
+ * Encode an array of components into a colon-separated cache key.
+ *
+ * Each component is passed through `encodeRefName`:
+ *   - `/` becomes `.` (path-style components round-trip)
+ *   - `.` in input throws (dot is reserved for the slash encoding)
+ *
+ * Examples:
+ *   encodeCacheKey(['pages', 'detail', 'home']) → 'pages:detail:home'
+ *   encodeCacheKey(['pages', 'detail', 'blog/[slug]']) → 'pages:detail:blog.[slug]'
+ *   encodeCacheKey(['pages', 'has.dot']) throws
+ */
+export function encodeCacheKey(parts) {
+    if (parts.length === 0) {
+        throw new Error('encodeCacheKey requires at least one component');
+    }
+    return parts.map(encodeRefName).join(':');
+}
+/**
+ * Extract the prefix portion of a key for `invalidatePrefix()`
+ * convenience. Returns the first N components joined by `:`.
+ *
+ * Examples:
+ *   prefixOf('pages:detail:home', 1) → 'pages:'
+ *   prefixOf('pages:detail:home', 2) → 'pages:detail:'
+ *
+ * The trailing colon is included so prefix matches don't accidentally
+ * include `pagesx:...` style siblings — `'pages:'` matches `'pages:detail:home'`
+ * but not `'pages-archived:home'`.
+ */
+export function prefixOf(key, components) {
+    if (components <= 0) {
+        throw new Error('prefixOf requires components >= 1');
+    }
+    const parts = key.split(':');
+    if (components >= parts.length) {
+        return `${key}:`;
+    }
+    return `${parts.slice(0, components).join(':')}:`;
+}
+/**
+ * Apply the version + overflow-hash policy to a consumer-encoded key.
+ * Provider-internal — consumers don't see the result; they pass clean
+ * keys to `cache.get/set/invalidate`, and the provider wraps before
+ * storing or looking up.
+ *
+ * Two transforms:
+ *   1. Prepend `{CACHE_SCHEMA_VERSION}:` so a schema bump invalidates
+ *      every entry across the process atomically.
+ *   2. If the wrapped key exceeds `MAX_KEY_LENGTH`, keep everything up
+ *      to the last `:` boundary that fits in `MAX_KEY_LENGTH - 9`
+ *      chars, then append `:{8-char-sha256}`. Prefix-invalidation
+ *      still works on the kept prefix; only the tail is opaque.
+ *
+ * Examples:
+ *   applyKeyPolicy('pages:detail:home') → '1:pages:detail:home'
+ *   applyKeyPolicy(very-long-key) →
+ *     '1:pages:detail:long-prefix-portion:{hash8}'
+ */
+export function applyKeyPolicy(consumerKey) {
+    const versioned = `${CACHE_SCHEMA_VERSION}:${consumerKey}`;
+    if (versioned.length <= MAX_KEY_LENGTH)
+        return versioned;
+    // Need to overflow. Reserve OVERFLOW_HASH_LENGTH + 1 (for the
+    // ':' separator) at the tail; cut the prefix at the last ':' that
+    // fits in the remaining budget.
+    const reserve = OVERFLOW_HASH_LENGTH + 1;
+    const budget = MAX_KEY_LENGTH - reserve;
+    // Find the last ':' at or before `budget` so prefix matches still
+    // align with consumer-visible component boundaries.
+    let cut = versioned.lastIndexOf(':', budget);
+    // Always at least the version prefix is present (`1:`); cut > 0
+    // here because versioned.length > MAX_KEY_LENGTH > budget > 1.
+    if (cut <= 0) {
+        // Pathological: no ':' in budget. Hard-cut at budget. Prefix
+        // invalidation degrades to "first N chars" rather than aligning
+        // to component boundaries, but keys this dense are unusual.
+        cut = budget;
+    }
+    const kept = versioned.slice(0, cut);
+    const tail = versioned.slice(cut);
+    const hash = createHash('sha256').update(tail).digest('hex').slice(0, OVERFLOW_HASH_LENGTH);
+    return `${kept}:${hash}`;
+}
+/**
+ * Apply the version prefix to a `invalidatePrefix()` argument.
+ * Provider-internal. Distinct from `applyKeyPolicy` because prefixes
+ * are not capped or hashed — `invalidatePrefix('pages:')` should
+ * match every stored `'1:pages:...'` key, not just keys that happen
+ * to fit under `MAX_KEY_LENGTH`. The cap-and-hash policy on `set/get`
+ * keeps long keys lookupable; prefix invalidation operates on the
+ * first chars, which the policy preserves verbatim up to the cap.
+ */
+export function applyPrefixPolicy(consumerPrefix) {
+    return `${CACHE_SCHEMA_VERSION}:${consumerPrefix}`;
+}
+//# sourceMappingURL=keys.js.map

package/dist/cache/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAErC;;;;GAIG;AACH,MAAM,cAAc,GAAG,GAAG,CAAA;AAE1B,0DAA0D;AAC1D,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAE9B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,KAAwB;IACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;IACnE,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,UAAkB;IACtD,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;IACtD,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,UAAU,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAC/B,OAAO,GAAG,GAAG,GAAG,CAAA;IAClB,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,MAAM,SAAS,GAAG,GAAG,oBAAoB,IAAI,WAAW,EAAE,CAAA;IAC1D,IAAI,SAAS,CAAC,MAAM,IAAI,cAAc;QAAE,OAAO,SAAS,CAAA;IAExD,8DAA8D;IAC9D,kEAAkE;IAClE,gCAAgC;IAChC,MAAM,OAAO,GAAG,oBAAoB,GAAG,CAAC,CAAA;IACxC,MAAM,MAAM,GAAG,cAAc,GAAG,OAAO,CAAA;IAEvC,kEAAkE;IAClE,oDAAoD;IACpD,IAAI,GAAG,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAC5C,gEAAgE;IAChE,+DAA+D;IAC/D,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,6DAA6D;QAC7D,gEAAgE;QAChE,4DAA4D;QAC5D,GAAG,GAAG,MAAM,CAAA;IACd,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACpC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAA;IAC3F,OAAO,GAAG,IAAI,IAAI,IAAI,EAAE,CAAA;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,cAAsB;IACtD,OAAO,GAAG,oBAAoB,IAAI,cAAc,EAAE,CAAA;AACpD,CAAC"}

package/dist/cache/memory.d.ts

@@ -0,0 +1,51 @@
+import type { AdminCache } from './types.js';
+/**
+ * Options for constructing an in-process `MemoryCache`. All fields
+ * optional; defaults are 10,000 entries and 50 MB approximate.
+ *
+ * Lives on the factory signature (rather than as a separate `*Config`
+ * interface in `types.ts`) per Phase 3 of the Path X migration — the
+ * options type is provider-specific construction config, not a
+ * runtime-manifest field.
+ */
+export interface MemoryCacheOptions {
+    /** Max entry count before LRU eviction kicks in. Default 10,000. */
+    maxEntries?: number;
+    /** Approximate max bytes before LRU eviction kicks in. Default 50 MB. */
+    maxBytes?: number;
+    /**
+     * Stable identifier emitted on `InvalidationEvent.source.instance`.
+     * When omitted, resolved from the environment (per
+     * `design-logging.md`):
+     *
+     *   1. `process.env.K_REVISION` — Cloud Run revision name. Per-
+     *      revision, NOT per-instance: pods scaled from the same
+     *      revision share this ID. Useful for revision-level log
+     *      filtering; for per-pod identity on Cloud Run, override
+     *      explicitly via this field from the metadata server.
+     *   2. `os.hostname()` — pod name on K8s (default config), machine
+     *      hostname elsewhere. Reliable across container runtimes
+     *      regardless of whether `process.env.HOSTNAME` is populated.
+     *   3. Random 8-char hex — only reached when hostname returns an
+     *      empty string (rare on real systems).
+     *
+     * Plugin authors writing shared-backing providers (Redis, Azure)
+     * should accept the same option and use the same resolution chain
+     * so log correlation across providers works uniformly.
+     */
+    instance?: string;
+}
+/**
+ * Resolve the instance ID from the environment when the operator
+ * doesn't supply one. Exported for tests; callers should pass through
+ * `MemoryCacheOptions.instance`.
+ */
+export declare function resolveInstanceId(override?: string): string;
+/**
+ * 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 declare function createMemoryCache(config?: MemoryCacheOptions): AdminCache;
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/cache/memory.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,UAAU,EAAiC,MAAM,YAAY,CAAA;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAO3D;AAaD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,kBAAuB,GAAG,UAAU,CA6I7E"}