gazetta 0.6.0 → 0.8.0

package/dist/index.js

@@ -16,23 +16,66 @@ export { loadSite } from './site-loader.js';
 export { allPageEntries, allFragmentEntries } from './site-loader.js';
 export { loadTemplate, invalidateTemplate, invalidateAllTemplates } from './template-loader.js';
 export { scopeHtml, scopeCss, hashPath } from './scope.js';
-// Storage providers
+// Storage provider factories — operator-facing (Path X). Operators import
+// these into `site.config.ts` and call them inline at the `storage:` field.
+// Cloud SDK peer deps load lazily on first method call so sites that don't
+// use a given provider don't pay the install cost.
+export { filesystemStorage, r2Storage, s3Storage, azureBlobStorage, } from './providers/factories.js';
+// Internal storage provider factories — kept public for tests and advanced
+// wiring (mocking with pre-resolved options, etc.). Operators should use the
+// operator-facing factories above.
 export { createFilesystemProvider } from './providers/filesystem.js';
-export { createAzureBlobProvider } from './providers/azure-blob.js';
-export { createS3Provider } from './providers/s3.js';
-export { createR2RestProvider } from './providers/r2.js';
+// Transform adapter factories — operator-facing (Path X). Operators import
+// these into `site.config.ts` and call them inline at the `transforms:` field.
+export { sharpAdapter, cloudflareAdapter } from './transforms/factories.js';
+// Internal transform-adapter factories — kept public for tests + advanced wiring.
+export { createSharpAdapter, createCloudflareAdapter, defaultSharpAdapter, } from './transforms/index.js';
+// Cache provider factories — operator-facing (Path X). Operators import
+// these into `site.config.ts` and call them inline at the `cache:` field.
+// Per the single-Site-per-process invariant (CONTEXT.md), gazetta-level
+// `defaults.cache` accepts the same factory result; each process gets a
+// fresh instance from re-evaluating `gazetta.config.ts`.
+export { memoryCache } from './cache/factories.js';
+// Internal cache provider factories — kept public for tests + advanced wiring.
+export { createMemoryCache } from './cache/memory.js';
+export { DeployAuthError, DeployConfigError, DeployContentError, DeployError, DeployTransportError, } from './deploy/index.js';
+export { cloudflareWorkersDeploy, } from './deploy/index.js';
+// AI provider factories — operator-facing (Path X). Operators import
+// these into `site.config.ts` / `gazetta.config.ts` and call them inline:
+//   const anthropic = anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! })
+//   ai: { provider: anthropic, model: 'claude-haiku-4-5' }
+// Provider transports are reusable across tasks (alt-text today; future
+// translation, summarization). Per-task config (model, systemPrompt,
+// maxTokens) lives in data-literal blocks the resolver feeds to
+// `provider.altText({...})` at boot.
+export { anthropicProvider } from './alt/anthropic.js';
+export { openaiProvider } from './alt/openai.js';
+export { ollamaProvider } from './alt/ollama.js';
+export { PROVIDER_DEFAULT_MODELS } from './ai/provider.js';
+// Internal AI factories — kept public for tests + advanced wiring.
+export { createAnthropicAltAdapter } from './alt/anthropic.js';
+export { createOpenAIAltAdapter } from './alt/openai.js';
+export { createOllamaAltAdapter } from './alt/ollama.js';
 // Targets
-export { createStorageProvider, createTargetRegistry } from './targets.js';
-// Bootstrap helpers — read site.yaml, build registry, derive SourceContext
+export { createTargetRegistry } from './targets.js';
+// Bootstrap helpers — load site.config.ts, build registry, derive SourceContext
 export { bootstrapFromSiteYaml, buildSourceContext } from './cli/bootstrap.js';
 // Server
 export { createServer } from './serve.js';
 // Publish
 export { publishItems, resolveDependencies } from './publish.js';
-export { publishPageRendered, publishPageStatic, publishFragmentRendered, publishSiteManifest, publishFragmentIndex, publishFragmentWithPurge, publishPageWithPurge, } from './publish-rendered.js';
+export { publishPageRendered, publishPageStatic, publishFragmentRendered, publishSiteManifest, publishDepIndices, } from './publish-rendered.js';
 // Format helpers
 export { format } from './formats.js';
 // ESI assembly (for edge workers and servers)
 export { assembleEsi, parseCacheComment, splitFragment, findEsiPaths } from './assemble.js';
