gazetta 0.7.0 → 0.8.0

package/dist/alt/route-handler.d.ts

@@ -0,0 +1,56 @@
+import type { GazettaManifest, SiteManifest, StorageProvider, TargetConfig } from '../types.js';
+/**
+ * Result of orchestration. The route handler maps these to HTTP
+ * responses uniformly:
+ *
+ *   - `'unavailable'` → 503 (no adapter / unsupported MIME)
+ *   - `'failed'`      → 502 (adapter threw)
+ *   - `'not-found'`   → 404 (asset doesn't exist)
+ *   - `'ok'`          → 200 (with body, including possible refused: true)
+ *
+ * `provider` is exposed on `ok` so the route handler can include it
+ * in the audit event (per testing-plan.md gap #4 — refusal forensics).
+ */
+export type SuggestAltResult = {
+    kind: 'ok';
+    suggestion: {
+        text: string;
+        refused: boolean;
+        refusalReason: string | null;
+    };
+    provider: string;
+} | {
+    kind: 'unavailable';
+    message: string;
+} | {
+    kind: 'failed';
+    message: string;
+} | {
+    kind: 'not-found';
+    message: string;
+};
+export interface SuggestAltOptions {
+    /** Asset name (from `:name` URL param). */
+    name: string;
+    /** Where assets live in storage (typically `'assets'`). */
+    assetsRoot: string;
+    /** Storage provider for the resolved target. */
+    storage: StorageProvider;
+    /** Site manifest carrying `ai:` and `altText:` blocks. */
+    site: Pick<SiteManifest, 'ai' | 'altText'>;
+    /** Resolved target config (target-level overrides applied via factory). */
+    target: Pick<TargetConfig, 'altText'> | undefined;
+    /** Optional gazetta-level manifest; first rung of the three-rung chain. */
+    gazetta?: Pick<GazettaManifest, 'ai' | 'altText'>;
+    /** Locale to generate alt in. Defaults to 'en' upstream. */
+    locale: string;
+    /** Optional AbortSignal forwarded to the adapter. */
+    signal?: AbortSignal;
+}
+/**
+ * Run an alt-text suggestion for an existing asset. Pure orchestration
+ * — no HTTP, no logging, no streaming. Returns a structured result
+ * that the route handler maps to HTTP.
+ */
+export declare function suggestAltForAsset(opts: SuggestAltOptions): Promise<SuggestAltResult>;
+//# sourceMappingURL=route-handler.d.ts.map

package/dist/alt/route-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/alt/route-handler.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAK/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC5E,QAAQ,EAAE,MAAM,CAAA;CACjB,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1C,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAA;IACxB,0DAA0D;IAC1D,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GAAG,SAAS,CAAA;IACjD,2EAA2E;IAC3E,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,SAAS,CAAC,CAAA;IACjD,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgG3F"}

package/dist/alt/route-handler.js

