@xyo-network/xl1-rest-block-publisher 2.1.1 → 2.1.3

package/README.md

@@ -5,26 +5,31 @@
 [![npm-badge][]][npm-link]
 [![license-badge][]][license-link]
 
-> Publishes a finalized XL1 chain's immutable files as the static REST file layout that `RestBlockViewer` reads — pre-compressed, immutable, CDN-friendly.
+> Publishes an XL1 chain as the static REST file layout the Rest viewers read — pre-compressed, CDN-friendly, one runner per concern.
 
 ## About
 
-Finalized blocks and completed steps never change, so the chain can be materialized once as static files on S3-compatible object storage (e.g. Cloudflare R2) and served forever over plain HTTP. `RestBlockPublisher` writes the finalized (immutable) part of that layout from any source `BlockViewer`:
+Finalized blocks and completed steps never change, so the chain can be materialized once as static files on S3-compatible object storage (e.g. Cloudflare R2) and served forever over plain HTTP. Three locator-configurable runners (implementing the `BlockPublishRunner`, `IndexPublishRunner`, and `ChainStatePublishRunner` interfaces from `@xyo-network/xl1-protocol-lib`) write that layout from any source `BlockViewer`:
+
+- **`S3BlockPublishRunner`** — finalized blocks and their payloads
+- **`S3IndexPublishRunner`** — completed steps' block summaries (the chain index)
+- **`S3ChainStatePublishRunner`** — the mutable chain state (the head pointer), targeting the chain-state bucket
 
 ```text
-/block/number/<n>.json            ← immutable
-/block/hash/<hash>.json           ← immutable, same content
-/blocks/step/<level>/<index>.json ← immutable, completed steps only
-/payload/<hash>.json              ← immutable
+/block/number/<n>.json            ← immutable (block runner)
+/block/hash/<hash>.json           ← immutable, same content (block runner)
+/blocks/step/<level>/<index>.json ← immutable, completed steps only (index runner)
+/payload/<hash>.json              ← immutable (block runner)
+/chain/head.json                  ← mutable, chain-state bucket (chain state runner)
 ```
 
-The mutable chain state (the head pointer, `/chain/head.json`) is **not** written by this publisher — it lives in a separate chain-state bucket and is written by the chain's finalizer (the `FinalizerActor` in xyo-chain) after the finalized files for that head exist, so readers never see a head that references missing files.
-
-Bodies are pre-compressed at write time (brotli by default, gzip or none configurable) and stored with the matching `Content-Encoding` plus `application/json`, so HTTP clients decompress transparently — keys keep their `.json` extension. Everything written gets `Cache-Control: public, max-age=31536000, immutable`.
+Bodies are pre-compressed at write time (brotli by default, gzip or none configurable) and stored with the matching `Content-Encoding` plus `application/json`, so HTTP clients decompress transparently — keys keep their `.json` extension. Finalized files get `Cache-Control: public, max-age=31536000, immutable`; the head pointer gets `must-revalidate`.
 
 ```ts
 import { S3Client } from '@aws-sdk/client-s3'
-import { RestBlockPublisher } from '@xyo-network/xl1-rest-block-publisher'
+import {
+  S3BlockPublishRunner, S3ChainStatePublishRunner, S3IndexPublishRunner,
+} from '@xyo-network/xl1-rest-block-publisher'
 
 const client = new S3Client({
   region: 'auto',
@@ -32,11 +37,18 @@ const client = new S3Client({
   credentials: { accessKeyId, secretAccessKey },
 })
 
-const publisher = await RestBlockPublisher.create({ bucket: 'chain', client, source: blockViewer })
-const range = await publisher.sync(from) // publishes [from, sourceHead]; null when up to date
+const blocks = await S3BlockPublishRunner.create({ bucket: 'finalized', client, context, source })
+const index = await S3IndexPublishRunner.create({ bucket: 'finalized', client, context, source })
+const chainState = await S3ChainStatePublishRunner.create({ bucket: 'chain-state', client, context, source })
+
+const range = await blocks.sync(from) // publishes [from, sourceHead]; null when up to date
+if (range) {
+  for (let n = range[0]; n <= range[1]; n++) await index.publishStepsCompletedBy(n)
+  await chainState.publishHead() // last, so readers never see a head referencing missing files
+}
 ```
 
