gazetta 0.4.0 → 0.6.0

package/dist/hash.d.ts

@@ -1,8 +1,54 @@
 import type { FragmentManifest, PageManifest } from './types.js';
-export declare function sidecarNameFor(hash: string): string;
+/** Build a hash sidecar filename, optionally locale-suffixed. */
+export declare function sidecarNameFor(hash: string, locale?: string): string;
+/** Parse a hash sidecar filename. Returns { hash, locale? } or null. */
 export declare function parseSidecarName(entryName: string): string | null;
+/** Parse locale from a hash sidecar filename. */
+export declare function parseSidecarLocale(entryName: string): string | undefined;
+/**
+ * Filename-safe encoding for fragment/template names. Fragments can be
+ * subfolder-qualified (e.g. "buttons/primary"); we replace `/` with `.`
+ * so the name works as a filename component and stays readable in
+ * listings.
+ *
+ * Why `.`: per operations.md, refs are lowercase-kebab-case — `.` is
+ * explicitly avoided in ref names ("confuses URL routing"), so using
+ * it as the path separator in encoded form is collision-free with
+ * the legal input alphabet (letters, digits, `-`, `_`, `/`).
+ *
+ * The prior `/` ↔ `__` scheme was ambiguous for any input containing
+ * `_` (a legitimate character in names like `my_fragment`) — a lone
+ * `_` adjacent to `/` encoded to `___` and decoded ambiguously.
+ *
+ * We reject `.` in inputs at encode time. It's already documented as
+ * off-limits in ref names; enforcing it here turns a silent
+ * round-trip bug into a loud error for anyone who tries.
+ */
+export declare function encodeRefName(name: string): string;
+export declare function decodeRefName(name: string): string;
+/** `.uses-header` for a page/fragment that references @header. */
+export declare function usesSidecarNameFor(fragmentName: string): string;
+export declare function parseUsesSidecarName(entryName: string): string | null;
+/** `.tpl-page-default` for a page/fragment rendered with that template. */
+export declare function templateSidecarNameFor(templateName: string): string;
+export declare function parseTemplateSidecarName(entryName: string): string | null;
+/** Compact ISO timestamp for `.pub-` sidecar filenames: `20260417T220000Z`. */
+export declare function compactTimestamp(date?: Date): string;
+/** Parse compact timestamp back to ISO string: `2026-04-17T22:00:00Z`. */
+export declare function parseCompactTimestamp(compact: string): string;
+export interface PubSidecar {
+    lastPublished: string;
+    noindex: boolean;
+}
+/** `.pub-20260417T220000Z`, `.pub-20260417T220000Z-noindex`, or `.pub-20260417T220000Z.fr` */
+export declare function pubSidecarNameFor(date?: Date, noindex?: boolean, locale?: string): string;
+export declare function parsePubSidecarName(entryName: string): PubSidecar | null;
+/** Parse locale from a pub sidecar filename. */
+export declare function parsePubSidecarLocale(entryName: string): string | undefined;
 export interface HashManifestOptions {
     templateHashes: Map<string, string>;
+    /** Fragment content hashes — include only for static-mode page hashing. */
+    fragmentHashes?: Map<string, string>;
 }
 /**
  * Compute the content hash for a page or fragment manifest.

package/dist/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAIhF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAuBD,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,GAAG,gBAAgB,EACzC,IAAI,EAAE,mBAAmB,GACxB,MAAM,CASR"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAOhF,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AACD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AACD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrE;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnE;AACD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAKhE;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,EAAE,OAAO,UAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnG;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOxE;AAED,gDAAgD;AAChD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3E;AAmCD,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,2EAA2E;IAC3E,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,gBAAgB,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CASzG"}

package/dist/hash.js

@@ -1,28 +1,125 @@
 import { createHash } from 'node:crypto';
-const SIDECAR_RE = /^\.([0-9a-f]{8})\.hash$/;
-export function sidecarNameFor(hash) {
-    return `.${hash}.hash`;
+const SIDECAR_RE = /^\.([0-9a-f]{8})\.hash(?:\.([a-z]{2}(?:-[a-z]+)?))?$/;
+const USES_SIDECAR_RE = /^\.uses-(.+)$/;
+const TPL_SIDECAR_RE = /^\.tpl-(.+)$/;
+const PUB_SIDECAR_RE = /^\.pub-(\d{8}T\d{6}Z)(-noindex)?(?:\.([a-z]{2}(?:-[a-z]+)?))?$/;
+/** Build a hash sidecar filename, optionally locale-suffixed. */
+export function sidecarNameFor(hash, locale) {
+    return locale ? `.${hash}.hash.${locale}` : `.${hash}.hash`;
 }