@@ -0,0 +1,122 @@
+/**
+ * Route-level orchestration for `POST /api/assets/:name/suggest-alt`.
+ *
+ * This module owns the wiring between the admin-api HTTP layer and the
+ * alt-text task: loads the asset manifest, reads bytes from storage,
+ * builds the suggester, runs it, returns the response body.
+ *
+ * Lives outside `admin-api/routes/assets.ts` so route handlers stay
+ * thin (HTTP concerns only) and the orchestration is unit-testable
+ * without spinning up Hono.
+ *
+ * # SOLID
+ *
+ *   - SRP: this module owns "given a name + locale + storage + site,
+ *     return a suggestion or a typed error". No HTTP concerns; no
+ *     adapter construction (delegates to `buildAltAdapter`).
+ *   - DIP: depends on `StorageProvider` + `SiteManifest` + factory
+ *     functions, never on a specific provider. Tests substitute via
+ *     the same abstractions.
+ *   - OCP: adding response fields (e.g., locale fallback used) is one
+ *     additional field on the returned shape; no changes to the route.
+ */
+import { readManifest } from '../assets/manifest.js';
+import { assetStoragePaths } from '../assets/asset-paths.js';
+import { AssetManifestNotFoundError } from '../assets/errors.js';
+import { buildAltAdapter } from './factory.js';
+import { resolveAltConfig } from './config.js';
+import { createAltSuggester } from './suggester.js';
+/**
+ * Run an alt-text suggestion for an existing asset. Pure orchestration
+ * — no HTTP, no logging, no streaming. Returns a structured result
+ * that the route handler maps to HTTP.
+ */
+export async function suggestAltForAsset(opts) {
+    // Resolve config first to validate the feature is configured for
+    // this site/target. No adapter construction yet — cheap.
+    const resolved = resolveAltConfig(opts.site, opts.target, opts.gazetta);
+    if (!resolved) {
+        return {
+            kind: 'unavailable',
+            message: 'AI alt-text is not configured for this site. Add an `altText:` block to site.config.ts.',
+        };
+    }
+    // Load the asset manifest. Wrapped in try/catch so we surface
+    // missing-asset as a typed result rather than letting the asset
+    // domain's typed error escape into the route handler's
+    // pattern-match list.
+    let manifest;
+    try {
+        manifest = await readManifest(opts.storage, opts.assetsRoot, opts.name);
+    }
+    catch (err) {
+        if (err instanceof AssetManifestNotFoundError) {
+            return { kind: 'not-found', message: `Asset '${opts.name}' not found` };
+        }
+        // Other asset-domain errors bubble — they indicate misconfiguration
+        // (e.g., corrupt manifest), which the route handler maps via
+        // `respondWithAssetError`.
+        throw err;
+    }
+    // Build the adapter via the factory. Returns nullAltAdapter when no
+    // provider is configured — the suggester's `available()` check
+    // surfaces this as `false` and we map to 503.
+    const adapter = buildAltAdapter(opts.site, opts.target, opts.gazetta);
+    const suggester = createAltSuggester({ adapter });
+    if (!suggester.available(manifest.mime)) {
+        return {
+            kind: 'unavailable',
+            message: `AI alt-text adapter unavailable. Check that '${resolved.provider.name}' credentials are valid and that the asset MIME (${manifest.mime}) is supported.`,
+        };
+    }
+    // Resolve the bytes path for the default-locale variant. v1.5
+    // suggests against the asset's default bytes regardless of the
+    // requested locale — locale only affects the prompt language. Future
+    // locale-specific bytes (e.g., a French-text-overlay version) could
+    // route through the override slices; deferred until a real consumer
+    // requests it.
+    const paths = assetStoragePaths(opts.assetsRoot, manifest);
+    let bytes;
+    try {
+        bytes = await opts.storage.readBytes(paths.defaultBytes);
+    }
+    catch (err) {
+        return {
+            kind: 'failed',
+            message: `Could not read asset bytes for '${opts.name}': ${err instanceof Error ? err.message : 'unknown error'}`,
+        };
+    }
+    // Optional poster bytes for animated images — the analyzer extracts
+    // them at upload time and writes a manifest path; we forward to the
+    // suggester so vision-prep skips re-rasterization.
+    let posterBytes;
+    if (manifest.poster) {
+        try {
+            posterBytes = await opts.storage.readBytes(`${opts.assetsRoot}/${manifest.poster}`);
+        }
+        catch {
+            // Poster missing or unreadable — fall through to source bytes.
+            // Vision-prep handles the rasterize-source path.
+            posterBytes = undefined;
+        }
+    }
+    const suggestion = await suggester.suggest({
+        bytes,
+        mime: manifest.mime,
+        hash: manifest.hash,
+        locale: opts.locale,
+        maxImageEdge: resolved.maxImageEdge,
+        posterBytes,
+    }, opts.signal);
+    if (suggestion === null) {
+        // The suggester returns null on capability miss, abort, or any
+        // typed AI error. We've already verified availability above, so
+        // here the cause is most likely a transport failure.
+        return {
+            kind: 'failed',
+            message: `Alt-text generation failed. Check ${resolved.provider} status and retry.`,
+        };
+    }
+    return { kind: 'ok', suggestion, provider: resolved.provider.name };
+}
+//# sourceMappingURL=route-handler.js.map