+// Site config — typed identity functions for site.config.ts and gazetta.config.ts
+export { defineSite, defineGazetta } from './config/index.js';
+// `SiteConfig` / `GazettaConfig` (z.infer-derived input shapes) are no longer
+// publicly exported — the user-input shape and runtime manifest shape converged
+// under Path X. Operators get types via inference from `SiteManifest` /
+// `GazettaManifest` through `defineSite` / `defineGazetta`.
+export { ConfigError, ConfigValidationError, ConfigEvaluationError, ConfigLayoutError, } from './config/index.js';
+export { loadGazettaConfig, loadSiteConfig, discoverSites, loadProjectConfig, siteConfigToManifest, } from './config/index.js';
 // Editor — import from 'gazetta/editor' (separate entry point to avoid pulling Tiptap into server builds)
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEhD,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAA;AAUpG,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE7D,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,YAAY,CAAA;AAGnB,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,WAAW;AACX,OAAO,EACL,eAAe,EACf,cAAc,EACd,UAAU,GAGX,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAA4B,MAAM,UAAU,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC9E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAE3C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC/F,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1D,oBAAoB;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAGxD,UAAU;AACV,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAE1E,2EAA2E;AAC3E,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG9E,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAGzC,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,uBAAuB,CAAA;AAE9B,iBAAiB;AACjB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC,8CAA8C;AAC9C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE3F,0GAA0G"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/locale.d.ts

@@ -32,7 +32,11 @@ export declare function isValidLocale(locale: string): boolean;
 export declare function normalizeLocale(locale: string): string;
 /**
  * Resolve the default locale for a site manifest.
- * Chain: explicit `locale` field → first in `locales.supported` → 'en'.
+ * Chain: `locales.default` → first in `locales.supported` → 'en'.
+ *
+ * The previous top-level `locale` field was removed in the locale-shape
+ * migration (Phase 5 of the Path X work); operators now write
+ * `locales: { default: 'fr', supported: ['en', 'fr'] }`.
  */
 export declare function defaultLocaleFor(site: SiteManifest): string;
 /**
@@ -71,4 +75,24 @@ export declare function resolveLocaleFallback(locale: string, available: Set<str
  * Other locales → '/{locale}'.
  */
 export declare function localeRoutePrefix(locale: string, resolved: ResolvedLocales): string;
+/**
+ * Build the locale fallback chain for a given active locale, EXCLUDING the
+ * default locale (which is always read separately as the base manifest).
+ *
+ * Distinct from `resolveLocaleFallback` (which is "first-found-wins" page
+ * resolution). This helper supports **per-field cascade** in asset metadata:
+ * the asset walker reads each variant in chain order and merges most-specific-
+ * wins, so a French page can pick up `pt-BR` alt overrides through the
+ * configured `pt-BR → pt` fallback while still using default for everything
+ * else.
+ *
+ * Examples (with site default `en`, fallbacks `{ 'pt-BR': 'pt' }`):
+ *   localeFallbackChain('pt-BR', resolved) → ['pt-br', 'pt']
+ *   localeFallbackChain('fr', resolved)    → ['fr']
+ *   localeFallbackChain('en', resolved)    → []  (active === default; no chain)
+ *
+ * The default locale never appears in the chain — callers always read the
+ * default manifest first as the base, then apply the chain on top.
+ */
+export declare function localeFallbackChain(locale: string, resolved: ResolvedLocales): readonly string[];
 //# sourceMappingURL=locale.d.ts.map

package/dist/locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAiB,MAAM,YAAY,CAAA;AAE3E,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAA;IACtB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAA;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAKD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAY7E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAsBrG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAG9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAiB/G;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAInF"}
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAiB,MAAM,YAAY,CAAA;AAE3E,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAA;IACtB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAA;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAKD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAY7E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAsBrG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAG9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAiB/G;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAInF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAehG"}

package/dist/locale.js