+/** Parse a hash sidecar filename. Returns { hash, locale? } or null. */
 export function parseSidecarName(entryName) {
     const m = SIDECAR_RE.exec(entryName);
     return m ? m[1] : null;
 }
+/** Parse locale from a hash sidecar filename. */
+export function parseSidecarLocale(entryName) {
+    const m = SIDECAR_RE.exec(entryName);
+    return m?.[2] ?? undefined;
+}
+/**
+ * Filename-safe encoding for fragment/template names. Fragments can be
+ * subfolder-qualified (e.g. "buttons/primary"); we replace `/` with `.`
+ * so the name works as a filename component and stays readable in
+ * listings.
+ *
+ * Why `.`: per operations.md, refs are lowercase-kebab-case — `.` is
+ * explicitly avoided in ref names ("confuses URL routing"), so using
+ * it as the path separator in encoded form is collision-free with
+ * the legal input alphabet (letters, digits, `-`, `_`, `/`).
+ *
+ * The prior `/` ↔ `__` scheme was ambiguous for any input containing
+ * `_` (a legitimate character in names like `my_fragment`) — a lone
+ * `_` adjacent to `/` encoded to `___` and decoded ambiguously.
+ *
+ * We reject `.` in inputs at encode time. It's already documented as
+ * off-limits in ref names; enforcing it here turns a silent
+ * round-trip bug into a loud error for anyone who tries.
+ */
+export function encodeRefName(name) {
+    if (name.includes('.')) {
+        throw new Error(`Invalid reference name "${name}": dot is reserved for path encoding. ` +
+            `Use lowercase-kebab-case with / for subfolders (e.g. "buttons/primary").`);
+    }
+    return name.replace(/\//g, '.');
+}
+export function decodeRefName(name) {
+    return name.replace(/\./g, '/');
+}
+/** `.uses-header` for a page/fragment that references @header. */
+export function usesSidecarNameFor(fragmentName) {
+    return `.uses-${encodeRefName(fragmentName)}`;
+}
+export function parseUsesSidecarName(entryName) {
+    const m = USES_SIDECAR_RE.exec(entryName);
+    return m ? decodeRefName(m[1]) : null;
+}
+/** `.tpl-page-default` for a page/fragment rendered with that template. */
+export function templateSidecarNameFor(templateName) {
+    return `.tpl-${encodeRefName(templateName)}`;
+}
+export function parseTemplateSidecarName(entryName) {
+    const m = TPL_SIDECAR_RE.exec(entryName);
+    return m ? decodeRefName(m[1]) : null;
+}
+/** Compact ISO timestamp for `.pub-` sidecar filenames: `20260417T220000Z`. */
+export function compactTimestamp(date = new Date()) {
+    return date
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}/, '');
+}
+/** Parse compact timestamp back to ISO string: `2026-04-17T22:00:00Z`. */
+export function parseCompactTimestamp(compact) {
+    // 20260417T220000Z → 2026-04-17T22:00:00Z
+    return `${compact.slice(0, 4)}-${compact.slice(4, 6)}-${compact.slice(6, 8)}T${compact.slice(9, 11)}:${compact.slice(11, 13)}:${compact.slice(13, 15)}Z`;
+}
+/** `.pub-20260417T220000Z`, `.pub-20260417T220000Z-noindex`, or `.pub-20260417T220000Z.fr` */
+export function pubSidecarNameFor(date = new Date(), noindex = false, locale) {
+    const base = `.pub-${compactTimestamp(date)}${noindex ? '-noindex' : ''}`;
+    return locale ? `${base}.${locale}` : base;
+}
+export function parsePubSidecarName(entryName) {
+    const m = PUB_SIDECAR_RE.exec(entryName);
+    if (!m)
+        return null;
+    return {
+        lastPublished: parseCompactTimestamp(m[1]),
+        noindex: !!m[2],
+    };
+}
+/** Parse locale from a pub sidecar filename. */
+export function parsePubSidecarLocale(entryName) {
+    const m = PUB_SIDECAR_RE.exec(entryName);
+    return m?.[3] ?? undefined;
+}
 /**
- * Walk the component tree and substitute `template: "name"` with `template: "name#hash"`
- * using the provided template hashes. Returns a new normalized structure — input is not mutated.
+ * Walk the component tree and substitute template/fragment refs with their
+ * hashed forms (`"name#hash"`) using the provided maps. Returns a new
+ * normalized structure — input is not mutated.
+ *
+ * `fragmentHashes` is only provided for static-mode targets where fragments
+ * are baked into pages at publish time — a fragment content change must
+ * invalidate every page that uses it. In ESI mode fragments are published
+ * separately, so pages don't need fragment hashes in their own hash.
  */