package/dist/alt/route-handler.js.map

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

package/dist/alt/suggester.d.ts

@@ -0,0 +1,57 @@
+import { AIAdapterFailedError, AIAdapterUnavailableError, AIInvalidResponseError } from '../ai/errors.js';
+import { type AltSuggestion, type AltTextAdapter } from './adapter.js';
+export interface SuggestInput {
+    /** Source asset bytes. */
+    bytes: Uint8Array;
+    /** Source MIME from manifest. */
+    mime: string;
+    /** For diagnostics (logging); not used for memoization in v1.5. */
+    hash: string;
+    /** Target locale for the description. Default 'en'. */
+    locale?: string;
+    /**
+     * For animated images: the analyzer-extracted first-frame poster
+     * bytes. The suggester forwards to `prepareForVision` which uses
+     * them directly (no re-rasterization).
+     */
+    posterBytes?: Uint8Array;
+    /**
+     * Per-call max-edge override for vision-prep. Defaults to the
+     * `prepareForVision` default (768).
+     */
+    maxImageEdge?: number;
+    /** Soft length cap; default 125. */
+    maxChars?: number;
+}
+/**
+ * The orchestration interface. UI components and route handlers
+ * depend on this; the concrete `createAltSuggester` builds an
+ * implementation backed by an adapter.
+ */
+export interface AltSuggester {
+    /**
+     * True when the wrapped adapter is configured AND supports the
+     * given MIME. UI uses this to decide whether to render AI affordances.
+     */
+    available(mime: string): boolean;
+    /**
+     * Run the alt-text suggestion. Returns the structured result from
+     * the adapter (which may have `refused: true`), or null when the
+     * call couldn't complete (unavailable, transport error, abort).
+     */
+    suggest(input: SuggestInput, signal?: AbortSignal): Promise<AltSuggestion | null>;
+}
+export interface CreateAltSuggesterOptions {
+    adapter: AltTextAdapter;
+}
+/**
+ * Build a suggester wrapping the given adapter. Pure factory — no I/O,
+ * no env-var reads. Caller (the route handler or test setup) supplies
+ * a fully-constructed adapter.
+ *
+ * Tests substitute by passing `nullAltAdapter`, a recording mock, or
+ * a real adapter with an msw-mocked transport.
+ */
+export declare function createAltSuggester(opts: CreateAltSuggesterOptions): AltSuggester;
+export { AIAdapterFailedError, AIAdapterUnavailableError, AIInvalidResponseError };
+//# sourceMappingURL=suggester.d.ts.map

package/dist/alt/suggester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggester.d.ts","sourceRoot":"","sources":["../../src/alt/suggester.ts"],"names":[],"mappings":"AAiDA,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAW,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAElH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAA;AAGrB,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,KAAK,EAAE,UAAU,CAAA;IACjB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;CAClF;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,cAAc,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,YAAY,CAoEhF;AAOD,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAA"}

package/dist/alt/suggester.js