-`sync(from)` resumes from a caller-supplied cursor — typically the block after the last published head pointer, which the finalizer owns. Omitting `from` republishes from genesis, which is safe (idempotent — deterministic keys, immutable content) but slow, so re-running after a crash is always safe. The path builders come from [`@xyo-network/xl1-rest-block-viewer`](https://www.npmjs.com/package/@xyo-network/xl1-rest-block-viewer), so reader and writer share one layout contract.
+`sync(from)` resumes from a caller-supplied cursor — typically the block after the last published head pointer. Omitting `from` republishes from genesis, which is safe (idempotent — deterministic keys, immutable content) but slow, so re-running after a crash is always safe. The path builders come from [`@xyo-network/xl1-rest-block-viewer`](https://www.npmjs.com/package/@xyo-network/xl1-rest-block-viewer), so readers and writers share one layout contract.
 
 ## Install
 
@@ -68,7 +80,10 @@ bun add @xyo-network/xl1-rest-block-publisher
 
 ## What's Inside
 
-- **`RestBlockPublisher`** — `sync(from)` (cursor-resumed publish), `publishBlock`, `publishStep`/`publishStepsCompletedBy` (completed steps only).
+- **`S3BlockPublishRunner`** — `sync(from)` (cursor-resumed publish) and `publishBlock`; implements `BlockPublishRunner`.
+- **`S3IndexPublishRunner`** — `publishStep`/`publishStepsCompletedBy` (completed steps only); implements `IndexPublishRunner`.
+- **`S3ChainStatePublishRunner`** — `publishHead` with must-revalidate caching; implements `ChainStatePublishRunner`.
+- **`AbstractS3PublishRunner`** — shared S3 target params (bucket, client, prefix, encoding) for custom runners.
 - **`encodeBody`/`decodeBody`** — brotli/gzip/none body codecs used for storage and read-back.
 
 ## Building Locally

package/dist/node/AbstractS3PublishRunner.d.ts

@@ -0,0 +1,31 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { CreatableProviderParams } from '@xyo-network/xl1-protocol-sdk';
+import { AbstractCreatableProvider } from '@xyo-network/xl1-protocol-sdk';
+import type { RestContentEncoding } from './encoding.ts';
+/** Shared parameters for S3 publish runners: where and how published files are written. */
+export interface S3PublishRunnerParams extends CreatableProviderParams {
+    bucket: string;
+    /** S3-compatible client pointed at the target endpoint (e.g. Cloudflare R2). */
+    client: S3Client;
+    /** Storage/wire encoding for published files. Defaults to 'br' (brotli). */
+    contentEncoding?: RestContentEncoding;
+    /** Optional key prefix, allowing the layout to live in a shared bucket. */
+    prefix?: string;
+}
+/** Finalized files never change once written. */
+export declare const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Chain state is rewritten as the chain advances. */
+export declare const MUTABLE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+/**
+ * Base for publish runners targeting S3-compatible storage. Bodies are pre-compressed at
+ * write time and stored with the matching Content-Encoding plus application/json, so HTTP
+ * clients decompress transparently — keys keep their `.json` extension.
+ */
+export declare abstract class AbstractS3PublishRunner<TParams extends S3PublishRunnerParams = S3PublishRunnerParams> extends AbstractCreatableProvider<TParams> {
+    get bucket(): string;
+    get client(): S3Client;
+    get contentEncoding(): RestContentEncoding;
+    get prefix(): string;
+    protected putJson(path: string, json: string, cacheControl: string): Promise<void>;
+}
+//# sourceMappingURL=AbstractS3PublishRunner.d.ts.map

package/dist/node/AbstractS3PublishRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractS3PublishRunner.d.ts","sourceRoot":"","sources":["../../src/AbstractS3PublishRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAEzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGxD,2FAA2F;AAC3F,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,MAAM,EAAE,QAAQ,CAAA;IAChB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,mBAAmB,CAAA;IACrC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,wCAAwC,CAAA;AAC5E,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,uCAAuC,CAAA;AAEzE;;;;GAIG;AACH,8BAAsB,uBAAuB,CAAC,OAAO,SAAS,qBAAqB,GAAG,qBAAqB,CACzG,SAAQ,yBAAyB,CAAC,OAAO,CAAC;IAC1C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,IAAI,QAAQ,CAErB;IAED,IAAI,eAAe,IAAI,mBAAmB,CAEzC;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;cAEe,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAWzF"}

package/dist/node/S3BlockPublishRunner.d.ts

@@ -0,0 +1,50 @@
+import type { BlockPublishRunner, BlockViewer, SignedHydratedBlockWithHashMeta, XL1BlockNumber, XL1BlockRange } from '@xyo-network/xl1-protocol-lib';
+import type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts';
+import { AbstractS3PublishRunner } from './AbstractS3PublishRunner.ts';
+/** A progress event emitted while publishing blocks. */
+export interface BlockPublishProgress {
+    blockNumber: XL1BlockNumber;
+    published: number;
+    total: number;
+}
+/** Parameters for S3BlockPublishRunner. */
+export interface S3BlockPublishRunnerParams extends S3PublishRunnerParams {
+    /** Maximum concurrent block publishes during sync. */
+    concurrency?: number;
+    /**
+     * Called every `progressInterval` blocks (and at pass completion). When omitted, the same
+     * events are logged via the params logger so long backfills are observable out of the box.
+     */
+    onProgress?: (event: BlockPublishProgress) => void;
+    /** How many block publishes between progress reports during sync. */
+    progressInterval?: number;
+    /** The viewer to publish from (only finalized chains should be published). */
+    source: BlockViewer;
+}
+/**
+ * Publishes finalized blocks (and their payloads) as the static REST file layout that
+ * `RestBlockViewer` reads (see `paths.ts` in @xyo-network/xl1-rest-block-viewer).
+ *
+ * Publishing is idempotent: keys are deterministic and contents immutable, so re-publishing
+ * any range is safe. `sync(from)` resumes from a caller-supplied cursor (typically the block
+ * after the last published head); omitting it republishes from genesis, which is safe.
+ */
+export declare class S3BlockPublishRunner extends AbstractS3PublishRunner<S3BlockPublishRunnerParams> implements BlockPublishRunner {
+    static readonly defaultMoniker: "BlockPublishRunner";
+    static readonly dependencies: never[];
+    static readonly monikers: "BlockPublishRunner"[];
+    moniker: "BlockPublishRunner";
+    get concurrency(): number;
+    get progressInterval(): number;
+    get source(): BlockViewer;
+    /** Publishes one block at its by-number and by-hash paths, plus its payload files. */
+    publishBlock(blockNumber: XL1BlockNumber): Promise<SignedHydratedBlockWithHashMeta | null>;
+    /**
+     * Publishes every block from `from` (inclusive, default genesis) through the source head.
+     * Returns the published range, or null when already up to date.
+     */
+    sync(from?: XL1BlockNumber): Promise<XL1BlockRange | null>;
+    /** Emits a progress event to the onProgress callback, or logs it when no callback is set. */
+    private report;
+}
+//# sourceMappingURL=S3BlockPublishRunner.d.ts.map

package/dist/node/S3BlockPublishRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3BlockPublishRunner.d.ts","sourceRoot":"","sources":["../../src/S3BlockPublishRunner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAAE,WAAW,EAAE,+BAA+B,EAAE,cAAc,EAAE,aAAa,EAChG,MAAM,+BAA+B,CAAA;AAQtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,uBAAuB,EAA2B,MAAM,8BAA8B,CAAA;AAE/F,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,cAAc,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,qBACa,oBAAqB,SAAQ,uBAAuB,CAAC,0BAA0B,CAAE,YAAW,kBAAkB;IACzH,MAAM,CAAC,QAAQ,CAAC,cAAc,uBAA4B;IAC1D,MAAM,CAAC,QAAQ,CAAC,YAAY,UAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,yBAA8B;IACtD,OAAO,uBAAsC;IAE7C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,sFAAsF;IAChF,YAAY,CAAC,WAAW,EAAE,cAAc,GAAG,OAAO,CAAC,+BAA+B,GAAG,IAAI,CAAC;IAYhG;;;OAGG;IACG,IAAI,CAAC,IAAI,GAAE,cAA0C,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqB3F,6FAA6F;IAC7F,OAAO,CAAC,MAAM;CAQf"}

package/dist/node/S3ChainStatePublishRunner.d.ts

@@ -0,0 +1,26 @@
+import type { ChainStatePublishRunner, ChainStateViewerMethods, SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol-lib';
+import type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts';
+import { AbstractS3PublishRunner } from './AbstractS3PublishRunner.ts';
+/** Parameters for S3ChainStatePublishRunner. */
+export interface S3ChainStatePublishRunnerParams extends S3PublishRunnerParams {
+    /** Where the current head is read from (any BlockViewer satisfies this). */
+    source: ChainStateViewerMethods;
+}
+/**
+ * Publishes the mutable chain state — the head pointer (`chain/head.json`) — that
+ * `RestChainStateViewer` reads. This is the one mutable file in the REST layout, so it is
+ * stored with must-revalidate caching and should target the chain-state bucket.
+ *
+ * Callers must publish the finalized files for a head before publishing the head itself,
+ * so readers never see a head that references missing files.
+ */
+export declare class S3ChainStatePublishRunner extends AbstractS3PublishRunner<S3ChainStatePublishRunnerParams> implements ChainStatePublishRunner {
+    static readonly defaultMoniker: "ChainStatePublishRunner";
+    static readonly dependencies: never[];
+    static readonly monikers: "ChainStatePublishRunner"[];
+    moniker: "ChainStatePublishRunner";
+    get source(): ChainStateViewerMethods;
+    /** Publishes the source's current head to the mutable chain state pointer. */
+    publishHead(): Promise<SignedHydratedBlockWithHashMeta>;
+}
+//# sourceMappingURL=S3ChainStatePublishRunner.d.ts.map

package/dist/node/S3ChainStatePublishRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ChainStatePublishRunner.d.ts","sourceRoot":"","sources":["../../src/S3ChainStatePublishRunner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EAAE,uBAAuB,EAAE,+BAA+B,EAClF,MAAM,+BAA+B,CAAA;AAKtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,uBAAuB,EAAyB,MAAM,8BAA8B,CAAA;AAE7F,gDAAgD;AAChD,MAAM,WAAW,+BAAgC,SAAQ,qBAAqB;IAC5E,4EAA4E;IAC5E,MAAM,EAAE,uBAAuB,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,qBACa,yBAA0B,SAAQ,uBAAuB,CAAC,+BAA+B,CAAE,YAAW,uBAAuB;IACxI,MAAM,CAAC,QAAQ,CAAC,cAAc,4BAAiC;IAC/D,MAAM,CAAC,QAAQ,CAAC,YAAY,UAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,8BAAmC;IAC3D,OAAO,4BAA2C;IAElD,IAAI,MAAM,IAAI,uBAAuB,CAEpC;IAED,8EAA8E;IACxE,WAAW,IAAI,OAAO,CAAC,+BAA+B,CAAC;CAM9D"}

package/dist/node/S3IndexPublishRunner.d.ts

@@ -0,0 +1,28 @@
+import type { BlockViewer, IndexPublishRunner, XL1BlockNumber } from '@xyo-network/xl1-protocol-lib';
+import type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts';
+import { AbstractS3PublishRunner } from './AbstractS3PublishRunner.ts';
+/** Parameters for S3IndexPublishRunner. */
+export interface S3IndexPublishRunnerParams extends S3PublishRunnerParams {
+    /** The viewer to publish from (only finalized chains should be published). */
+    source: BlockViewer;
+}
+/**
+ * Publishes completed steps' block summaries (the chain index) as the static REST file
+ * layout that `RestIndexViewer` reads. Step files are immutable: only complete steps are
+ * ever published, and a completed step's blocks never change.
+ */
+export declare class S3IndexPublishRunner extends AbstractS3PublishRunner<S3IndexPublishRunnerParams> implements IndexPublishRunner {
+    static readonly defaultMoniker: "IndexPublishRunner";
+    static readonly dependencies: never[];
+    static readonly monikers: "IndexPublishRunner"[];
+    moniker: "IndexPublishRunner";
+    get source(): BlockViewer;
+    /**
+     * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).
+     * Asserts the step is complete — partial tail steps are never published.
+     */
+    publishStep(stepLevel: number, stepIndex: number): Promise<void>;
+    /** Publishes every step (at every level) completed by the given block. */
+    publishStepsCompletedBy(blockNumber: XL1BlockNumber): Promise<void>;
+}
+//# sourceMappingURL=S3IndexPublishRunner.d.ts.map

package/dist/node/S3IndexPublishRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3IndexPublishRunner.d.ts","sourceRoot":"","sources":["../../src/S3IndexPublishRunner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACS,WAAW,EAAE,kBAAkB,EAAE,cAAc,EACnE,MAAM,+BAA+B,CAAA;AAOtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,uBAAuB,EAA2B,MAAM,8BAA8B,CAAA;AAE/F,2CAA2C;AAC3C,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;;GAIG;AACH,qBACa,oBAAqB,SAAQ,uBAAuB,CAAC,0BAA0B,CAAE,YAAW,kBAAkB;IACzH,MAAM,CAAC,QAAQ,CAAC,cAAc,uBAA4B;IAC1D,MAAM,CAAC,QAAQ,CAAC,YAAY,UAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,yBAA8B;IACtD,OAAO,uBAAsC;IAE7C,IAAI,MAAM,IAAI,WAAW,CAExB;IAED;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBtE,0EAA0E;IACpE,uBAAuB,CAAC,WAAW,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ1E"}

package/dist/node/index.d.ts

@@ -1,3 +1,6 @@
+export * from './AbstractS3PublishRunner.ts';
 export * from './encoding.ts';
-export * from './RestBlockPublisher.ts';
+export * from './S3BlockPublishRunner.ts';
+export * from './S3ChainStatePublishRunner.ts';
+export * from './S3IndexPublishRunner.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAA;AAC5C,cAAc,eAAe,CAAA;AAC7B,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,2BAA2B,CAAA"}

package/dist/node/index.mjs

@@ -1,5 +1,6 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __decorateClass = (decorators, target, key, kind) => {
   var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
@@ -8,6 +9,12 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/AbstractS3PublishRunner.ts
+import { PutObjectCommand } from "@aws-sdk/client-s3";
+import { assertEx } from "@xylabs/sdk-js";
+import { AbstractCreatableProvider } from "@xyo-network/xl1-protocol-sdk";
 
 // src/encoding.ts
 import ZLIB from "node:zlib";
@@ -38,100 +45,71 @@ function decodeBody(body, contentEncoding) {
   }
 }
 
-// src/RestBlockPublisher.ts
-import { PutObjectCommand } from "@aws-sdk/client-s3";
-import {
-  AbstractCreatable,
-  assertEx,
-  creatable,
-  isNull
-} from "@xylabs/sdk-js";
-import { asXL1BlockNumber, StepSizes } from "@xyo-network/xl1-protocol-lib";
-import { blocksMaxStep, BlocksStepSummarySchema } from "@xyo-network/xl1-protocol-sdk";
-import {
-  blockHashPath,
-  blockNumberPath,
-  blocksStepPath,
-  payloadPath
-} from "@xyo-network/xl1-rest-block-viewer";
-import { Semaphore } from "async-mutex";
+// src/AbstractS3PublishRunner.ts
 var IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
-var RestBlockPublisher = class extends AbstractCreatable {
+var MUTABLE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+var AbstractS3PublishRunner = class extends AbstractCreatableProvider {
   get bucket() {
     return assertEx(this.params.bucket, () => "No bucket specified");
   }
   get client() {
     return assertEx(this.params.client, () => "No client specified");
   }
-  get concurrency() {
-    return this.params.concurrency ?? 8;
-  }
   get contentEncoding() {
     return this.params.contentEncoding ?? "br";
   }
   get prefix() {
     return this.params.prefix ?? "";
   }
+  async putJson(path, json, cacheControl) {
+    const { body, contentEncoding } = encodeBody(json, this.contentEncoding);
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: `${this.prefix}${path}`,
+      Body: body,
+      CacheControl: cacheControl,
+      ContentEncoding: contentEncoding,
+      ContentType: "application/json"
+    }));
+  }
+};
+
+// src/S3BlockPublishRunner.ts
+import { assertEx as assertEx2, isNull } from "@xylabs/sdk-js";
+import { asXL1BlockNumber, BlockPublishRunnerMoniker } from "@xyo-network/xl1-protocol-lib";
+import { creatableProvider } from "@xyo-network/xl1-protocol-sdk";
+import {
+  blockHashPath,
+  blockNumberPath,
+  payloadPath
+} from "@xyo-network/xl1-rest-block-viewer";
+import { Semaphore } from "async-mutex";
+var S3BlockPublishRunner = class extends AbstractS3PublishRunner {
+  moniker = S3BlockPublishRunner.defaultMoniker;
+  get concurrency() {
+    return this.params.concurrency ?? 8;
+  }
   get progressInterval() {
     return this.params.progressInterval ?? 100;
   }
   get source() {
-    return assertEx(this.params.source, () => "No source specified");
+    return assertEx2(this.params.source, () => "No source specified");
   }
   /** Publishes one block at its by-number and by-hash paths, plus its payload files. */
   async publishBlock(blockNumber) {
     const block = await this.source.blockByNumber(blockNumber);
     if (isNull(block)) return null;
     const json = JSON.stringify(block);
-    await this.putJson(blockNumberPath(block[0].block), json);
-    await this.putJson(blockHashPath(block[0]._hash), json);
+    await this.putJson(blockNumberPath(block[0].block), json, IMMUTABLE_CACHE_CONTROL);
+    await this.putJson(blockHashPath(block[0]._hash), json, IMMUTABLE_CACHE_CONTROL);
     for (const payload of block[1]) {
-      await this.putJson(payloadPath(payload._hash), JSON.stringify(payload));
+      await this.putJson(payloadPath(payload._hash), JSON.stringify(payload), IMMUTABLE_CACHE_CONTROL);
     }
     return block;
   }
   /**
-   * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).
-   * Asserts the step is complete — partial tail steps are never published.
-   */
-  async publishStep(stepLevel, stepIndex) {
-    const size = StepSizes[stepLevel];
-    assertEx(stepLevel <= blocksMaxStep, () => `publishStep does not support step levels above ${blocksMaxStep} (requested ${stepLevel})`);
-    const lastBlockNumber = (stepIndex + 1) * size - 1;
-    const headNumber = await this.source.currentBlockNumber();
-    assertEx(lastBlockNumber <= headNumber, () => `Step ${stepLevel}/${stepIndex} is not complete (head ${headNumber})`);
-    const newestFirst = await this.source.blocksByStep(stepLevel, stepIndex);
-    const blocks = newestFirst.toReversed();
-    const summary = {
-      schema: BlocksStepSummarySchema,
-      hash: assertEx(blocks.at(-1), () => `No blocks for step ${stepLevel}/${stepIndex}`)[0]._hash,
-      stepSize: size,
-      blocks
-    };
-    await this.putJson(blocksStepPath(stepLevel, stepIndex), JSON.stringify(summary));
-    this.report({
-      stepIndex,
-      stepLevel,
-      type: "step"
-    });
-  }
-  /** Publishes every step (at every level) completed by the given block. */
-  async publishStepsCompletedBy(blockNumber) {
-    for (let stepLevel = 0; stepLevel <= blocksMaxStep; stepLevel++) {
-      const size = StepSizes[stepLevel];
-      if ((blockNumber + 1) % size === 0) {
-        await this.publishStep(stepLevel, (blockNumber + 1) / size - 1);
-      }
-    }
-  }
-  /**
-   * Publishes everything from `from` (inclusive, default genesis) to the source head
-   * (inclusive), then the completed steps in that range. Returns the published range, or
-   * null when already up to date.
-   *
-   * The caller supplies the resume cursor — typically the block after the last published
-   * head pointer, which is written by the finalizer rather than this publisher. Omitting
-   * `from` republishes from genesis, which is safe (idempotent) but slow.
+   * Publishes every block from `from` (inclusive, default genesis) through the source head.
+   * Returns the published range, or null when already up to date.
    */
   async sync(from = asXL1BlockNumber(0, true)) {
     const sourceHead = await this.source.currentBlock();
@@ -142,33 +120,18 @@ var RestBlockPublisher = class extends AbstractCreatable {
     const total = numbers.length;
     let publishedCount = 0;
     await Promise.all(numbers.map((blockNumber) => semaphore.runExclusive(async () => {
-      assertEx(await this.publishBlock(blockNumber), () => `Block not found in source [${blockNumber}]`);
+      assertEx2(await this.publishBlock(blockNumber), () => `Block not found in source [${blockNumber}]`);
       publishedCount += 1;
       if (publishedCount % this.progressInterval === 0 || publishedCount === total) {
         this.report({
           blockNumber,
           published: publishedCount,
-          total,
-          type: "block"
+          total
         });
       }
     })));
-    for (const blockNumber of numbers) {
-      await this.publishStepsCompletedBy(blockNumber);
-    }
     return [from, end];
   }
-  async putJson(path, json) {
-    const { body, contentEncoding } = encodeBody(json, this.contentEncoding);
-    await this.client.send(new PutObjectCommand({
-      Bucket: this.bucket,
-      Key: `${this.prefix}${path}`,
-      Body: body,
-      CacheControl: IMMUTABLE_CACHE_CONTROL,
-      ContentEncoding: contentEncoding,
-      ContentType: "application/json"
-    }));
-  }
   /** Emits a progress event to the onProgress callback, or logs it when no callback is set. */
   report(event) {
     const onProgress = this.params.onProgress;
@@ -176,23 +139,99 @@ var RestBlockPublisher = class extends AbstractCreatable {
       onProgress(event);
       return;
     }
-    switch (event.type) {
-      case "block": {
-        this.logger?.info(`RestBlockPublisher: published block ${event.blockNumber} (${event.published}/${event.total})`);
-        break;
-      }
-      case "step": {
-        this.logger?.info(`RestBlockPublisher: published step ${event.stepLevel}/${event.stepIndex}`);
-        break;
+    this.logger?.info(`S3BlockPublishRunner: published block ${event.blockNumber} (${event.published}/${event.total})`);
+  }
+};
+__publicField(S3BlockPublishRunner, "defaultMoniker", BlockPublishRunnerMoniker);
+__publicField(S3BlockPublishRunner, "dependencies", []);
+__publicField(S3BlockPublishRunner, "monikers", [BlockPublishRunnerMoniker]);
+S3BlockPublishRunner = __decorateClass([
+  creatableProvider()
+], S3BlockPublishRunner);
+
+// src/S3ChainStatePublishRunner.ts
+import { assertEx as assertEx3 } from "@xylabs/sdk-js";
+import { ChainStatePublishRunnerMoniker } from "@xyo-network/xl1-protocol-lib";
+import { creatableProvider as creatableProvider2 } from "@xyo-network/xl1-protocol-sdk";
+import { headPath } from "@xyo-network/xl1-rest-block-viewer";
+var S3ChainStatePublishRunner = class extends AbstractS3PublishRunner {
+  moniker = S3ChainStatePublishRunner.defaultMoniker;
+  get source() {
+    return assertEx3(this.params.source, () => "No source specified");
+  }
+  /** Publishes the source's current head to the mutable chain state pointer. */
+  async publishHead() {
+    const head = await this.source.currentBlock();
+    await this.putJson(headPath(), JSON.stringify(head), MUTABLE_CACHE_CONTROL);
+    this.logger?.info(`S3ChainStatePublishRunner: published head ${head[0].block}`);
+    return head;
+  }
+};
+__publicField(S3ChainStatePublishRunner, "defaultMoniker", ChainStatePublishRunnerMoniker);
+__publicField(S3ChainStatePublishRunner, "dependencies", []);
+__publicField(S3ChainStatePublishRunner, "monikers", [ChainStatePublishRunnerMoniker]);
+S3ChainStatePublishRunner = __decorateClass([
+  creatableProvider2()
+], S3ChainStatePublishRunner);
+
+// src/S3IndexPublishRunner.ts
+import { assertEx as assertEx4 } from "@xylabs/sdk-js";
+import {
+  BlocksStepSummarySchema,
+  IndexPublishRunnerMoniker,
+  StepSizes
+} from "@xyo-network/xl1-protocol-lib";
+import { blocksMaxStep, creatableProvider as creatableProvider3 } from "@xyo-network/xl1-protocol-sdk";
+import { blocksStepPath } from "@xyo-network/xl1-rest-block-viewer";
+var S3IndexPublishRunner = class extends AbstractS3PublishRunner {
+  moniker = S3IndexPublishRunner.defaultMoniker;
+  get source() {
+    return assertEx4(this.params.source, () => "No source specified");
+  }
+  /**
+   * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).
+   * Asserts the step is complete — partial tail steps are never published.
+   */
+  async publishStep(stepLevel, stepIndex) {
+    const size = StepSizes[stepLevel];
+    assertEx4(stepLevel <= blocksMaxStep, () => `publishStep does not support step levels above ${blocksMaxStep} (requested ${stepLevel})`);
+    const lastBlockNumber = (stepIndex + 1) * size - 1;
+    const headNumber = await this.source.currentBlockNumber();
+    assertEx4(lastBlockNumber <= headNumber, () => `Step ${stepLevel}/${stepIndex} is not complete (head ${headNumber})`);
+    const newestFirst = await this.source.blocksByStep(stepLevel, stepIndex);
+    const blocks = newestFirst.toReversed();
+    const summary = {
+      schema: BlocksStepSummarySchema,
+      hash: assertEx4(blocks.at(-1), () => `No blocks for step ${stepLevel}/${stepIndex}`)[0]._hash,
+      stepSize: size,
+      blocks
+    };
+    await this.putJson(blocksStepPath(stepLevel, stepIndex), JSON.stringify(summary), IMMUTABLE_CACHE_CONTROL);
+    this.logger?.info(`S3IndexPublishRunner: published step ${stepLevel}/${stepIndex}`);
+  }
+  /** Publishes every step (at every level) completed by the given block. */
+  async publishStepsCompletedBy(blockNumber) {
+    for (let stepLevel = 0; stepLevel <= blocksMaxStep; stepLevel++) {
+      const size = StepSizes[stepLevel];
+      if ((blockNumber + 1) % size === 0) {
+        await this.publishStep(stepLevel, (blockNumber + 1) / size - 1);
       }
     }
   }
 };
-RestBlockPublisher = __decorateClass([
-  creatable()
-], RestBlockPublisher);
+__publicField(S3IndexPublishRunner, "defaultMoniker", IndexPublishRunnerMoniker);
+__publicField(S3IndexPublishRunner, "dependencies", []);
+__publicField(S3IndexPublishRunner, "monikers", [IndexPublishRunnerMoniker]);
+S3IndexPublishRunner = __decorateClass([
+  creatableProvider3()
+], S3IndexPublishRunner);
 export {
-  RestBlockPublisher,
+  AbstractS3PublishRunner,
+  IMMUTABLE_CACHE_CONTROL,
+  MUTABLE_CACHE_CONTROL,
+  S3BlockPublishRunner,
+  S3ChainStatePublishRunner,
+  S3IndexPublishRunner,
   decodeBody,
   encodeBody
 };

package/dist/node/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/encoding.ts", "../../src/RestBlockPublisher.ts"],
-  "sourcesContent": ["import ZLIB from 'node:zlib'\n\n/** Wire/storage encoding for published files. */\nexport type RestContentEncoding = 'br' | 'gzip' | 'none'\n\n/** An encoded file body plus the HTTP Content-Encoding it should be served with. */\nexport interface EncodedBody {\n  body: Uint8Array\n  contentEncoding?: 'br' | 'gzip'\n}\n\n/**\n * Encodes a JSON string for storage. Bodies are pre-compressed at write time and stored\n * with the matching Content-Encoding so HTTP clients decompress transparently \u2014 keys keep\n * their .json extension and Content-Type stays application/json.\n */\nexport function encodeBody(json: string, encoding: RestContentEncoding): EncodedBody {\n  switch (encoding) {\n    case 'br': {\n      return { body: ZLIB.brotliCompressSync(json), contentEncoding: 'br' }\n    }\n    case 'gzip': {\n      return { body: ZLIB.gzipSync(json), contentEncoding: 'gzip' }\n    }\n    case 'none': {\n      return { body: new TextEncoder().encode(json) }\n    }\n  }\n}\n\n/** Decodes a stored body back to its JSON string using the object's Content-Encoding. */\nexport function decodeBody(body: Uint8Array, contentEncoding?: string): string {\n  switch (contentEncoding) {\n    case 'br': {\n      return ZLIB.brotliDecompressSync(body).toString('utf8')\n    }\n    case 'gzip': {\n      return ZLIB.gunzipSync(body).toString('utf8')\n    }\n    default: {\n      return new TextDecoder().decode(body)\n    }\n  }\n}\n", "import type { S3Client } from '@aws-sdk/client-s3'\nimport { PutObjectCommand } from '@aws-sdk/client-s3'\nimport type { CreatableParams } from '@xylabs/sdk-js'\nimport {\n  AbstractCreatable, assertEx, creatable, isNull,\n} from '@xylabs/sdk-js'\nimport type {\n  BlockViewer, SignedHydratedBlockWithHashMeta, XL1BlockNumber, XL1BlockRange,\n} from '@xyo-network/xl1-protocol-lib'\nimport { asXL1BlockNumber, StepSizes } from '@xyo-network/xl1-protocol-lib'\nimport type { BlocksStepSummary } from '@xyo-network/xl1-protocol-sdk'\nimport { blocksMaxStep, BlocksStepSummarySchema } from '@xyo-network/xl1-protocol-sdk'\nimport {\n  blockHashPath, blockNumberPath, blocksStepPath, payloadPath,\n} from '@xyo-network/xl1-rest-block-viewer'\nimport { Semaphore } from 'async-mutex'\n\nimport type { RestContentEncoding } from './encoding.ts'\nimport { encodeBody } from './encoding.ts'\n\n/** A progress event emitted while publishing. */\nexport type RestPublishEvent\n  = | { blockNumber: XL1BlockNumber; published: number; total: number; type: 'block' }\n    | { stepIndex: number; stepLevel: number; type: 'step' }\n\n/** Parameters for RestBlockPublisher. */\nexport interface RestBlockPublisherParams extends CreatableParams {\n  bucket: string\n  /** S3-compatible client pointed at the target endpoint (e.g. Cloudflare R2). */\n  client: S3Client\n  /** Maximum concurrent block publishes during sync. */\n  concurrency?: number\n  /** Storage/wire encoding for published files. Defaults to 'br' (brotli). */\n  contentEncoding?: RestContentEncoding\n  /**\n   * Called as publishing progresses: every `progressInterval` blocks (and at pass completion)\n   * and per step file. When omitted, the same events are logged via the params logger so\n   * long backfills are observable out of the box.\n   */\n  onProgress?: (event: RestPublishEvent) => void\n  /** Optional key prefix, allowing the layout to live in a shared bucket. */\n  prefix?: string\n  /** How many block publishes between progress reports during sync. */\n  progressInterval?: number\n  /** The viewer to publish from (only finalized chains should be published). */\n  source: BlockViewer\n}\n\n/** Everything this publisher writes is immutable once written. */\nconst IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable'\n\n/**\n * Publishes a chain's immutable files as the static REST file layout that `RestBlockViewer`\n * reads (see `paths.ts` in @xyo-network/xl1-rest-block-viewer).\n *\n * The mutable chain state (the head pointer, `chain/head.json`) is NOT written here \u2014 it\n * lives in a separate chain-state bucket and is written by the chain's finalizer after the\n * finalized files for that head exist, so readers never see a head that references missing\n * files.\n *\n * Publishing is idempotent: keys are deterministic and contents immutable, so re-publishing\n * any range is safe. `sync(from)` resumes from a caller-supplied cursor (typically the block\n * after the last published head); omitting it republishes from genesis, which is safe.\n */\n@creatable()\nexport class RestBlockPublisher extends AbstractCreatable<RestBlockPublisherParams> {\n  get bucket(): string {\n    return assertEx(this.params.bucket, () => 'No bucket specified')\n  }\n\n  get client(): S3Client {\n    return assertEx(this.params.client, () => 'No client specified')\n  }\n\n  get concurrency(): number {\n    return this.params.concurrency ?? 8\n  }\n\n  get contentEncoding(): RestContentEncoding {\n    return this.params.contentEncoding ?? 'br'\n  }\n\n  get prefix(): string {\n    return this.params.prefix ?? ''\n  }\n\n  get progressInterval(): number {\n    return this.params.progressInterval ?? 100\n  }\n\n  get source(): BlockViewer {\n    return assertEx(this.params.source, () => 'No source specified')\n  }\n\n  /** Publishes one block at its by-number and by-hash paths, plus its payload files. */\n  async publishBlock(blockNumber: XL1BlockNumber): Promise<SignedHydratedBlockWithHashMeta | null> {\n    const block = await this.source.blockByNumber(blockNumber)\n    if (isNull(block)) return null\n    const json = JSON.stringify(block)\n    await this.putJson(blockNumberPath(block[0].block), json)\n    await this.putJson(blockHashPath(block[0]._hash), json)\n    for (const payload of block[1]) {\n      await this.putJson(payloadPath(payload._hash), JSON.stringify(payload))\n    }\n    return block\n  }\n\n  /**\n   * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).\n   * Asserts the step is complete \u2014 partial tail steps are never published.\n   */\n  async publishStep(stepLevel: number, stepIndex: number): Promise<void> {\n    const size = StepSizes[stepLevel]\n    assertEx(stepLevel <= blocksMaxStep, () => `publishStep does not support step levels above ${blocksMaxStep} (requested ${stepLevel})`)\n    const lastBlockNumber = (stepIndex + 1) * size - 1\n    const headNumber = await this.source.currentBlockNumber()\n    assertEx(lastBlockNumber <= headNumber, () => `Step ${stepLevel}/${stepIndex} is not complete (head ${headNumber})`)\n    const newestFirst = await this.source.blocksByStep(stepLevel, stepIndex)\n    const blocks = newestFirst.toReversed()\n    const summary: BlocksStepSummary = {\n      schema: BlocksStepSummarySchema,\n      hash: assertEx(blocks.at(-1), () => `No blocks for step ${stepLevel}/${stepIndex}`)[0]._hash,\n      stepSize: size,\n      blocks,\n    }\n    await this.putJson(blocksStepPath(stepLevel, stepIndex), JSON.stringify(summary))\n    this.report({\n      stepIndex, stepLevel, type: 'step',\n    })\n  }\n\n  /** Publishes every step (at every level) completed by the given block. */\n  async publishStepsCompletedBy(blockNumber: XL1BlockNumber): Promise<void> {\n    for (let stepLevel = 0; stepLevel <= blocksMaxStep; stepLevel++) {\n      const size = StepSizes[stepLevel]\n      if ((blockNumber + 1) % size === 0) {\n        await this.publishStep(stepLevel, (blockNumber + 1) / size - 1)\n      }\n    }\n  }\n\n  /**\n   * Publishes everything from `from` (inclusive, default genesis) to the source head\n   * (inclusive), then the completed steps in that range. Returns the published range, or\n   * null when already up to date.\n   *\n   * The caller supplies the resume cursor \u2014 typically the block after the last published\n   * head pointer, which is written by the finalizer rather than this publisher. Omitting\n   * `from` republishes from genesis, which is safe (idempotent) but slow.\n   */\n  async sync(from: XL1BlockNumber = asXL1BlockNumber(0, true)): Promise<XL1BlockRange | null> {\n    const sourceHead = await this.source.currentBlock()\n    const end = sourceHead[0].block\n    if (from > end) return null\n\n    const semaphore = new Semaphore(this.concurrency)\n    const numbers = Array.from({ length: end - from + 1 }, (_, i) => asXL1BlockNumber(from + i, true))\n    const total = numbers.length\n    let publishedCount = 0\n    await Promise.all(numbers.map(blockNumber => semaphore.runExclusive(async () => {\n      assertEx(await this.publishBlock(blockNumber), () => `Block not found in source [${blockNumber}]`)\n      publishedCount += 1\n      if (publishedCount % this.progressInterval === 0 || publishedCount === total) {\n        this.report({\n          blockNumber, published: publishedCount, total, type: 'block',\n        })\n      }\n    })))\n    for (const blockNumber of numbers) {\n      await this.publishStepsCompletedBy(blockNumber)\n    }\n    return [from, end]\n  }\n\n  private async putJson(path: string, json: string): Promise<void> {\n    const { body, contentEncoding } = encodeBody(json, this.contentEncoding)\n    await this.client.send(new PutObjectCommand({\n      Bucket: this.bucket,\n      Key: `${this.prefix}${path}`,\n      Body: body,\n      CacheControl: IMMUTABLE_CACHE_CONTROL,\n      ContentEncoding: contentEncoding,\n      ContentType: 'application/json',\n    }))\n  }\n\n  /** Emits a progress event to the onProgress callback, or logs it when no callback is set. */\n  private report(event: RestPublishEvent): void {\n    const onProgress = this.params.onProgress\n    if (onProgress) {\n      onProgress(event)\n      return\n    }\n    switch (event.type) {\n      case 'block': {\n        this.logger?.info(`RestBlockPublisher: published block ${event.blockNumber} (${event.published}/${event.total})`)\n        break\n      }\n      case 'step': {\n        this.logger?.info(`RestBlockPublisher: published step ${event.stepLevel}/${event.stepIndex}`)\n        break\n      }\n    }\n  }\n}\n"],
-  "mappings": "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",
-  "names": []
+  "sources": ["../../src/AbstractS3PublishRunner.ts", "../../src/encoding.ts", "../../src/S3BlockPublishRunner.ts", "../../src/S3ChainStatePublishRunner.ts", "../../src/S3IndexPublishRunner.ts"],
+  "sourcesContent": ["import type { S3Client } from '@aws-sdk/client-s3'\nimport { PutObjectCommand } from '@aws-sdk/client-s3'\nimport { assertEx } from '@xylabs/sdk-js'\nimport type { CreatableProviderParams } from '@xyo-network/xl1-protocol-sdk'\nimport { AbstractCreatableProvider } from '@xyo-network/xl1-protocol-sdk'\n\nimport type { RestContentEncoding } from './encoding.ts'\nimport { encodeBody } from './encoding.ts'\n\n/** Shared parameters for S3 publish runners: where and how published files are written. */\nexport interface S3PublishRunnerParams extends CreatableProviderParams {\n  bucket: string\n  /** S3-compatible client pointed at the target endpoint (e.g. Cloudflare R2). */\n  client: S3Client\n  /** Storage/wire encoding for published files. Defaults to 'br' (brotli). */\n  contentEncoding?: RestContentEncoding\n  /** Optional key prefix, allowing the layout to live in a shared bucket. */\n  prefix?: string\n}\n\n/** Finalized files never change once written. */\nexport const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable'\n/** Chain state is rewritten as the chain advances. */\nexport const MUTABLE_CACHE_CONTROL = 'public, max-age=0, must-revalidate'\n\n/**\n * Base for publish runners targeting S3-compatible storage. Bodies are pre-compressed at\n * write time and stored with the matching Content-Encoding plus application/json, so HTTP\n * clients decompress transparently \u2014 keys keep their `.json` extension.\n */\nexport abstract class AbstractS3PublishRunner<TParams extends S3PublishRunnerParams = S3PublishRunnerParams>\n  extends AbstractCreatableProvider<TParams> {\n  get bucket(): string {\n    return assertEx(this.params.bucket, () => 'No bucket specified')\n  }\n\n  get client(): S3Client {\n    return assertEx(this.params.client, () => 'No client specified')\n  }\n\n  get contentEncoding(): RestContentEncoding {\n    return this.params.contentEncoding ?? 'br'\n  }\n\n  get prefix(): string {\n    return this.params.prefix ?? ''\n  }\n\n  protected async putJson(path: string, json: string, cacheControl: string): Promise<void> {\n    const { body, contentEncoding } = encodeBody(json, this.contentEncoding)\n    await this.client.send(new PutObjectCommand({\n      Bucket: this.bucket,\n      Key: `${this.prefix}${path}`,\n      Body: body,\n      CacheControl: cacheControl,\n      ContentEncoding: contentEncoding,\n      ContentType: 'application/json',\n    }))\n  }\n}\n", "import ZLIB from 'node:zlib'\n\n/** Wire/storage encoding for published files. */\nexport type RestContentEncoding = 'br' | 'gzip' | 'none'\n\n/** An encoded file body plus the HTTP Content-Encoding it should be served with. */\nexport interface EncodedBody {\n  body: Uint8Array\n  contentEncoding?: 'br' | 'gzip'\n}\n\n/**\n * Encodes a JSON string for storage. Bodies are pre-compressed at write time and stored\n * with the matching Content-Encoding so HTTP clients decompress transparently \u2014 keys keep\n * their .json extension and Content-Type stays application/json.\n */\nexport function encodeBody(json: string, encoding: RestContentEncoding): EncodedBody {\n  switch (encoding) {\n    case 'br': {\n      return { body: ZLIB.brotliCompressSync(json), contentEncoding: 'br' }\n    }\n    case 'gzip': {\n      return { body: ZLIB.gzipSync(json), contentEncoding: 'gzip' }\n    }\n    case 'none': {\n      return { body: new TextEncoder().encode(json) }\n    }\n  }\n}\n\n/** Decodes a stored body back to its JSON string using the object's Content-Encoding. */\nexport function decodeBody(body: Uint8Array, contentEncoding?: string): string {\n  switch (contentEncoding) {\n    case 'br': {\n      return ZLIB.brotliDecompressSync(body).toString('utf8')\n    }\n    case 'gzip': {\n      return ZLIB.gunzipSync(body).toString('utf8')\n    }\n    default: {\n      return new TextDecoder().decode(body)\n    }\n  }\n}\n", "import { assertEx, isNull } from '@xylabs/sdk-js'\nimport type {\n  BlockPublishRunner, BlockViewer, SignedHydratedBlockWithHashMeta, XL1BlockNumber, XL1BlockRange,\n} from '@xyo-network/xl1-protocol-lib'\nimport { asXL1BlockNumber, BlockPublishRunnerMoniker } from '@xyo-network/xl1-protocol-lib'\nimport { creatableProvider } from '@xyo-network/xl1-protocol-sdk'\nimport {\n  blockHashPath, blockNumberPath, payloadPath,\n} from '@xyo-network/xl1-rest-block-viewer'\nimport { Semaphore } from 'async-mutex'\n\nimport type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts'\nimport { AbstractS3PublishRunner, IMMUTABLE_CACHE_CONTROL } from './AbstractS3PublishRunner.ts'\n\n/** A progress event emitted while publishing blocks. */\nexport interface BlockPublishProgress {\n  blockNumber: XL1BlockNumber\n  published: number\n  total: number\n}\n\n/** Parameters for S3BlockPublishRunner. */\nexport interface S3BlockPublishRunnerParams extends S3PublishRunnerParams {\n  /** Maximum concurrent block publishes during sync. */\n  concurrency?: number\n  /**\n   * Called every `progressInterval` blocks (and at pass completion). When omitted, the same\n   * events are logged via the params logger so long backfills are observable out of the box.\n   */\n  onProgress?: (event: BlockPublishProgress) => void\n  /** How many block publishes between progress reports during sync. */\n  progressInterval?: number\n  /** The viewer to publish from (only finalized chains should be published). */\n  source: BlockViewer\n}\n\n/**\n * Publishes finalized blocks (and their payloads) as the static REST file layout that\n * `RestBlockViewer` reads (see `paths.ts` in @xyo-network/xl1-rest-block-viewer).\n *\n * Publishing is idempotent: keys are deterministic and contents immutable, so re-publishing\n * any range is safe. `sync(from)` resumes from a caller-supplied cursor (typically the block\n * after the last published head); omitting it republishes from genesis, which is safe.\n */\n@creatableProvider()\nexport class S3BlockPublishRunner extends AbstractS3PublishRunner<S3BlockPublishRunnerParams> implements BlockPublishRunner {\n  static readonly defaultMoniker = BlockPublishRunnerMoniker\n  static readonly dependencies = []\n  static readonly monikers = [BlockPublishRunnerMoniker]\n  moniker = S3BlockPublishRunner.defaultMoniker\n\n  get concurrency(): number {\n    return this.params.concurrency ?? 8\n  }\n\n  get progressInterval(): number {\n    return this.params.progressInterval ?? 100\n  }\n\n  get source(): BlockViewer {\n    return assertEx(this.params.source, () => 'No source specified')\n  }\n\n  /** Publishes one block at its by-number and by-hash paths, plus its payload files. */\n  async publishBlock(blockNumber: XL1BlockNumber): Promise<SignedHydratedBlockWithHashMeta | null> {\n    const block = await this.source.blockByNumber(blockNumber)\n    if (isNull(block)) return null\n    const json = JSON.stringify(block)\n    await this.putJson(blockNumberPath(block[0].block), json, IMMUTABLE_CACHE_CONTROL)\n    await this.putJson(blockHashPath(block[0]._hash), json, IMMUTABLE_CACHE_CONTROL)\n    for (const payload of block[1]) {\n      await this.putJson(payloadPath(payload._hash), JSON.stringify(payload), IMMUTABLE_CACHE_CONTROL)\n    }\n    return block\n  }\n\n  /**\n   * Publishes every block from `from` (inclusive, default genesis) through the source head.\n   * Returns the published range, or null when already up to date.\n   */\n  async sync(from: XL1BlockNumber = asXL1BlockNumber(0, true)): Promise<XL1BlockRange | null> {\n    const sourceHead = await this.source.currentBlock()\n    const end = sourceHead[0].block\n    if (from > end) return null\n\n    const semaphore = new Semaphore(this.concurrency)\n    const numbers = Array.from({ length: end - from + 1 }, (_, i) => asXL1BlockNumber(from + i, true))\n    const total = numbers.length\n    let publishedCount = 0\n    await Promise.all(numbers.map(blockNumber => semaphore.runExclusive(async () => {\n      assertEx(await this.publishBlock(blockNumber), () => `Block not found in source [${blockNumber}]`)\n      publishedCount += 1\n      if (publishedCount % this.progressInterval === 0 || publishedCount === total) {\n        this.report({\n          blockNumber, published: publishedCount, total,\n        })\n      }\n    })))\n    return [from, end]\n  }\n\n  /** Emits a progress event to the onProgress callback, or logs it when no callback is set. */\n  private report(event: BlockPublishProgress): void {\n    const onProgress = this.params.onProgress\n    if (onProgress) {\n      onProgress(event)\n      return\n    }\n    this.logger?.info(`S3BlockPublishRunner: published block ${event.blockNumber} (${event.published}/${event.total})`)\n  }\n}\n", "import { assertEx } from '@xylabs/sdk-js'\nimport type {\n  ChainStatePublishRunner, ChainStateViewerMethods, SignedHydratedBlockWithHashMeta,\n} from '@xyo-network/xl1-protocol-lib'\nimport { ChainStatePublishRunnerMoniker } from '@xyo-network/xl1-protocol-lib'\nimport { creatableProvider } from '@xyo-network/xl1-protocol-sdk'\nimport { headPath } from '@xyo-network/xl1-rest-block-viewer'\n\nimport type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts'\nimport { AbstractS3PublishRunner, MUTABLE_CACHE_CONTROL } from './AbstractS3PublishRunner.ts'\n\n/** Parameters for S3ChainStatePublishRunner. */\nexport interface S3ChainStatePublishRunnerParams extends S3PublishRunnerParams {\n  /** Where the current head is read from (any BlockViewer satisfies this). */\n  source: ChainStateViewerMethods\n}\n\n/**\n * Publishes the mutable chain state \u2014 the head pointer (`chain/head.json`) \u2014 that\n * `RestChainStateViewer` reads. This is the one mutable file in the REST layout, so it is\n * stored with must-revalidate caching and should target the chain-state bucket.\n *\n * Callers must publish the finalized files for a head before publishing the head itself,\n * so readers never see a head that references missing files.\n */\n@creatableProvider()\nexport class S3ChainStatePublishRunner extends AbstractS3PublishRunner<S3ChainStatePublishRunnerParams> implements ChainStatePublishRunner {\n  static readonly defaultMoniker = ChainStatePublishRunnerMoniker\n  static readonly dependencies = []\n  static readonly monikers = [ChainStatePublishRunnerMoniker]\n  moniker = S3ChainStatePublishRunner.defaultMoniker\n\n  get source(): ChainStateViewerMethods {\n    return assertEx(this.params.source, () => 'No source specified')\n  }\n\n  /** Publishes the source's current head to the mutable chain state pointer. */\n  async publishHead(): Promise<SignedHydratedBlockWithHashMeta> {\n    const head = await this.source.currentBlock()\n    await this.putJson(headPath(), JSON.stringify(head), MUTABLE_CACHE_CONTROL)\n    this.logger?.info(`S3ChainStatePublishRunner: published head ${head[0].block}`)\n    return head\n  }\n}\n", "import { assertEx } from '@xylabs/sdk-js'\nimport type {\n  BlocksStepSummary, BlockViewer, IndexPublishRunner, XL1BlockNumber,\n} from '@xyo-network/xl1-protocol-lib'\nimport {\n  BlocksStepSummarySchema, IndexPublishRunnerMoniker, StepSizes,\n} from '@xyo-network/xl1-protocol-lib'\nimport { blocksMaxStep, creatableProvider } from '@xyo-network/xl1-protocol-sdk'\nimport { blocksStepPath } from '@xyo-network/xl1-rest-block-viewer'\n\nimport type { S3PublishRunnerParams } from './AbstractS3PublishRunner.ts'\nimport { AbstractS3PublishRunner, IMMUTABLE_CACHE_CONTROL } from './AbstractS3PublishRunner.ts'\n\n/** Parameters for S3IndexPublishRunner. */\nexport interface S3IndexPublishRunnerParams extends S3PublishRunnerParams {\n  /** The viewer to publish from (only finalized chains should be published). */\n  source: BlockViewer\n}\n\n/**\n * Publishes completed steps' block summaries (the chain index) as the static REST file\n * layout that `RestIndexViewer` reads. Step files are immutable: only complete steps are\n * ever published, and a completed step's blocks never change.\n */\n@creatableProvider()\nexport class S3IndexPublishRunner extends AbstractS3PublishRunner<S3IndexPublishRunnerParams> implements IndexPublishRunner {\n  static readonly defaultMoniker = IndexPublishRunnerMoniker\n  static readonly dependencies = []\n  static readonly monikers = [IndexPublishRunnerMoniker]\n  moniker = S3IndexPublishRunner.defaultMoniker\n\n  get source(): BlockViewer {\n    return assertEx(this.params.source, () => 'No source specified')\n  }\n\n  /**\n   * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).\n   * Asserts the step is complete \u2014 partial tail steps are never published.\n   */\n  async publishStep(stepLevel: number, stepIndex: number): Promise<void> {\n    const size = StepSizes[stepLevel]\n    assertEx(stepLevel <= blocksMaxStep, () => `publishStep does not support step levels above ${blocksMaxStep} (requested ${stepLevel})`)\n    const lastBlockNumber = (stepIndex + 1) * size - 1\n    const headNumber = await this.source.currentBlockNumber()\n    assertEx(lastBlockNumber <= headNumber, () => `Step ${stepLevel}/${stepIndex} is not complete (head ${headNumber})`)\n    const newestFirst = await this.source.blocksByStep(stepLevel, stepIndex)\n    const blocks = newestFirst.toReversed()\n    const summary: BlocksStepSummary = {\n      schema: BlocksStepSummarySchema,\n      hash: assertEx(blocks.at(-1), () => `No blocks for step ${stepLevel}/${stepIndex}`)[0]._hash,\n      stepSize: size,\n      blocks,\n    }\n    await this.putJson(blocksStepPath(stepLevel, stepIndex), JSON.stringify(summary), IMMUTABLE_CACHE_CONTROL)\n    this.logger?.info(`S3IndexPublishRunner: published step ${stepLevel}/${stepIndex}`)\n  }\n\n  /** Publishes every step (at every level) completed by the given block. */\n  async publishStepsCompletedBy(blockNumber: XL1BlockNumber): Promise<void> {\n    for (let stepLevel = 0; stepLevel <= blocksMaxStep; stepLevel++) {\n      const size = StepSizes[stepLevel]\n      if ((blockNumber + 1) % size === 0) {\n        await this.publishStep(stepLevel, (blockNumber + 1) / size - 1)\n      }\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["assertEx", "assertEx", "assertEx", "creatableProvider", "assertEx", "creatableProvider", "assertEx", "creatableProvider", "assertEx", "creatableProvider"]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package.json",
   "name": "@xyo-network/xl1-rest-block-publisher",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "XYO Layer One static REST chain layout publisher",
   "homepage": "https://xylabs.com",
   "bugs": {
@@ -35,9 +35,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@xyo-network/xl1-protocol-sdk": "~2.1.1",
-    "@xyo-network/xl1-protocol-lib": "~2.1.1",
-    "@xyo-network/xl1-rest-block-viewer": "~2.1.1"
+    "@xyo-network/xl1-protocol-lib": "~2.1.3",
+    "@xyo-network/xl1-protocol-sdk": "~2.1.3",
+    "@xyo-network/xl1-rest-block-viewer": "~2.1.3"
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.1065.0",

package/dist/node/RestBlockPublisher.d.ts

@@ -1,83 +0,0 @@
-import type { S3Client } from '@aws-sdk/client-s3';
-import type { CreatableParams } from '@xylabs/sdk-js';
-import { AbstractCreatable } from '@xylabs/sdk-js';
-import type { BlockViewer, SignedHydratedBlockWithHashMeta, XL1BlockNumber, XL1BlockRange } from '@xyo-network/xl1-protocol-lib';
-import type { RestContentEncoding } from './encoding.ts';
-/** A progress event emitted while publishing. */
-export type RestPublishEvent = {
-    blockNumber: XL1BlockNumber;
-    published: number;
-    total: number;
-    type: 'block';
-} | {
-    stepIndex: number;
-    stepLevel: number;
-    type: 'step';
-};
-/** Parameters for RestBlockPublisher. */
-export interface RestBlockPublisherParams extends CreatableParams {
-    bucket: string;
-    /** S3-compatible client pointed at the target endpoint (e.g. Cloudflare R2). */
-    client: S3Client;
-    /** Maximum concurrent block publishes during sync. */
-    concurrency?: number;
-    /** Storage/wire encoding for published files. Defaults to 'br' (brotli). */
-    contentEncoding?: RestContentEncoding;
-    /**
-     * Called as publishing progresses: every `progressInterval` blocks (and at pass completion)
-     * and per step file. When omitted, the same events are logged via the params logger so
-     * long backfills are observable out of the box.
-     */
-    onProgress?: (event: RestPublishEvent) => void;
-    /** Optional key prefix, allowing the layout to live in a shared bucket. */
-    prefix?: string;
-    /** How many block publishes between progress reports during sync. */
-    progressInterval?: number;
-    /** The viewer to publish from (only finalized chains should be published). */
-    source: BlockViewer;
-}
-/**
- * Publishes a chain's immutable files as the static REST file layout that `RestBlockViewer`
- * reads (see `paths.ts` in @xyo-network/xl1-rest-block-viewer).
- *
- * The mutable chain state (the head pointer, `chain/head.json`) is NOT written here — it
- * lives in a separate chain-state bucket and is written by the chain's finalizer after the
- * finalized files for that head exist, so readers never see a head that references missing
- * files.
- *
- * Publishing is idempotent: keys are deterministic and contents immutable, so re-publishing
- * any range is safe. `sync(from)` resumes from a caller-supplied cursor (typically the block
- * after the last published head); omitting it republishes from genesis, which is safe.
- */
-export declare class RestBlockPublisher extends AbstractCreatable<RestBlockPublisherParams> {
-    get bucket(): string;
-    get client(): S3Client;
-    get concurrency(): number;
-    get contentEncoding(): RestContentEncoding;
-    get prefix(): string;
-    get progressInterval(): number;
-    get source(): BlockViewer;
-    /** Publishes one block at its by-number and by-hash paths, plus its payload files. */
-    publishBlock(blockNumber: XL1BlockNumber): Promise<SignedHydratedBlockWithHashMeta | null>;
-    /**
-     * Publishes one completed step's blocks as a BlocksStepSummary file (blocks oldest-first).
-     * Asserts the step is complete — partial tail steps are never published.
-     */
-    publishStep(stepLevel: number, stepIndex: number): Promise<void>;
-    /** Publishes every step (at every level) completed by the given block. */
-    publishStepsCompletedBy(blockNumber: XL1BlockNumber): Promise<void>;
-    /**
-     * Publishes everything from `from` (inclusive, default genesis) to the source head
-     * (inclusive), then the completed steps in that range. Returns the published range, or
-     * null when already up to date.
-     *
-     * The caller supplies the resume cursor — typically the block after the last published
-     * head pointer, which is written by the finalizer rather than this publisher. Omitting
-     * `from` republishes from genesis, which is safe (idempotent) but slow.
-     */
-    sync(from?: XL1BlockNumber): Promise<XL1BlockRange | null>;
-    private putJson;
-    /** Emits a progress event to the onProgress callback, or logs it when no callback is set. */
-    private report;
-}
-//# sourceMappingURL=RestBlockPublisher.d.ts.map

package/dist/node/RestBlockPublisher.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"RestBlockPublisher.d.ts","sourceRoot":"","sources":["../../src/RestBlockPublisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EACV,WAAW,EAAE,+BAA+B,EAAE,cAAc,EAAE,aAAa,EAC5E,MAAM,+BAA+B,CAAA;AAStC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGxD,iDAAiD;AACjD,MAAM,MAAM,gBAAgB,GACtB;IAAE,WAAW,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAChF;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,yCAAyC;AACzC,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,MAAM,EAAE,QAAQ,CAAA;IAChB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,mBAAmB,CAAA;IACrC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC9C,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;CACpB;AAKD;;;;;;;;;;;;GAYG;AACH,qBACa,kBAAmB,SAAQ,iBAAiB,CAAC,wBAAwB,CAAC;IACjF,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,IAAI,QAAQ,CAErB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,eAAe,IAAI,mBAAmB,CAEzC;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,sFAAsF;IAChF,YAAY,CAAC,WAAW,EAAE,cAAc,GAAG,OAAO,CAAC,+BAA+B,GAAG,IAAI,CAAC;IAYhG;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBtE,0EAA0E;IACpE,uBAAuB,CAAC,WAAW,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASzE;;;;;;;;OAQG;IACG,IAAI,CAAC,IAAI,GAAE,cAA0C,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAwB7E,OAAO;IAYrB,6FAA6F;IAC7F,OAAO,CAAC,MAAM;CAiBf"}