-function substituteTemplateHashes(components, templateHashes) {
+function substituteHashes(components, templateHashes, fragmentHashes) {
     if (!components)
         return undefined;
     return components.map(entry => {
-        if (typeof entry === 'string')
-            return entry;
+        if (typeof entry === 'string') {
+            if (!fragmentHashes || !entry.startsWith('@'))
+                return entry;
+            const name = entry.slice(1);
+            const h = fragmentHashes.get(name);
+            return h ? `@${name}#${h}` : entry;
+        }
         const hash = templateHashes.get(entry.template);
         return {
             name: entry.name,
             template: hash ? `${entry.template}#${hash}` : entry.template,
             content: entry.content,
-            components: substituteTemplateHashes(entry.components, templateHashes),
+            components: substituteHashes(entry.components, templateHashes, fragmentHashes),
         };
     });
 }
@@ -39,7 +136,7 @@ export function hashManifest(manifest, opts) {
     const normalized = {
         template: rootHash ? `${manifest.template}#${rootHash}` : manifest.template,
         content: manifest.content ?? null,
-        components: substituteTemplateHashes(manifest.components, opts.templateHashes) ?? null,
+        components: substituteHashes(manifest.components, opts.templateHashes, opts.fragmentHashes) ?? null,
     };
     const json = JSON.stringify(normalized, sortedReplacer);
     return createHash('md5').update(json).digest('hex').slice(0, 8);

package/dist/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,MAAM,UAAU,GAAG,yBAAyB,CAAA;AAE5C,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,IAAI,OAAO,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACpC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACxB,CAAC;AAED;;;GAGG;AACH,SAAS,wBAAwB,CAC/B,UAAwC,EACxC,cAAmC;IAEnC,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAA;IACjC,OAAO,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QAC3C,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QAC/C,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ;YAC7D,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,wBAAwB,CAAC,KAAK,CAAC,UAAU,EAAE,cAAc,CAAC;SACvE,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAMD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAyC,EACzC,IAAyB;IAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC3D,MAAM,UAAU,GAAG;QACjB,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ;QAC3E,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,IAAI;QACjC,UAAU,EAAE,wBAAwB,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI;KACvF,CAAA;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,cAAc,CAAC,CAAA;IACvD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACjE,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAc;IAClD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,GAAG,GAA4B,EAAE,CAAA;QACvC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACrE,GAAG,CAAC,CAAC,CAAC,GAAI,KAAiC,CAAC,CAAC,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"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"}

package/dist/history-provider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * HistoryProvider implementation on top of any StorageProvider.
+ *
+ * Layout per target (inside `.gazetta/history/` under the target's
+ * storage root):
+ *
+ *   index.json                     { nextId: N, revisions: ['rev-0001', ...] }
+ *   revisions/rev-NNNN.json        one manifest per revision — metadata +
+ *                                  items map (itemPath → blob hash)
+ *   objects/<hh>/<rest>            content-addressed blobs (SHA-256, sharded
+ *                                  by first 2 hex chars)
+ *
+ * Design-decisions.md #18:
+ *  - One uniform approach across all providers (no native versioning).
+ *  - Content-addressed blobs → unchanged items share storage across
+ *    revisions; storage scales with unique content, not revision count.
+ *  - Soft undo only — every restore writes a new forward revision.
+ *  - Retention default 50; oldest evicted on write.
+ *
+ * SRP: this module owns .gazetta/history/ layout and retention. Nothing
+ * else. The write pipeline (save/publish) calls `recordRevision`; undo/
+ * rollback call `readRevision` + `readBlob`. Restore happens outside —
+ * this module doesn't touch the content tree.
+ */
+import type { StorageProvider } from './types.js';
+import type { HistoryProvider } from './history.js';
+export interface CreateHistoryProviderOptions {
+    /** Storage under which `.gazetta/history/` lives. Usually the target's storage. */
+    storage: StorageProvider;
+    /**
+     * Path prefix where history lives. Default: `.gazetta/history`. Callers
+     * with a rooted storage (filesystem target with `path:`) pass the
+     * default; anything more exotic (e.g. history under a sub-prefix)
+     * overrides.
+     */
+    rootPath?: string;
+    /**
+     * Maximum number of revisions to keep; older ones evicted on write.
+     * Default: `DEFAULT_HISTORY_RETENTION` (50). Pass < 1 → clamped to 1
+     * (zero retention would self-evict every write).
+     */
+    retention?: number;
+}
+/**
+ * Build a HistoryProvider backed by the given storage. No I/O happens
+ * at construction time — everything is lazy on first call.
+ */
+export declare function createHistoryProvider(opts: CreateHistoryProviderOptions): HistoryProvider;
+//# sourceMappingURL=history-provider.d.ts.map

package/dist/history-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-provider.d.ts","sourceRoot":"","sources":["../src/history-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAA6C,MAAM,cAAc,CAAA;AAG9F,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,OAAO,EAAE,eAAe,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAgBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,eAAe,CAyMzF"}

package/dist/history-provider.js

@@ -0,0 +1,226 @@
+/**
+ * HistoryProvider implementation on top of any StorageProvider.
+ *
+ * Layout per target (inside `.gazetta/history/` under the target's
+ * storage root):
+ *
+ *   index.json                     { nextId: N, revisions: ['rev-0001', ...] }
+ *   revisions/rev-NNNN.json        one manifest per revision — metadata +
+ *                                  items map (itemPath → blob hash)
+ *   objects/<hh>/<rest>            content-addressed blobs (SHA-256, sharded
+ *                                  by first 2 hex chars)
+ *
+ * Design-decisions.md #18:
+ *  - One uniform approach across all providers (no native versioning).
+ *  - Content-addressed blobs → unchanged items share storage across
+ *    revisions; storage scales with unique content, not revision count.
+ *  - Soft undo only — every restore writes a new forward revision.
+ *  - Retention default 50; oldest evicted on write.
+ *
+ * SRP: this module owns .gazetta/history/ layout and retention. Nothing
+ * else. The write pipeline (save/publish) calls `recordRevision`; undo/
+ * rollback call `readRevision` + `readBlob`. Restore happens outside —
+ * this module doesn't touch the content tree.
+ */
+import { createHash } from 'node:crypto';
+import { DEFAULT_HISTORY_RETENTION } from './types.js';
+/**
+ * Build a HistoryProvider backed by the given storage. No I/O happens
+ * at construction time — everything is lazy on first call.
+ */
+export function createHistoryProvider(opts) {
+    const { storage } = opts;
+    const root = opts.rootPath ?? '.gazetta/history';
+    const retention = Math.max(1, opts.retention ?? DEFAULT_HISTORY_RETENTION);
+    const indexPath = join(root, 'index.json');
+    /** Read the index or return an empty one if it doesn't exist yet. */
+    async function readIndex() {
+        if (!(await storage.exists(indexPath))) {
+            return { revisions: [] };
+        }
+        const parsed = JSON.parse(await storage.readFile(indexPath));
+        // Forward-compat: tolerate legacy `nextId` by ignoring it. Old indexes
+        // (from the numeric-id era) continue to read cleanly, new writes use
+        // the timestamp scheme. No migration pass needed — retention naturally
+        // evicts the legacy ids over time.
+        return { revisions: parsed.revisions ?? [] };
+    }
+    /**
+     * Ensure the parent directory exists before writing. Object-store
+     * providers (R2, S3) ignore mkdir. Filesystem requires it because
+     * `writeFile` fails on missing parents, and our sharded blob paths
+     * (objects/<hh>/<rest>) plus revisions/rev-NNNN.json live in dirs
+     * that don't exist until the first write.
+     */
+    async function writeWithParents(path, content) {
+        const parent = path.substring(0, path.lastIndexOf('/'));
+        if (parent)
+            await storage.mkdir(parent);
+        await storage.writeFile(path, content);
+    }
+    async function writeIndex(idx) {
+        await writeWithParents(indexPath, JSON.stringify(idx, null, 2) + '\n');
+    }
+    function blobPath(hash) {
+        // Shard by first two hex chars — keeps any one `objects/` subdirectory
+        // from ballooning past a few thousand entries on large sites.
+        return join(root, 'objects', hash.slice(0, 2), hash.slice(2));
+    }
+    function revisionPath(id) {
+        return join(root, 'revisions', `${id}.json`);
+    }
+    /** SHA-256 hex of the content — strong enough that collisions can be
+     *  ignored for practical purposes (blob identity), cheap enough at our
+     *  scale (tens of KB per item, hundreds of items per revision). */
+    function hashContent(content) {
+        return createHash('sha256').update(content).digest('hex');
+    }
+    /**
+     * Allocate a fresh revision id. Scheme: `rev-<unixMillis>`, with a
+     * `-<seq>` suffix on same-millisecond collisions ("rev-1760...050",
+     * "rev-1760...050-2", ...). Collision tracking uses the current
+     * index's revisions list — assumes no concurrent writers against
+     * the same target (already true: Gazetta never has two admins
+     * writing the same target's history simultaneously).
+     *
+     * Why millis + suffix rather than a monotonic counter:
+     *   - Retention evictions leave you with a window of revisions you
+     *     can date-read from the filename alone.
+     *   - No counter to overflow or reset when history is disabled then
+     *     re-enabled.
+     *   - Lex-sort = chrono sort (13-digit ms are fixed-width through
+     *     year 5138 AD).
+     *
+     * `_clock` is injectable for deterministic tests — production uses
+     * Date.now(). Stays private to createHistoryProvider.
+     */
+    function formatId(existing, now) {
+        const base = `rev-${now}`;
+        if (!existing.some(id => id === base || id.startsWith(`${base}-`)))
+            return base;
+        // Same-millisecond collision: bump the suffix. Start from 2 so the
+        // first duplicate gets `-2` (matches the mental model "base, then
+        // the second, then the third").
+        let seq = 2;
+        while (existing.includes(`${base}-${seq}`))
+            seq += 1;
+        return `${base}-${seq}`;
+    }
+    /**
+     * Write any blob that's not already stored. Returns the hash. Dedup
+     * check is a single `exists()` — cheaper than reading the existing
+     * blob to confirm equal content (hashes collide vanishingly).
+     */
+    async function writeBlob(content) {
+        const hash = hashContent(content);
+        const path = blobPath(hash);
+        if (!(await storage.exists(path))) {
+            await writeWithParents(path, content);
+        }
+        return hash;
+    }
+    async function recordRevision(input) {
+        const idx = await readIndex();
+        const id = formatId(idx.revisions, Date.now());
+        // Write blobs (dedup via content-addressing) and build the
+        // path → hash snapshot.
+        const snapshot = {};
+        // Deterministic order so rev manifests diff cleanly on inspection.
+        const sortedEntries = [...input.items.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+        for (const [path, content] of sortedEntries) {
+            snapshot[path] = await writeBlob(content);
+        }
+        const manifest = {
+            id,
+            timestamp: new Date().toISOString(),
+            operation: input.operation,
+            author: input.author,
+            source: input.source,
+            items: [...input.items.keys()].sort(),
+            message: input.message,
+            restoredFrom: input.restoredFrom,
+            snapshot,
+        };
+        await writeWithParents(revisionPath(id), JSON.stringify(manifest, null, 2) + '\n');
+        // Update the index (append) then apply retention. Do the index
+        // write last so a mid-write failure leaves orphan blobs and an
+        // orphan manifest (both harmless) rather than a dangling index
+        // entry pointing at a missing manifest.
+        idx.revisions.push(id);
+        await writeIndex(idx);
+        await applyRetention(idx);
+        // Return the public Revision shape (no snapshot).
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { snapshot: _snapshot, ...revision } = manifest;
+        return revision;
+    }
+    /**
+     * Evict oldest revisions to fit `retention`. Deletes manifests; blobs
+     * become eligible for GC if no remaining revision references them.
+     * GC is lazy — blob files stay until an explicit GC pass, which is
+     * fine for v1 (disk is cheap; a future `gazetta gc` command can walk
+     * all manifests and prune orphans).
+     */
+    async function applyRetention(idx) {
+        const excess = idx.revisions.length - retention;
+        if (excess <= 0)
+            return;
+        const toEvict = idx.revisions.slice(0, excess);
+        idx.revisions = idx.revisions.slice(excess);
+        for (const id of toEvict) {
+            const path = revisionPath(id);
+            if (await storage.exists(path))
+                await storage.rm(path);
+        }
+        await writeIndex(idx);
+    }
+    async function listRevisions(limit) {
+        const idx = await readIndex();
+        const ids = [...idx.revisions].reverse(); // newest first
+        const sliced = typeof limit === 'number' ? ids.slice(0, limit) : ids;
+        // Read manifests in parallel; strip snapshot for the summary list.
+        return Promise.all(sliced.map(async (id) => {
+            const m = await readManifest(id);
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { snapshot: _snapshot, ...rev } = m;
+            return rev;
+        }));
+    }
+    async function readManifest(id) {
+        return JSON.parse(await storage.readFile(revisionPath(id)));
+    }
+    async function readRevision(id) {
+        return readManifest(id);
+    }
+    async function readBlob(hash) {
+        return storage.readFile(blobPath(hash));
+    }
+    async function deleteRevision(id) {
+        const idx = await readIndex();
+        const at = idx.revisions.indexOf(id);
+        if (at === -1)
+            return;
+        idx.revisions.splice(at, 1);
+        await writeIndex(idx);
+        const path = revisionPath(id);
+        if (await storage.exists(path))
+            await storage.rm(path);
+        // Orphan blobs left for lazy GC — see applyRetention rationale.
+    }
+    return {
+        recordRevision,
+        listRevisions,
+        readRevision,
+        readBlob,
+        deleteRevision,
+    };
+}
+/**
+ * `posix.join` behavior without importing it — keeps the module self-
+ * contained and works identically across platforms. Storage providers
+ * normalize separators internally, but our stored paths are POSIX.
+ */
+function join(...parts) {
+    return parts.filter(Boolean).join('/').replace(/\/+/g, '/');
+}
+//# sourceMappingURL=history-provider.js.map

package/dist/history-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-provider.js","sourceRoot":"","sources":["../src/history-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAkCtD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAkC;IACtE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAA;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,yBAAyB,CAAC,CAAA;IAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IAE1C,qEAAqE;IACrE,KAAK,UAAU,SAAS;QACtB,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACvC,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;QAC1B,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAuC,CAAA;QAClG,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,mCAAmC;QACnC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,CAAA;IAC9C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;QAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;QACvD,IAAI,MAAM;YAAE,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACvC,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACxC,CAAC;IAED,KAAK,UAAU,UAAU,CAAC,GAAiB;QACzC,MAAM,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACxE,CAAC;IAED,SAAS,QAAQ,CAAC,IAAY;QAC5B,uEAAuE;QACvE,8DAA8D;QAC9D,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,SAAS,YAAY,CAAC,EAAU;QAC9B,OAAO,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;IAED;;uEAEmE;IACnE,SAAS,WAAW,CAAC,OAAe;QAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC3D,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,QAAQ,CAAC,QAA2B,EAAE,GAAW;QACxD,MAAM,IAAI,GAAG,OAAO,GAAG,EAAE,CAAA;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;QAC/E,mEAAmE;QACnE,kEAAkE;QAClE,gCAAgC;QAChC,IAAI,GAAG,GAAG,CAAC,CAAA;QACX,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;YAAE,GAAG,IAAI,CAAC,CAAA;QACpD,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAA;IACzB,CAAC;IAED;;;;OAIG;IACH,KAAK,UAAU,SAAS,CAAC,OAAe;QACtC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;QACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACvC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,UAAU,cAAc,CAAC,KAAoB;QAChD,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAA;QAC7B,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QAE9C,2DAA2D;QAC3D,wBAAwB;QACxB,MAAM,QAAQ,GAA2B,EAAE,CAAA;QAC3C,mEAAmE;QACnE,MAAM,aAAa,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACzF,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,aAAa,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;QAC3C,CAAC;QAED,MAAM,QAAQ,GAAqB;YACjC,EAAE;YACF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YACrC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,QAAQ;SACT,CAAA;QACD,MAAM,gBAAgB,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;QAElF,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,wCAAwC;QACxC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACtB,MAAM,UAAU,CAAC,GAAG,CAAC,CAAA;QACrB,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QAEzB,kDAAkD;QAClD,6DAA6D;QAC7D,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAA;QACrD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,UAAU,cAAc,CAAC,GAAiB;QAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAA;QAC/C,IAAI,MAAM,IAAI,CAAC;YAAE,OAAM;QACvB,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QAC9C,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAC3C,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;YAC7B,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,MAAM,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QACxD,CAAC;QACD,MAAM,UAAU,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,KAAK,UAAU,aAAa,CAAC,KAAc;QACzC,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAA;QAC7B,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA,CAAC,eAAe;QACxD,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;QACpE,mEAAmE;QACnE,OAAO,OAAO,CAAC,GAAG,CAChB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACpB,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,EAAE,CAAC,CAAA;YAChC,6DAA6D;YAC7D,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,GAAG,EAAE,GAAG,CAAC,CAAA;YACzC,OAAO,GAAG,CAAA;QACZ,CAAC,CAAC,CACH,CAAA;IACH,CAAC;IAED,KAAK,UAAU,YAAY,CAAC,EAAU;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAqB,CAAA;IACjF,CAAC;IAED,KAAK,UAAU,YAAY,CAAC,EAAU;QACpC,OAAO,YAAY,CAAC,EAAE,CAAC,CAAA;IACzB,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,IAAY;QAClC,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IACzC,CAAC;IAED,KAAK,UAAU,cAAc,CAAC,EAAU;QACtC,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAA;QAC7B,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACpC,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAM;QACrB,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;QAC3B,MAAM,UAAU,CAAC,GAAG,CAAC,CAAA;QACrB,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC7B,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QACtD,gEAAgE;IAClE,CAAC;IAED,OAAO;QACL,cAAc;QACd,aAAa;QACb,YAAY;QACZ,QAAQ;QACR,cAAc;KACf,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,IAAI,CAAC,GAAG,KAAe;IAC9B,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC7D,CAAC"}

package/dist/history-recorder.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Higher-level helper for recording revisions on a target.
+ *
+ * The bare `HistoryProvider.recordRevision` takes a full
+ * `items: Map<path, content>` snapshot. That's fine for testing but
+ * wasteful at runtime: every save of one page would re-hash and
+ * re-list every page + fragment on the target. This helper does the
+ * right thing:
+ *
+ *   - First revision on a target: walks the content tree once to
+ *     snapshot every manifest (page.json, fragment.json, site.yaml).
+ *   - Subsequent revisions: reads the previous snapshot and overlays
+ *     the delta (changed items the caller passes in). `readBlob` for
+ *     each carried-over path gives us the content for the new
+ *     revision's items map — at which point `recordRevision` dedupes
+ *     the unchanged blobs via content-addressing, so no new storage.
+ *
+ * SRP: this module owns the "what goes in a revision snapshot"
+ * decision. `HistoryProvider` owns layout. Callers (admin-api save /
+ * admin-api publish / CLI publish) just describe *what they wrote*
+ * and we construct the revision.
+ */
+import type { HistoryProvider, RevisionOperation } from './history.js';
+import type { ContentRoot } from './content-root.js';
+/** A single item that was written in this save/publish. */
+export interface WrittenItem {
+    /** Path relative to the content root, e.g. `pages/home/page.json`. */
+    path: string;
+    /** Current content as stored. `null` marks a deletion. */
+    content: string | null;
+}
+/**
+ * Location to scan when building the first revision's baseline
+ * snapshot. Each entry names a directory under the content root and
+ * the manifest filename to capture from every subdirectory.
+ */
+export interface ScanLocation {
+    /** Directory relative to the content root, e.g. `pages` or `fragments`. */
+    dir: string;
+    /** Manifest filename to capture, e.g. `page.json` or `fragment.json`. */
+    manifest: string;
+}
+/**
+ * Built-in content locations Gazetta knows about today. Callers can
+ * pass a superset (e.g. for future data/*, templates/*) — the list is
+ * part of `RecordWriteOptions` so this module stays open for extension
+ * without changes when new content kinds land.
+ */
+export declare const DEFAULT_SCAN_LOCATIONS: readonly ScanLocation[];
+/**
+ * Flat files at the content root to capture in the baseline snapshot
+ * (no per-subdirectory recursion). `site.yaml` is the only one today.
+ */
+export declare const DEFAULT_SCAN_ROOT_FILES: readonly string[];
+export interface RecordWriteOptions {
+    /** HistoryProvider for the target we're recording on. */
+    history: HistoryProvider;
+    /** Content root of the target — used to scan on first revision. */
+    contentRoot: ContentRoot;
+    operation: RevisionOperation;
+    /** Items the save/publish wrote (and optionally deleted). */
+    items: WrittenItem[];
+    /** Author identifier passed through to the manifest. */
+    author?: string;
+    /** Source target name (for publish). */
+    source?: string;
+    /** Optional human-readable note. */
+    message?: string;
+    /** For rollback/restore: the revision id this one restored from. */
+    restoredFrom?: string;
+    /**
+     * Override the directories walked during the first-revision baseline
+     * scan. Defaults to `DEFAULT_SCAN_LOCATIONS` (pages + fragments).
+     * Pass a superset if the site has extra authored content (e.g.
+     * custom `data/*.json` dirs); pass `[]` to skip directory scanning
+     * entirely (only root files + explicit items are captured).
+     */
+    scanLocations?: readonly ScanLocation[];
+    /**
+     * Override the flat files captured from the content root. Defaults
+     * to `DEFAULT_SCAN_ROOT_FILES` (`site.yaml`). Missing files are
+     * silently skipped so empty publish-targets still record cleanly.
+     */
+    scanRootFiles?: readonly string[];
+}
+/**
+ * Build + record a revision for the given write. Reads the previous
+ * snapshot (if any), overlays the delta, and calls
+ * `history.recordRevision`. Returns the recorded Revision.
+ *
+ * Callers are expected to have already written the items to the
+ * target's storage before invoking this; the recorder reads back via
+ * the HistoryProvider's dedup path (blobs it has already seen just
+ * `exists()` and skip) so the happy path is cheap on repeated saves
+ * of the same item.
+ */
+export declare function recordWrite(opts: RecordWriteOptions): Promise<import("./history.js").Revision>;
+//# sourceMappingURL=history-recorder.d.ts.map

package/dist/history-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-recorder.d.ts","sourceRoot":"","sources":["../src/history-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAiB,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAA;IACX,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EAGzD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAkB,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,OAAO,EAAE,eAAe,CAAA;IACxB,mEAAmE;IACnE,WAAW,EAAE,WAAW,CAAA;IACxB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,6DAA6D;IAC7D,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACvC;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,4CAmCzD"}