@@ -0,0 +1,133 @@
+/**
+ * `AltSuggester` — orchestration between callers and adapters.
+ *
+ * The suggester is **stateless**. No memoization, no per-replica cache.
+ * Multi-replica admin correctness > per-replica optimization. If
+ * caching ever earns its keep operationally, it lands as a decorator
+ * (`CachedAltSuggester`) wrapping this base — additive, multi-replica
+ * correct via shared storage.
+ *
+ * # What the suggester owns
+ *
+ *   - Build typed `AltRequest` from caller input + defaults
+ *   - Compose the prompt via `composePrompt(request, policies)`
+ *   - Call `prepareForVision` to resize bytes before adapter call
+ *   - Forward `AbortSignal` to adapter
+ *   - Return `AltSuggestion | null` — null = call failed (adapter
+ *     unavailable, error, etc.)
+ *
+ * # What it doesn't own
+ *
+ *   - HTTP / SDK transport (adapter)
+ *   - Provider-specific request shape (adapter)
+ *   - Refusal detection (adapter calls `detectRefusal` and constructs
+ *     the structured `AltSuggestion`; suggester forwards the result)
+ *   - Cache (none; future decorator)
+ *   - UI concerns (consumer)
+ *
+ * # Returning null vs. throwing
+ *
+ * The suggester's contract: returns `AltSuggestion | null`. Null
+ * means "call couldn't complete" — the adapter doesn't support the
+ * MIME, or threw a transport error, or was canceled. Consumers treat
+ * null uniformly (don't auto-fill).
+ *
+ * Refusals (model said no but we got a response) come back as
+ * `AltSuggestion` with `refused: true`. Different from null — the
+ * suggester DID complete, the model just declined. Consumers can
+ * surface `refusalReason` to the author.
+ *
+ * # SOLID
+ *
+ *   - SRP: this module owns one concern (orchestration of the
+ *     adapter call from caller input to result/null)
+ *   - OCP: caching, retry, throttling all land as decorators wrapping
+ *     `AltSuggester` — none requires changing this module
+ *   - DIP: depends on `AltTextAdapter` (abstract), uses `prepareForVision`
+ *     and `composePrompt` (utilities); no knowledge of any provider
+ */
+import { composePrompt } from '../ai/compose-prompt.js';
+import { AIAdapterFailedError, AIAdapterUnavailableError, AIError, AIInvalidResponseError } from '../ai/errors.js';
+import { prepareForVision } from '../ai/vision-prep.js';
+import { DEFAULT_ALT_REQUEST, } from './adapter.js';
+import { DEFAULT_ALT_PROMPT_POLICIES } from './prompt-policies.js';
+/**
+ * Build a suggester wrapping the given adapter. Pure factory — no I/O,
+ * no env-var reads. Caller (the route handler or test setup) supplies
+ * a fully-constructed adapter.
+ *
+ * Tests substitute by passing `nullAltAdapter`, a recording mock, or
+ * a real adapter with an msw-mocked transport.
+ */
+export function createAltSuggester(opts) {
+    const { adapter } = opts;
+    return {
+        available(mime) {
+            return adapter.supports(mime);
+        },
+        async suggest(input, signal) {
+            // Capability check first — adapter may be null-adapter or may
+            // not support this MIME. Either way: nothing to attempt.
+            if (!adapter.supports(input.mime))
+                return null;
+            // Bail on already-aborted signals before doing any work.
+            if (signal?.aborted)
+                return null;
+            // Build the typed request from input + defaults.
+            const request = {
+                ...DEFAULT_ALT_REQUEST,
+                locale: input.locale ?? DEFAULT_ALT_REQUEST.locale,
+                maxChars: input.maxChars ?? DEFAULT_ALT_REQUEST.maxChars,
+            };
+            // Compose prompt and prepare bytes — both pure, both idempotent.
+            const prompt = composePrompt(request, DEFAULT_ALT_PROMPT_POLICIES);
+            let prepared;
+            try {
+                prepared = await prepareForVision({
+                    bytes: input.bytes,
+                    mime: input.mime,
+                    posterBytes: input.posterBytes,
+                    maxEdge: input.maxImageEdge,
+                });
+            }
+            catch {
+                // Vision-prep failure (sharp couldn't decode): treat as
+                // unavailable. The asset's bytes are presumably corrupt or
+                // an unexpected format — not worth calling the model on
+                // garbage.
+                return null;
+            }
+            const generateInput = {
+                bytes: prepared.bytes,
+                mime: prepared.mime,
+                request,
+                prompt,
+            };
+            try {
+                return await adapter.generate(generateInput, signal);
+            }
+            catch (err) {
+                // AbortSignal-induced rejection: surface as null (call canceled).
+                if (signal?.aborted)
+                    return null;
+                // AI errors are expected failure modes — caller maps null →
+                // user-facing toast. Re-throwing would force every caller to
+                // try/catch around `suggest`, which is exactly what the
+                // suggester contract abstracts away.
+                if (err instanceof AIError)
+                    return null;
+                // Non-AI errors (programmer bugs, unexpected exceptions)
+                // bubble — the suggester doesn't swallow these, since they
+                // indicate a real problem worth surfacing.
+                throw err;
+            }
+        },
+    };
+}
+// Re-export AI error types so callers/tests can pattern-match without
+// importing from `ai/`. Useful during the brief window where adapter
+// implementations distinguish unavailable vs. failed vs. invalid-
+// response; in practice route handlers only need the suggester's
+// null/non-null result.
+export { AIAdapterFailedError, AIAdapterUnavailableError, AIInvalidResponseError };
+//# sourceMappingURL=suggester.js.map