@@ -24,10 +24,14 @@ export function normalizeLocale(locale) {
 }
 /**
  * Resolve the default locale for a site manifest.
- * Chain: explicit `locale` field → first in `locales.supported` → 'en'.
+ * Chain: `locales.default` → first in `locales.supported` → 'en'.
+ *
+ * The previous top-level `locale` field was removed in the locale-shape
+ * migration (Phase 5 of the Path X work); operators now write
+ * `locales: { default: 'fr', supported: ['en', 'fr'] }`.
  */
 export function defaultLocaleFor(site) {
-    return site.locale ?? site.locales?.supported?.[0] ?? 'en';
+    return site.locales?.default ?? site.locales?.supported?.[0] ?? 'en';
 }
 /**
  * Resolve site-level locale settings.
@@ -137,6 +141,44 @@ export function localeRoutePrefix(locale, resolved) {
         return '';
     return `/${norm}`;
 }
+/**
+ * Build the locale fallback chain for a given active locale, EXCLUDING the
+ * default locale (which is always read separately as the base manifest).
+ *
+ * Distinct from `resolveLocaleFallback` (which is "first-found-wins" page
+ * resolution). This helper supports **per-field cascade** in asset metadata:
+ * the asset walker reads each variant in chain order and merges most-specific-
+ * wins, so a French page can pick up `pt-BR` alt overrides through the
+ * configured `pt-BR → pt` fallback while still using default for everything
+ * else.
+ *
+ * Examples (with site default `en`, fallbacks `{ 'pt-BR': 'pt' }`):
+ *   localeFallbackChain('pt-BR', resolved) → ['pt-br', 'pt']
+ *   localeFallbackChain('fr', resolved)    → ['fr']
+ *   localeFallbackChain('en', resolved)    → []  (active === default; no chain)
+ *
+ * The default locale never appears in the chain — callers always read the
+ * default manifest first as the base, then apply the chain on top.
+ */
+export function localeFallbackChain(locale, resolved) {
+    const norm = normalizeLocale(locale);
+    if (norm === resolved.default)
+        return [];
+    const chain = [norm];
+    const visited = new Set([norm]);
+    let current = norm;
+    while (resolved.fallbacks[current]) {
+        const next = resolved.fallbacks[current];
+        if (next === resolved.default)
+            break;
+        if (visited.has(next))
+            break; // cycle: stop, never re-visit
+        visited.add(next);
+        chain.push(next);
+        current = next;
+    }
+    return chain;
+}
 /** Normalize fallback keys and values to lowercase. */
 function normalizeFallbacks(fallbacks) {
     if (!fallbacks)

package/dist/locale.js.map

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

package/dist/manifest-save.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Save pipeline — orchestrator for Page and Fragment Manifest writes.
+ *
+ * Today's `admin-api/routes/pages.ts` PUT handler and the matching
+ * fragments.ts handler each inline the same 13-step orchestration:
+ * etag check → validate → beforeSave hooks → history → write → sidecars
+ * → cache → audit → afterSave hooks → scanner. Two route files, one deep
+ * concept duplicated.
+ *
+ * `saveManifestCore` is the seam that hides the orchestration. Routes
+ * become protocol translators (parse Hono request → call → project
+ * SaveResult to HTTP). The CLI, plugin-contributed routes, and any
+ * future Save-shaped consumer call the same function.
+ *
+ * Per-kind entry points (`savePage`, `saveFragment` in pages/save.ts +
+ * fragments/save.ts — Cuts 3+4) wrap this with kind-specific concerns:
+ * locale resolution from `site.pages` vs `site.fragments`, the `route`
+ * field preservation Page Manifests need, and per-kind cache prefixes
+ * (Fragment Saves invalidate `pages:` too because Fragment References
+ * compose into Page summaries).
+ *
+ * Pipeline order is locked semantics, not configuration. Per
+ * `design-hooks.md` "Save flow with hooks": validators run first
+ * (validators are pure functions over a manifest), then beforeSave
+ * hooks see validated payload, then storage write, then afterSave
+ * hooks observe the result. Reordering breaks invariants — audit
+ * before write would lie about success.
+ *
+ * Reserved slots in the sequence (no-ops today; wired by future cuts):
+ *   - Review-state precheck (Review-Workflow Cut 5: pending-review
+ *     state → 409 EDIT_LOCKED)
+ *   - Cascades (Soft-Delete Q6: auto-cancel scheduled actions on
+ *     archive transition; Review Cut 5: invalidateOnSave policy
+ *     transitions approved → draft)
+ *
+ * Throws are reserved for infrastructure failures (storage write
+ * fail, audit infra fail per locked fail-open). Expected outcomes
+ * — STALE / VALIDATION_FAILED / HOOK_CANCELLED — are typed
+ * `SaveResult` variants. Callers `switch` exhaustively; TS narrows.
+ */
+import type { Principal } from './auth/types.js';
+import type { ContentRoot } from './content-root.js';
+import type { HistoryProvider } from './history.js';
+import { type HookRegistry } from './hooks/index.js';
+import type { Site } from './site-loader.js';
+import type { StorageProvider } from './types.js';
+import type { ValidatorRegistry } from './validation/registry.js';
+import type { RescanCause, ValidationScanner } from './validation/scanner.js';
+import type { Issue } from './validation/types.js';
+/**
+ * Discriminator for the kind of manifest being saved. The pipeline
+ * spine is the same for every kind; per-kind wrappers in
+ * `pages/save.ts` and `fragments/save.ts` carry the kind through to
+ * audit + sidecar + cache invalidation calls.
+ */
+export type SaveManifestKind = 'page' | 'fragment';
+/**
+ * Successful save outcome. `etag` is the recomputed save-etag for
+ * the new on-disk content; clients update their baseline without a
+ * separate GET so offline replay chains work (per
+ * `design-offline.md` Q3 — chained If-Match projections).
+ */
+export interface SaveOk {
+    readonly ok: true;
+    readonly etag: string;
+}
+/**
+ * Save-etag mismatch (per `design-offline.md` Q3). Server returned
+ * the current manifest body so the client can render a diff. The
+ * `currentEtag` lets the client retry-without-conflict if it accepts
+ * the server's version verbatim.
+ */
+export interface SaveStale {
+    readonly ok: false;
+    readonly code: 'STALE';
+    readonly current: Record<string, unknown>;
+    readonly currentEtag: string;
+}
+/**
+ * Save-delta validation produced blocking issues (per
+ * `design-validation.md` four-phase model). Only issues introduced
+ * by THIS edit are surfaced — pre-existing site debt is the
+ * background scanner's surface, not the save handler's.
+ */
+export interface SaveValidationFailed {
+    readonly ok: false;
+    readonly code: 'VALIDATION_FAILED';
+    readonly issues: readonly Issue[];
+}
+/**
+ * A `beforeSave` hook threw `HookCancellation` or `HookTimeout`
+ * (per `design-hooks.md` "Composition" — `before*` hooks chain;
+ * one throw stops the chain and cancels the operation). The hook's
+ * name is surfaced so clients can discriminate which hook
+ * cancelled.
+ */
+export interface SaveHookCancelled {
+    readonly ok: false;
+    readonly code: 'HOOK_CANCELLED';
+    readonly hook: string;
+    readonly reason: string;
+}
+/**
+ * Typed union of expected save outcomes. Routes project each
+ * variant to HTTP (200 / 409). Callers (CLI, plugin-routes, future
+ * save-via-hook) `switch` exhaustively. Adding a new variant is a
+ * compile error at every call site — intentional, per the locked
+ * decision in Q1.
+ */
+export type SaveResult = SaveOk | SaveStale | SaveValidationFailed | SaveHookCancelled;
+/**
+ * Audit recorder shape the pipeline calls. Matches the existing
+ * `c.var.audit.record` surface from admin-api/middleware/audit.ts
+ * — the pipeline doesn't construct events differently from routes.
+ *
+ * Returns `unknown` (not `RecordResult`) so the pipeline doesn't
+ * couple to the audit module's return shape. Strict-mode operators
+ * branch on `result.failed > 0`; the pipeline doesn't.
+ */
+export interface SaveAuditRecorder {
+    record(event: {
+        action: 'save';
+        /**
+         * Closed-enum subset of AuditOutcome the save pipeline emits.
+         * 'hook-cancelled' fires when a beforeSave hook throws or times
+         * out (per design-hooks.md Q3); 'validation-failed' fires when
+         * save-delta validators flag blocking issues. Pre-fix shape
+         * conflated the two paths under 'validation-failed' — fixed
+         * 2026-05 alongside cross-foundation gap #1 coverage.
+         */
+        outcome: 'success' | 'validation-failed' | 'forbidden' | 'hook-cancelled';
+        scope: {
+            kind: SaveManifestKind;
+            name: string;
+        };
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/**
+ * Principal shape the pipeline needs. Re-exports `auth/types.ts:Principal`
+ * so callers (`c.var.principal`) pass the real type without conversion.
+ * The pipeline doesn't construct principals — only forwards them to
+ * `buildHookContext`.
+ */
+export type SavePrincipal = Principal;
+/**
+ * Source wiring the pipeline needs. Mirrors the relevant subset of
+ * `admin-api/source-context.ts:SourceContext` without importing the
+ * admin-api type — the pipeline is a domain primitive, not bound to
+ * the admin-api boundary. Wrappers (`savePage`, `saveFragment`) pass
+ * `source` straight through; the structural compatibility with
+ * `SourceContext` lets that work without conversion.
+ */
+export interface SaveSourceWiring {
+    readonly storage: StorageProvider;
+    readonly contentRoot: ContentRoot;
+    readonly cache: {
+        invalidatePrefix(prefix: string): Promise<number>;
+    };
+    readonly history?: HistoryProvider;
+    readonly targetName?: string;
+    readonly manifest?: {
+        name?: string;
+    };
+}
+/**
+ * Inputs to `saveManifestCore`. Carries everything the pipeline
+ * needs without reaching into route or HTTP concerns.
+ *
+ * Per Q2 lock: target wiring (cache, history, storage, contentRoot)
+ * comes from `SourceContext` upstream; orchestration deps
+ * (validators, hooks, scanner, audit) are injected per request.
+ * The wrapper functions (`savePage`, `saveFragment`) destructure
+ * `source` and assemble this shape.
+ */
+export interface SaveManifestInput {
+    /** Discriminator for downstream audit + sidecar calls. */
+    readonly kind: SaveManifestKind;
+    /** Item name (folder name under `pages/` or `fragments/`). */
+    readonly name: string;
+    /** BCP-47 locale when saving a Locale Variant; undefined for default. */
+    readonly locale?: string;
+    /** New manifest body (post-component-id, pre-validation). */
+    readonly manifest: Record<string, unknown>;
+    /** Pre-save manifest from the loaded `Site`; null when creating. */
+    readonly before: Record<string, unknown> | null;
+    /** Absolute path the new manifest serializes to. */
+    readonly manifestPath: string;
+    /** Optional save-etag for concurrency check (per design-offline.md Q3). */
+    readonly ifMatch?: string;
+    /**
+     * Loaded `Site` (the same instance that resolved `before`). Save-delta
+     * validation needs it to walk template + fragment + asset refs.
+     */
+    readonly site: Site;
+    /**
+     * Cache prefixes to invalidate after the write. Page Saves pass
+     * `['pages:']`; Fragment Saves pass `['fragments:', 'pages:']`
+     * because Fragment References compose into Page summaries.
+     */
+    readonly cacheInvalidatePrefixes: readonly string[];
+    /**
+     * Optional fields to include in the recomputed save-etag.
+     * Page Saves include `route` (folder-derived; not stored in the
+     * file but part of the etag projection chain). Fragment Saves
+     * pass an empty object.
+     */
+    readonly etagExtras: Record<string, unknown>;
+    /** Source wiring; opaque to the pipeline beyond the typed fields below. */
+    readonly source: SaveSourceWiring;
+    /** Audit recorder bound to the request (typically `c.var.audit`). */
+    readonly audit: SaveAuditRecorder;
+    /** Authenticated principal driving this save (for hook context). */
+    readonly principal: SavePrincipal;
+    /** Audit-firing emitter used by hook dispatch (forwarded to buildHookContext). */
+    readonly hookAuditEmit?: import('./hooks/index.js').HookFiringEmitter;
+    /** Validator registry (built once at admin boot per design-validation.md Cut 1). */
+    readonly validators: ValidatorRegistry;
+    /** Hook registry; absent when the site has no hooks contributed. */
+    readonly hooks?: HookRegistry;
+    /** Background scanner; absent when scanner not enabled for this admin. */
+    readonly scanner?: ValidationScanner;
+    /**
+     * Scanner rescan cause. Per-kind because the scanner's `RescanCause`
+     * union differs by kind (Page Saves use `{ kind: 'manifest', item }`
+     * to invalidate just the page; Fragment Saves use
+     * `{ kind: 'fragment', name }` to walk transitive dependents via
+     * `findDependentsFromSidecars`). Wrappers build the right shape.
+     */
+    readonly scannerCause?: RescanCause;
+    /** Per-request correlation id; fresh UUID when absent. */
+    readonly requestId?: string;
+}
+/**
+ * Save pipeline orchestrator — Cut 2.
+ *
+ * Ports the 13-step spine from `admin-api/routes/pages.ts:290-510`.
+ * Pipeline sequence (locked per Q5):
+ *
+ *   1. etag precheck                 → STALE
+ *   2. review-state precheck         (reserved slot — no-op today)
+ *   3. validators                    → VALIDATION_FAILED
+ *   4. beforeSave hooks              → HOOK_CANCELLED
+ *   5. history record (pre-write)
+ *   6. storage write
+ *   7. sidecars (asset/fragment/alias) in parallel
+ *   8. cache invalidate (per per-kind prefixes)
+ *   9. compute new etag
+ *  10. audit success
+ *  11. afterSave hooks               (fail-open observers)
+ *  12. cascades                      (reserved slot — no-op today)
+ *  13. scanner.rescan                (fire-and-forget)
+ */
+export declare function saveManifestCore(input: SaveManifestInput): Promise<SaveResult>;
+//# sourceMappingURL=manifest-save.d.ts.map

package/dist/manifest-save.d.ts.map

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