package/dist/alt/suggester.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggester.js","sourceRoot":"","sources":["../../src/alt/suggester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAClH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAKL,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAA;AAiDlE;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAExB,OAAO;QACL,SAAS,CAAC,IAAY;YACpB,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,KAAmB,EAAE,MAAoB;YACrD,8DAA8D;YAC9D,yDAAyD;YACzD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YAE9C,yDAAyD;YACzD,IAAI,MAAM,EAAE,OAAO;gBAAE,OAAO,IAAI,CAAA;YAEhC,iDAAiD;YACjD,MAAM,OAAO,GAAe;gBAC1B,GAAG,mBAAmB;gBACtB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,mBAAmB,CAAC,MAAM;gBAClD,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,mBAAmB,CAAC,QAAQ;aACzD,CAAA;YAED,iEAAiE;YACjE,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAA;YAElE,IAAI,QAA6C,CAAA;YACjD,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,OAAO,EAAE,KAAK,CAAC,YAAY;iBAC5B,CAAC,CAAA;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,wDAAwD;gBACxD,2DAA2D;gBAC3D,wDAAwD;gBACxD,WAAW;gBACX,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,aAAa,GAAqB;gBACtC,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,OAAO;gBACP,MAAM;aACP,CAAA;YAED,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;YACtD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,kEAAkE;gBAClE,IAAI,MAAM,EAAE,OAAO;oBAAE,OAAO,IAAI,CAAA;gBAEhC,4DAA4D;gBAC5D,6DAA6D;gBAC7D,wDAAwD;gBACxD,qCAAqC;gBACrC,IAAI,GAAG,YAAY,OAAO;oBAAE,OAAO,IAAI,CAAA;gBAEvC,yDAAyD;gBACzD,2DAA2D;gBAC3D,2CAA2C;gBAC3C,MAAM,GAAG,CAAA;YACX,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,sEAAsE;AACtE,qEAAqE;AACrE,kEAAkE;AAClE,iEAAiE;AACjE,wBAAwB;AACxB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAA"}

package/dist/app.js

@@ -4,7 +4,7 @@ import { resolvePage } from './resolver.js';
 import { renderPage } from './renderer.js';
 export async function createApp(siteDir, storage) {
     const app = new Hono();
-    const site = await loadSite({ siteDir, storage });
+    const site = await loadSite({ siteDir, storage, manifest: { name: '(app)' } });
     for (const [pageName, page] of site.pages) {
         app.get(page.route, async (c) => {
             const resolved = await resolvePage(pageName, site);

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAe,EAAE,OAAwB;IACvE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IAEjD,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAC,CAAC,EAAC,EAAE;YAC5B,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAClD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAA;YACtD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAe,EAAE,OAAwB;IACvE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAA;IAE9E,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAC,CAAC,EAAC,EAAE;YAC5B,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAClD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAA;YACtD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/archive-aliases.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Archive-alias-targets sidecar binding for the generic dep-sidecars
+ * module.
+ *
+ * Answers "which archived items have `aliasOf === X`?" via the same
+ * per-edge sidecar shape as `asset-refs` and `fragment-deps`:
+ *
+ *   `{root}/.gazetta/alias-targets/{X}/{encoded-source-item}`
+ *
+ * Without this index, the purge handler (Cut 5) would have to walk
+ * every page + fragment manifest on every purge attempt to find
+ * aliases pointing at the target. At the 5K-page envelope per
+ * `design-scale.md`, that's a ~30s walk on real cloud storage —
+ * unacceptable for an interactive admin operation. The sidecar
+ * makes it a single `readDir` (~5ms).
+ *
+ * Per `team-preferences.md` rule 24: "Validate every primitive
+ * against the 5K-page envelope" — the sidecar IS the perf design.
+ *
+ * # Lifecycle
+ *
+ * - Save handler: when an item is archived with `aliasOf` set,
+ *   `rebuildArchiveAliases` writes the sidecar at
+ *   `.gazetta/alias-targets/{aliasTarget}/{item}`.
+ * - Save handler: when the same item is unarchived OR has its
+ *   `aliasOf` field changed, the diff drops the old target's
+ *   sidecar and adds the new target's sidecar.
+ * - Delete/purge handler: pass `newManifest = null` to tear down
+ *   the sidecar for the item being purged.
+ * - Cross-target: source-and-target consistent (same shape on
+ *   both); the publish flow propagates the `.gazetta/` namespace.
+ *
+ * Per Q3's flatten-on-rename lock: aliases never form chains.
+ * `aliasOf` always points at a live item (or at a missing item,
+ * which the `dangling-alias` validator surfaces). The sidecar
+ * stores ONE target per archive — the relation's `extract`
+ * returns either `{aliasOf}` or `∅`.
+ */
+import type { ContentRoot } from './content-root.js';
+import { type DepRelation, type ItemRef, type ManifestLike } from './dep-sidecars.js';
+/**
+ * The archive-aliases relation.
+ *
+ * Extracts the alias target from a manifest. The set is at most
+ * one element — Q3 flatten guarantees one-hop aliases. A live
+ * manifest (or an archived-without-alias manifest) yields the
+ * empty set, which means no sidecars are written for it.
+ */
+export declare const ARCHIVE_ALIASES: DepRelation;
+/**
+ * Read every archived item that aliases this target. Returns
+ * `ItemRef[]`; the caller maps to `(kind, name)` for error bodies
+ * (e.g. the purge-blocked 409 response from `design-soft-delete.md`
+ * Q4).
+ */
+export declare function readArchivesAliasing(contentRoot: ContentRoot, targetName: string): Promise<ItemRef[]>;
+/**
+ * Apply the alias-targets diff for one item's manifest change.
+ *
+ * Pass the pre-save manifest as `oldManifest` and the post-save
+ * manifest as `newManifest`. The diff drops sidecars for any
+ * removed alias targets and writes sidecars for any added targets.
+ *
+ * Cases:
+ *   - Live → archive(aliasOf=X)         : write `.gazetta/alias-targets/X/{item}`
+ *   - Live → archive(no aliasOf)         : no I/O
+ *   - Archive(X) → archive(Y)            : remove X's sidecar, write Y's
+ *   - Archive(X) → archive(no aliasOf)   : remove X's sidecar
+ *   - Archive(X) → live                  : remove X's sidecar
+ *   - Archive(X) → null (purge)          : remove X's sidecar
+ *   - Live → null (purge)                : no I/O
+ */
+export declare function rebuildArchiveAliases(contentRoot: ContentRoot, item: ItemRef, oldManifest: ManifestLike | null, newManifest: ManifestLike | null): Promise<void>;
+/**
+ * Apply a pre-computed diff (used in tests + cases where the
+ * caller has the alias names already).
+ */
+export declare function applyArchiveAliasesDiff(contentRoot: ContentRoot, item: ItemRef, oldTargets: ReadonlySet<string>, newTargets: ReadonlySet<string>): Promise<void>;
+//# sourceMappingURL=archive-aliases.d.ts.map

package/dist/archive-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-aliases.d.ts","sourceRoot":"","sources":["../src/archive-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,YAAY,EAIlB,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,WAY7B,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAErG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,YAAY,GAAG,IAAI,EAChC,WAAW,EAAE,YAAY,GAAG,IAAI,GAC/B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/archive-aliases.js

@@ -0,0 +1,60 @@
+import { applyDepDiff, rebuildItemDeps, readDepsFor, } from './dep-sidecars.js';
+/**
+ * The archive-aliases relation.
+ *
+ * Extracts the alias target from a manifest. The set is at most
+ * one element — Q3 flatten guarantees one-hop aliases. A live
+ * manifest (or an archived-without-alias manifest) yields the
+ * empty set, which means no sidecars are written for it.
+ */
+export const ARCHIVE_ALIASES = {
+    rootName: 'alias-targets',
+    extract: (manifest) => {
+        // Cast: ComponentManifest is the full shape; ManifestLike is
+        // the dep-sidecars module's loose type. The `archived` and
+        // `aliasOf` fields aren't part of `ManifestLike`'s declaration,
+        // so the cast names what we're looking at.
+        const m = manifest;
+        if (m.archived !== true)
+            return new Set();
+        if (typeof m.aliasOf !== 'string' || m.aliasOf.length === 0)
+            return new Set();
+        return new Set([m.aliasOf]);
+    },
+};
+/**
+ * Read every archived item that aliases this target. Returns
+ * `ItemRef[]`; the caller maps to `(kind, name)` for error bodies
+ * (e.g. the purge-blocked 409 response from `design-soft-delete.md`
+ * Q4).
+ */
+export function readArchivesAliasing(contentRoot, targetName) {
+    return readDepsFor(ARCHIVE_ALIASES, contentRoot, targetName);
+}
+/**
+ * Apply the alias-targets diff for one item's manifest change.
+ *
+ * Pass the pre-save manifest as `oldManifest` and the post-save
+ * manifest as `newManifest`. The diff drops sidecars for any
+ * removed alias targets and writes sidecars for any added targets.
+ *
+ * Cases:
+ *   - Live → archive(aliasOf=X)         : write `.gazetta/alias-targets/X/{item}`
+ *   - Live → archive(no aliasOf)         : no I/O
+ *   - Archive(X) → archive(Y)            : remove X's sidecar, write Y's
+ *   - Archive(X) → archive(no aliasOf)   : remove X's sidecar
+ *   - Archive(X) → live                  : remove X's sidecar
+ *   - Archive(X) → null (purge)          : remove X's sidecar
+ *   - Live → null (purge)                : no I/O
+ */
+export function rebuildArchiveAliases(contentRoot, item, oldManifest, newManifest) {
+    return rebuildItemDeps(ARCHIVE_ALIASES, contentRoot, item, oldManifest, newManifest);
+}
+/**
+ * Apply a pre-computed diff (used in tests + cases where the
+ * caller has the alias names already).
+ */
+export function applyArchiveAliasesDiff(contentRoot, item, oldTargets, newTargets) {
+    return applyDepDiff(ARCHIVE_ALIASES, contentRoot, item, oldTargets, newTargets);
+}
+//# sourceMappingURL=archive-aliases.js.map

package/dist/archive-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-aliases.js","sourceRoot":"","sources":["../src/archive-aliases.ts"],"names":[],"mappings":"AAwCA,OAAO,EAIL,YAAY,EACZ,eAAe,EACf,WAAW,GACZ,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,QAAQ,EAAE,eAAe;IACzB,OAAO,EAAE,CAAC,QAAsB,EAAE,EAAE;QAClC,6DAA6D;QAC7D,2DAA2D;QAC3D,gEAAgE;QAChE,2CAA2C;QAC3C,MAAM,CAAC,GAAG,QAAsC,CAAA;QAChD,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI;YAAE,OAAO,IAAI,GAAG,EAAU,CAAA;QACjD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,GAAG,EAAU,CAAA;QACrF,OAAO,IAAI,GAAG,CAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;IACrC,CAAC;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAwB,EAAE,UAAkB;IAC/E,OAAO,WAAW,CAAC,eAAe,EAAE,WAAW,EAAE,UAAU,CAAC,CAAA;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAwB,EACxB,IAAa,EACb,WAAgC,EAChC,WAAgC;IAEhC,OAAO,eAAe,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAwB,EACxB,IAAa,EACb,UAA+B,EAC/B,UAA+B;IAE/B,OAAO,YAAY,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAA;AACjF,CAAC"}

package/dist/archive-helpers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Archive predicates + alias resolution helpers per design-soft-delete.md.
+ *
+ * Pure functions over manifest data. No I/O. The render pipeline + admin
+ * routes consume these instead of inlining `manifest.archived === true`
+ * checks (SRP — archive semantics in one place).
+ *
+ * Archive state lives on the manifest itself (Q1 lock — manifest field,
+ * not sidecar). Aliasing is a runtime concern — the resolver follows
+ * `aliasOf` for archived items with the field set; throws ARCHIVED_NO_ALIAS
+ * for archived items without (Q2 F1 split).
+ *
+ * Q3 flatten-on-rename guarantees aliases never point at other archives —
+ * one-hop only. The recursion limit + cycle detection in
+ * `resolveFragmentArchiveAlias` are defensive: if external manifest
+ * mutation produces a chain (git pull, hand edit), we still terminate.
+ */
+import type { ComponentManifest } from './types.js';
+/** True when the manifest is archived (and not a non-archived archived: false). */
+export declare function isArchived(manifest: {
+    archived?: boolean;
+}): boolean;
+/**
+ * Returns the alias target name when the manifest is archived AND has
+ * `aliasOf` set; null in any other case (live manifest, or archived
+ * without alias).
+ *
+ * The caller distinguishes "live" from "archived without alias" via
+ * `isArchived(manifest)` — both states return null here, but the runtime
+ * behavior differs (live = render normally; archived-no-alias = throw).
+ */
+export declare function aliasTarget(manifest: {
+    archived?: boolean;
+    aliasOf?: string;
+}): string | null;
+/**
+ * Error thrown by `resolveFragmentArchiveAlias` when an archived fragment
+ * has no `aliasOf` field. Caller (renderer / worker) decides UX:
+ *
+ *   - Renderer: surface as render-time error (per Q2 F1 split)
+ *   - Validator (P1): warn at save / background / pre-publish
+ *   - Worker: emit 410 Gone on the page that referenced this fragment
+ *
+ * Distinct error class so callers can `instanceof`-check without
+ * pattern-matching messages.
+ */
+export declare class ArchivedNoAliasError extends Error {
+    readonly fragmentName: string;
+    constructor(fragmentName: string, contextPath?: string);
+}
+/**
+ * Resolve a fragment ref through the alias chain. Returns the live
+ * fragment name to use for the actual lookup.
+ *
+ * - Live fragment → returns the original name unchanged
+ * - Archived fragment with `aliasOf: X` → recurses to resolve X
+ * - Archived fragment without `aliasOf` → throws ArchivedNoAliasError
+ * - Alias chain longer than MAX_ALIAS_HOPS → throws (data-corruption guard)
+ * - Cycle (A → B → A) → throws (data-corruption guard)
+ *
+ * The `lookupFragment` callback decouples this helper from the
+ * `Site.fragments` / `Site.fragmentLocales` map shape — the resolver
+ * passes whichever lookup strategy applies for the active locale.
+ *
+ * Returns null when the resolved name doesn't exist as a fragment
+ * (the caller's lookup returned null at some point in the chain) —
+ * caller surfaces "fragment not found" with their own context.
+ */
+export declare function resolveFragmentArchiveAlias(fragmentName: string, lookupFragment: (name: string) => ComponentManifest | null, contextPath?: string): {
+    resolvedName: string;
+    manifest: ComponentManifest;
+} | null;
+//# sourceMappingURL=archive-helpers.d.ts.map

package/dist/archive-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-helpers.d.ts","sourceRoot":"","sources":["../src/archive-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAG7F;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBAEjB,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CASvD;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,IAAI,EAC1D,WAAW,CAAC,EAAE,MAAM,GACnB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAAG,IAAI,CAkC9D"}