@secondlayer/shared 7.8.0 → 7.10.0

package/dist/src/archive/derived-stage-report.d.ts

@@ -0,0 +1,99 @@
+/**
+* Derived-stage acceptance — what each service reads, writes, and needs
+* beyond the canonical archive.
+*
+* The canonical archive rebuilds `blocks`, `transactions`, and `events`
+* deterministically from R2 alone. Every stage downstream of those tables
+* (decoders, subgraphs, subscription delivery) has its own inputs, outputs,
+* and rebuild requirements — and an operator restoring from the archive
+* needs to know exactly which of those it also needs to source, replay, or
+* re-derive.
+*
+* This module defines the reporting shape. Each producer/service declares
+* itself once (a `ServiceManifest`) and the aggregator emits one report per
+* service to `reports/derived/<service>.json`. Stateful verification —
+* actually re-running the service and comparing outputs — is Phase 4 work
+* (see P4.10 effect manifests, P4.13 stateful deep verify); this shape is
+* what Phase 4 will populate.
+*
+* The report answers three operator questions:
+*   1. What canonical inputs does this service consume? (archive suffices)
+*   2. What external inputs does it need? (RPC endpoints, envelope journal,
+*      contract source, ORACLE feeds — anything not in the archive)
+*   3. If I restore from R2 alone, can this service resume? If not, what
+*      is missing?
+*
+* Silence is the failure mode we most want to prevent: a service that ships
+* without a manifest is a service whose rebuild story is undocumented.
+* `assertAllServicesDeclared()` fails a build when a known service is missing.
+*/
+declare const DERIVED_STAGE_REPORT_SCHEMA_VERSION: 1;
+type ServiceKind = "decoder" | "subgraph-runtime" | "subscription-runtime" | "protocol-producer";
+type CanonicalInput = "blocks" | "transactions" | "events";
+interface ExternalInput {
+	/** Short name for the dependency: `stacks-node-rpc`, `hiro-extended-api`,
+	*  `observer-journal`, `contract-source-registry`, etc. */
+	name: string;
+	/** Why the archive can't provide this. One sentence. */
+	reason: string;
+	/** Where an operator can source it. `bundled-stacks`, `own-node`,
+	*  `hiro-public-api`, `re-derive-from-events`, `manual-import`. */
+	source: string;
+	/** True if the archive supplies enough to re-derive this dependency
+	*  without a live external source. Rare but happens (e.g. contract ABIs
+	*  derivable from `transactions.raw_tx`). */
+	rebuildable_from_archive: boolean;
+}
+interface Output {
+	/** Table/topic/queue name in the operator's runtime. */
+	target: string;
+	/** How the operator verifies this output — e.g. `row-count`,
+	*  `semantic-digest`, `effect-manifest`, `dlq-empty`. */
+	verification: string;
+}
+interface ServiceManifest {
+	name: string;
+	kind: ServiceKind;
+	description: string;
+	canonical_inputs: CanonicalInput[];
+	external_inputs: ExternalInput[];
+	outputs: Output[];
+	/**
+	* Explicit judgment on whether R2 alone can rebuild this service.
+	* `false` REQUIRES `external_inputs` to name what else is needed.
+	*/
+	r2_alone_can_rebuild: boolean;
+	/** When true, this service can only replay forward from a starting point
+	*  the operator supplies (e.g. a webhook consumer's last-delivered id).
+	*  Publish it, don't hide it. */
+	requires_operator_state: boolean;
+	/** Repo path where the service lives, for cross-reference. */
+	source_path: string;
+}
+interface DerivedStageReport {
+	schema_version: typeof DERIVED_STAGE_REPORT_SCHEMA_VERSION;
+	generated_at: string;
+	services: ServiceManifest[];
+}
+/**
+* Compose a report from a set of registered manifests. Sorts services by name
+* so the JSON is stable across runs — a re-emit with unchanged manifests
+* produces byte-identical output, so an operator can diff two archive
+* publish cycles cleanly.
+*/
+declare function buildDerivedStageReport(manifests: ReadonlyArray<ServiceManifest>, generatedAt: string): DerivedStageReport;
+type ManifestValidationIssue = {
+	name: string
+	problem: string
+};
+/**
+* Enforce the invariants the report shape leaves ambiguous:
+*   - `r2_alone_can_rebuild: false` REQUIRES at least one external input.
+*     Otherwise the report claims a rebuild gap it can't explain, which is
+*     worse than declaring nothing.
+*   - Names are unique — a duplicate is almost always a copy-paste that
+*     silently shadows the earlier declaration.
+*   - Every canonical_input is a real dataset name.
+*/
+declare function validateServiceManifests(manifests: ReadonlyArray<ServiceManifest>): ManifestValidationIssue[];
+export { validateServiceManifests, buildDerivedStageReport, ServiceManifest, ServiceKind, Output, ManifestValidationIssue, ExternalInput, DerivedStageReport, DERIVED_STAGE_REPORT_SCHEMA_VERSION, CanonicalInput };

package/dist/src/archive/derived-stage-report.js

@@ -0,0 +1,64 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/archive/derived-stage-report.ts
+var DERIVED_STAGE_REPORT_SCHEMA_VERSION = 1;
+function buildDerivedStageReport(manifests, generatedAt) {
+  const sorted = [...manifests].sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    schema_version: DERIVED_STAGE_REPORT_SCHEMA_VERSION,
+    generated_at: generatedAt,
+    services: sorted
+  };
+}
+function validateServiceManifests(manifests) {
+  const issues = [];
+  const seen = new Set;
+  const canonicalDatasets = new Set([
+    "blocks",
+    "transactions",
+    "events"
+  ]);
+  for (const m of manifests) {
+    if (seen.has(m.name)) {
+      issues.push({ name: m.name, problem: "duplicate service name" });
+    }
+    seen.add(m.name);
+    if (!m.r2_alone_can_rebuild && m.external_inputs.length === 0) {
+      issues.push({
+        name: m.name,
+        problem: "declares r2_alone_can_rebuild=false but lists no external_inputs — the gap is undocumented"
+      });
+    }
+    for (const input of m.canonical_inputs) {
+      if (!canonicalDatasets.has(input)) {
+        issues.push({
+          name: m.name,
+          problem: `canonical_inputs contains unknown dataset: ${String(input)}`
+        });
+      }
+    }
+  }
+  return issues;
+}
+export {
+  validateServiceManifests,
+  buildDerivedStageReport,
+  DERIVED_STAGE_REPORT_SCHEMA_VERSION
+};
+
+//# debugId=C79406F0A3036B1164756E2164756E21
+//# sourceMappingURL=derived-stage-report.js.map

package/dist/src/archive/derived-stage-report.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/derived-stage-report.ts"],
+  "sourcesContent": [
+    "/**\n * Derived-stage acceptance — what each service reads, writes, and needs\n * beyond the canonical archive.\n *\n * The canonical archive rebuilds `blocks`, `transactions`, and `events`\n * deterministically from R2 alone. Every stage downstream of those tables\n * (decoders, subgraphs, subscription delivery) has its own inputs, outputs,\n * and rebuild requirements — and an operator restoring from the archive\n * needs to know exactly which of those it also needs to source, replay, or\n * re-derive.\n *\n * This module defines the reporting shape. Each producer/service declares\n * itself once (a `ServiceManifest`) and the aggregator emits one report per\n * service to `reports/derived/<service>.json`. Stateful verification —\n * actually re-running the service and comparing outputs — is Phase 4 work\n * (see P4.10 effect manifests, P4.13 stateful deep verify); this shape is\n * what Phase 4 will populate.\n *\n * The report answers three operator questions:\n *   1. What canonical inputs does this service consume? (archive suffices)\n *   2. What external inputs does it need? (RPC endpoints, envelope journal,\n *      contract source, ORACLE feeds — anything not in the archive)\n *   3. If I restore from R2 alone, can this service resume? If not, what\n *      is missing?\n *\n * Silence is the failure mode we most want to prevent: a service that ships\n * without a manifest is a service whose rebuild story is undocumented.\n * `assertAllServicesDeclared()` fails a build when a known service is missing.\n */\n\nexport const DERIVED_STAGE_REPORT_SCHEMA_VERSION = 1 as const;\n\nexport type ServiceKind =\n\t| \"decoder\"\n\t| \"subgraph-runtime\"\n\t| \"subscription-runtime\"\n\t| \"protocol-producer\";\n\nexport type CanonicalInput = \"blocks\" | \"transactions\" | \"events\";\n\nexport interface ExternalInput {\n\t/** Short name for the dependency: `stacks-node-rpc`, `hiro-extended-api`,\n\t *  `observer-journal`, `contract-source-registry`, etc. */\n\tname: string;\n\t/** Why the archive can't provide this. One sentence. */\n\treason: string;\n\t/** Where an operator can source it. `bundled-stacks`, `own-node`,\n\t *  `hiro-public-api`, `re-derive-from-events`, `manual-import`. */\n\tsource: string;\n\t/** True if the archive supplies enough to re-derive this dependency\n\t *  without a live external source. Rare but happens (e.g. contract ABIs\n\t *  derivable from `transactions.raw_tx`). */\n\trebuildable_from_archive: boolean;\n}\n\nexport interface Output {\n\t/** Table/topic/queue name in the operator's runtime. */\n\ttarget: string;\n\t/** How the operator verifies this output — e.g. `row-count`,\n\t *  `semantic-digest`, `effect-manifest`, `dlq-empty`. */\n\tverification: string;\n}\n\nexport interface ServiceManifest {\n\tname: string;\n\tkind: ServiceKind;\n\tdescription: string;\n\tcanonical_inputs: CanonicalInput[];\n\texternal_inputs: ExternalInput[];\n\toutputs: Output[];\n\t/**\n\t * Explicit judgment on whether R2 alone can rebuild this service.\n\t * `false` REQUIRES `external_inputs` to name what else is needed.\n\t */\n\tr2_alone_can_rebuild: boolean;\n\t/** When true, this service can only replay forward from a starting point\n\t *  the operator supplies (e.g. a webhook consumer's last-delivered id).\n\t *  Publish it, don't hide it. */\n\trequires_operator_state: boolean;\n\t/** Repo path where the service lives, for cross-reference. */\n\tsource_path: string;\n}\n\nexport interface DerivedStageReport {\n\tschema_version: typeof DERIVED_STAGE_REPORT_SCHEMA_VERSION;\n\tgenerated_at: string;\n\tservices: ServiceManifest[];\n}\n\n/**\n * Compose a report from a set of registered manifests. Sorts services by name\n * so the JSON is stable across runs — a re-emit with unchanged manifests\n * produces byte-identical output, so an operator can diff two archive\n * publish cycles cleanly.\n */\nexport function buildDerivedStageReport(\n\tmanifests: ReadonlyArray<ServiceManifest>,\n\tgeneratedAt: string,\n): DerivedStageReport {\n\tconst sorted = [...manifests].sort((a, b) => a.name.localeCompare(b.name));\n\treturn {\n\t\tschema_version: DERIVED_STAGE_REPORT_SCHEMA_VERSION,\n\t\tgenerated_at: generatedAt,\n\t\tservices: sorted,\n\t};\n}\n\nexport type ManifestValidationIssue = {\n\tname: string;\n\tproblem: string;\n};\n\n/**\n * Enforce the invariants the report shape leaves ambiguous:\n *   - `r2_alone_can_rebuild: false` REQUIRES at least one external input.\n *     Otherwise the report claims a rebuild gap it can't explain, which is\n *     worse than declaring nothing.\n *   - Names are unique — a duplicate is almost always a copy-paste that\n *     silently shadows the earlier declaration.\n *   - Every canonical_input is a real dataset name.\n */\nexport function validateServiceManifests(\n\tmanifests: ReadonlyArray<ServiceManifest>,\n): ManifestValidationIssue[] {\n\tconst issues: ManifestValidationIssue[] = [];\n\tconst seen = new Set<string>();\n\tconst canonicalDatasets: ReadonlySet<CanonicalInput> = new Set([\n\t\t\"blocks\",\n\t\t\"transactions\",\n\t\t\"events\",\n\t]);\n\tfor (const m of manifests) {\n\t\tif (seen.has(m.name)) {\n\t\t\tissues.push({ name: m.name, problem: \"duplicate service name\" });\n\t\t}\n\t\tseen.add(m.name);\n\t\tif (!m.r2_alone_can_rebuild && m.external_inputs.length === 0) {\n\t\t\tissues.push({\n\t\t\t\tname: m.name,\n\t\t\t\tproblem:\n\t\t\t\t\t\"declares r2_alone_can_rebuild=false but lists no external_inputs — the gap is undocumented\",\n\t\t\t});\n\t\t}\n\t\tfor (const input of m.canonical_inputs) {\n\t\t\tif (!canonicalDatasets.has(input)) {\n\t\t\t\tissues.push({\n\t\t\t\t\tname: m.name,\n\t\t\t\t\tproblem: `canonical_inputs contains unknown dataset: ${String(input)}`,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\treturn issues;\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AA8BO,IAAM,sCAAsC;AAiE5C,SAAS,uBAAuB,CACtC,WACA,aACqB;AAAA,EACrB,MAAM,SAAS,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC;AAAA,EACzE,OAAO;AAAA,IACN,gBAAgB;AAAA,IAChB,cAAc;AAAA,IACd,UAAU;AAAA,EACX;AAAA;AAiBM,SAAS,wBAAwB,CACvC,WAC4B;AAAA,EAC5B,MAAM,SAAoC,CAAC;AAAA,EAC3C,MAAM,OAAO,IAAI;AAAA,EACjB,MAAM,oBAAiD,IAAI,IAAI;AAAA,IAC9D;AAAA,IACA;AAAA,IACA;AAAA,EACD,CAAC;AAAA,EACD,WAAW,KAAK,WAAW;AAAA,IAC1B,IAAI,KAAK,IAAI,EAAE,IAAI,GAAG;AAAA,MACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,yBAAyB,CAAC;AAAA,IAChE;AAAA,IACA,KAAK,IAAI,EAAE,IAAI;AAAA,IACf,IAAI,CAAC,EAAE,wBAAwB,EAAE,gBAAgB,WAAW,GAAG;AAAA,MAC9D,OAAO,KAAK;AAAA,QACX,MAAM,EAAE;AAAA,QACR,SACC;AAAA,MACF,CAAC;AAAA,IACF;AAAA,IACA,WAAW,SAAS,EAAE,kBAAkB;AAAA,MACvC,IAAI,CAAC,kBAAkB,IAAI,KAAK,GAAG;AAAA,QAClC,OAAO,KAAK;AAAA,UACX,MAAM,EAAE;AAAA,UACR,SAAS,8CAA8C,OAAO,KAAK;AAAA,QACpE,CAAC;AAAA,MACF;AAAA,IACD;AAAA,EACD;AAAA,EACA,OAAO;AAAA;",
+  "debugId": "C79406F0A3036B1164756E2164756E21",
+  "names": []
+}

package/dist/src/archive/disk-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+* Free-space guard for bulk archive jobs.
+*
+* Twice on 2026-08-12 a bulk job filled the disk that production Postgres
+* shares: a backfill died at 9.2M/14.4M rows on ENOSPC, and a restore died at
+* 86% of events. Prod survived both, but only just — 2.9GB free with the
+* indexer still ingesting.
+*
+* The failure mode that makes this worth guarding rather than monitoring: the
+* nightly `pg_basebackup` transiently consumes ~150GB, so a job that starts
+* with comfortable headroom can still hit the wall an hour later. Checking
+* once at startup is not enough; the check has to be repeated as the job runs.
+*
+* Waiting is the right response, not failing. The spike passes, and an
+* archive job that pauses for twenty minutes is strictly better than one that
+* dies at 86% or, worse, takes the database down with it.
+*/
+type DiskSpace = {
+	freeBytes: number
+	totalBytes: number
+};
+declare function readDiskSpace(path: string): Promise<DiskSpace>;
+type DiskGuardOptions = {
+	/** Any path on the filesystem to watch. */
+	path: string
+	/** Pause below this many bytes free. */
+	minFreeBytes?: number
+	/** How long to wait between re-checks while paused. */
+	pollMs?: number
+	/** Give up after this long rather than pausing forever. */
+	maxWaitMs?: number
+	onPause?: (free: DiskSpace, waitedMs: number) => void
+	sleep?: (ms: number) => Promise<void>
+	readSpace?: (path: string) => Promise<DiskSpace>
+};
+declare class DiskSpaceExhausted extends Error {
+	constructor(free: number, required: number, waitedMs: number);
+}
+/**
+* Block until there is enough headroom, or throw after `maxWaitMs`.
+*
+* Call this between units of work — before each partition, not once at the
+* start — because the pressure that matters arrives mid-job.
+*/
+declare function waitForDiskSpace(options: DiskGuardOptions): Promise<void>;
+export { waitForDiskSpace, readDiskSpace, DiskSpaceExhausted, DiskSpace, DiskGuardOptions };

package/dist/src/archive/disk-guard.js

@@ -0,0 +1,69 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/archive/disk-guard.ts
+import { statfs } from "node:fs/promises";
+async function readDiskSpace(path) {
+  const stats = await statfs(path);
+  return {
+    freeBytes: stats.bavail * stats.bsize,
+    totalBytes: stats.blocks * stats.bsize
+  };
+}
+var DEFAULT_MIN_FREE_BYTES = 100 * 1024 ** 3;
+var DEFAULT_POLL_MS = 60000;
+var DEFAULT_MAX_WAIT_MS = 2 * 3600000;
+var MAX_THRESHOLD_FRACTION_OF_DISK = 0.25;
+function effectiveThreshold(configured, totalBytes) {
+  if (!Number.isFinite(totalBytes) || totalBytes <= 0)
+    return configured;
+  return Math.min(configured, totalBytes * MAX_THRESHOLD_FRACTION_OF_DISK);
+}
+
+class DiskSpaceExhausted extends Error {
+  constructor(free, required, waitedMs) {
+    super(`only ${(free / 1024 ** 3).toFixed(1)}GB free (need ${(required / 1024 ** 3).toFixed(1)}GB) after waiting ${Math.round(waitedMs / 60000)}m`);
+    this.name = "DiskSpaceExhausted";
+  }
+}
+async function waitForDiskSpace(options) {
+  const minFree = options.minFreeBytes ?? DEFAULT_MIN_FREE_BYTES;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+  const readSpace = options.readSpace ?? readDiskSpace;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let waited = 0;
+  while (true) {
+    const space = await readSpace(options.path);
+    const threshold = effectiveThreshold(minFree, space.totalBytes);
+    if (space.freeBytes >= threshold)
+      return;
+    if (waited >= maxWaitMs) {
+      throw new DiskSpaceExhausted(space.freeBytes, threshold, waited);
+    }
+    options.onPause?.(space, waited);
+    await sleep(pollMs);
+    waited += pollMs;
+  }
+}
+export {
+  waitForDiskSpace,
+  readDiskSpace,
+  DiskSpaceExhausted
+};
+
+//# debugId=F49523DF35B78F5364756E2164756E21
+//# sourceMappingURL=disk-guard.js.map

package/dist/src/archive/disk-guard.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/disk-guard.ts"],
+  "sourcesContent": [
+    "import { statfs } from \"node:fs/promises\";\n\n/**\n * Free-space guard for bulk archive jobs.\n *\n * Twice on 2026-08-12 a bulk job filled the disk that production Postgres\n * shares: a backfill died at 9.2M/14.4M rows on ENOSPC, and a restore died at\n * 86% of events. Prod survived both, but only just — 2.9GB free with the\n * indexer still ingesting.\n *\n * The failure mode that makes this worth guarding rather than monitoring: the\n * nightly `pg_basebackup` transiently consumes ~150GB, so a job that starts\n * with comfortable headroom can still hit the wall an hour later. Checking\n * once at startup is not enough; the check has to be repeated as the job runs.\n *\n * Waiting is the right response, not failing. The spike passes, and an\n * archive job that pauses for twenty minutes is strictly better than one that\n * dies at 86% or, worse, takes the database down with it.\n */\n\nexport type DiskSpace = { freeBytes: number; totalBytes: number };\n\nexport async function readDiskSpace(path: string): Promise<DiskSpace> {\n\tconst stats = await statfs(path);\n\treturn {\n\t\tfreeBytes: stats.bavail * stats.bsize,\n\t\ttotalBytes: stats.blocks * stats.bsize,\n\t};\n}\n\nexport type DiskGuardOptions = {\n\t/** Any path on the filesystem to watch. */\n\tpath: string;\n\t/** Pause below this many bytes free. */\n\tminFreeBytes?: number;\n\t/** How long to wait between re-checks while paused. */\n\tpollMs?: number;\n\t/** Give up after this long rather than pausing forever. */\n\tmaxWaitMs?: number;\n\tonPause?: (free: DiskSpace, waitedMs: number) => void;\n\tsleep?: (ms: number) => Promise<void>;\n\treadSpace?: (path: string) => Promise<DiskSpace>;\n};\n\n/** 100GB: comfortably above the ~39GB an export needs plus the backup spike. */\nconst DEFAULT_MIN_FREE_BYTES = 100 * 1024 ** 3;\nconst DEFAULT_POLL_MS = 60_000;\nconst DEFAULT_MAX_WAIT_MS = 2 * 3_600_000;\n/**\n * A threshold larger than a share of the whole disk is unsatisfiable, not\n * protective: on a 14GB CI runner or a modest VPS, demanding 100GB free would\n * block forever waiting for space that machine can never have. The absolute\n * default is tuned for the production host; this keeps it from becoming a wall\n * everywhere else.\n */\nconst MAX_THRESHOLD_FRACTION_OF_DISK = 0.25;\n\nfunction effectiveThreshold(configured: number, totalBytes: number): number {\n\tif (!Number.isFinite(totalBytes) || totalBytes <= 0) return configured;\n\treturn Math.min(configured, totalBytes * MAX_THRESHOLD_FRACTION_OF_DISK);\n}\n\nexport class DiskSpaceExhausted extends Error {\n\tconstructor(free: number, required: number, waitedMs: number) {\n\t\tsuper(\n\t\t\t`only ${(free / 1024 ** 3).toFixed(1)}GB free (need ${(required / 1024 ** 3).toFixed(1)}GB) after waiting ${Math.round(waitedMs / 60_000)}m`,\n\t\t);\n\t\tthis.name = \"DiskSpaceExhausted\";\n\t}\n}\n\n/**\n * Block until there is enough headroom, or throw after `maxWaitMs`.\n *\n * Call this between units of work — before each partition, not once at the\n * start — because the pressure that matters arrives mid-job.\n */\nexport async function waitForDiskSpace(\n\toptions: DiskGuardOptions,\n): Promise<void> {\n\tconst minFree = options.minFreeBytes ?? DEFAULT_MIN_FREE_BYTES;\n\tconst pollMs = options.pollMs ?? DEFAULT_POLL_MS;\n\tconst maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;\n\tconst readSpace = options.readSpace ?? readDiskSpace;\n\tconst sleep =\n\t\toptions.sleep ??\n\t\t((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));\n\n\tlet waited = 0;\n\twhile (true) {\n\t\tconst space = await readSpace(options.path);\n\t\tconst threshold = effectiveThreshold(minFree, space.totalBytes);\n\t\tif (space.freeBytes >= threshold) return;\n\t\tif (waited >= maxWaitMs) {\n\t\t\tthrow new DiskSpaceExhausted(space.freeBytes, threshold, waited);\n\t\t}\n\t\toptions.onPause?.(space, waited);\n\t\tawait sleep(pollMs);\n\t\twaited += pollMs;\n\t}\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAsBA,eAAsB,aAAa,CAAC,MAAkC;AAAA,EACrE,MAAM,QAAQ,MAAM,OAAO,IAAI;AAAA,EAC/B,OAAO;AAAA,IACN,WAAW,MAAM,SAAS,MAAM;AAAA,IAChC,YAAY,MAAM,SAAS,MAAM;AAAA,EAClC;AAAA;AAkBD,IAAM,yBAAyB,MAAM,QAAQ;AAC7C,IAAM,kBAAkB;AACxB,IAAM,sBAAsB,IAAI;AAQhC,IAAM,iCAAiC;AAEvC,SAAS,kBAAkB,CAAC,YAAoB,YAA4B;AAAA,EAC3E,IAAI,CAAC,OAAO,SAAS,UAAU,KAAK,cAAc;AAAA,IAAG,OAAO;AAAA,EAC5D,OAAO,KAAK,IAAI,YAAY,aAAa,8BAA8B;AAAA;AAAA;AAGjE,MAAM,2BAA2B,MAAM;AAAA,EAC7C,WAAW,CAAC,MAAc,UAAkB,UAAkB;AAAA,IAC7D,MACC,SAAS,OAAO,QAAQ,GAAG,QAAQ,CAAC,mBAAmB,WAAW,QAAQ,GAAG,QAAQ,CAAC,sBAAsB,KAAK,MAAM,WAAW,KAAM,IACzI;AAAA,IACA,KAAK,OAAO;AAAA;AAEd;AAQA,eAAsB,gBAAgB,CACrC,SACgB;AAAA,EAChB,MAAM,UAAU,QAAQ,gBAAgB;AAAA,EACxC,MAAM,SAAS,QAAQ,UAAU;AAAA,EACjC,MAAM,YAAY,QAAQ,aAAa;AAAA,EACvC,MAAM,YAAY,QAAQ,aAAa;AAAA,EACvC,MAAM,QACL,QAAQ,UACP,CAAC,OAAe,IAAI,QAAc,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAAA,EAExE,IAAI,SAAS;AAAA,EACb,OAAO,MAAM;AAAA,IACZ,MAAM,QAAQ,MAAM,UAAU,QAAQ,IAAI;AAAA,IAC1C,MAAM,YAAY,mBAAmB,SAAS,MAAM,UAAU;AAAA,IAC9D,IAAI,MAAM,aAAa;AAAA,MAAW;AAAA,IAClC,IAAI,UAAU,WAAW;AAAA,MACxB,MAAM,IAAI,mBAAmB,MAAM,WAAW,WAAW,MAAM;AAAA,IAChE;AAAA,IACA,QAAQ,UAAU,OAAO,MAAM;AAAA,IAC/B,MAAM,MAAM,MAAM;AAAA,IAClB,UAAU;AAAA,EACX;AAAA;",
+  "debugId": "F49523DF35B78F5364756E2164756E21",
+  "names": []
+}

package/dist/src/archive/per-height-digest.d.ts

@@ -0,0 +1,99 @@
+/**
+* v1 canonical byte encoding for chain identity — the shape that lets
+* independently-run runtimes agree on the same block.
+*
+* The exact-body digest (`sha256:parquet-object`) proves capture fidelity to one
+* source: replay the same bytes, get the same rows. It cannot prove two nodes
+* observed the same chain, because their Parquet encoders legally differ in
+* column padding, compression, JSON key order, and null placement — two
+* operators processing the same block can ship byte-different Parquets that
+* carry identical content.
+*
+* The semantic digest is the shape that lets independent runtimes agree. Every
+* value on a block/transaction/event is normalized into a canonical byte string
+* by rules that MUST NOT change without a version bump. Two v1 computations
+* over the same range agree, or one is wrong about the chain — never about
+* formatting.
+*
+* Encoding rules (v1):
+*   - Fields join with `\x1f` (ASCII US, unit separator — cannot legally
+*     appear in any chain value; a printable delimiter risks collision with
+*     contract-emitted strings).
+*   - Null encodes as `\x00` (single NUL). Distinct from empty string `""`.
+*   - Integers encode as their base-10 string. bigint → decimal string.
+*   - JSON payload columns (function_args, event data) encode as canonical
+*     JSON: object keys sorted lexicographically, no whitespace, bigint →
+*     quoted decimal string, non-finite numbers rejected.
+*   - Field order per record type is fixed and never reordered.
+*   - Digest = sha256(bytes), lowercase hex.
+*
+* Rollup rules (v1) — order MUST match the archive's stream order or an
+* honest re-will disagree with the manifest:
+*   - blocks:       (height asc)
+*   - transactions: (block_height asc, tx_index asc, tx_id asc)
+*   - events:       (block_height asc, event_index asc, tx_id asc)
+* Per-partition rollup is `sha256(concat(row_digest_bytes))` in stream order.
+*
+* Test vectors under `packages/shared/src/archive/__fixtures__/semantic-digest/`
+* pin the encoding. Any change to bytes must bump the spec version.
+*/
+declare const SEMANTIC_DIGEST_SPEC_V1: "sha256:semantic-v1";
+/**
+* Per-height semantic digest sidecars — enable "verify one block" without
+* downloading a whole 50k-block partition.
+*
+* The partition-level semantic digest is the shape a byte-level comparator
+* wants: one string per partition, cheap to compare in bulk. But a caller who
+* only cares about block 8_500_017 has to pull an entire Parquet file to check
+* one row. The per-height sidecar closes that gap: one 32-byte block digest and
+* two roll-up digests per height (transactions and events), addressable by
+* height without touching the raw datasets.
+*
+* Rollup rules (v1) — MUST match the exporter's stream order or an honest
+* re-derivation will disagree:
+*   - transactions_rollup: sha256(concat(tx_digest_bytes, tx_index asc, tx_id asc))
+*     `null` when the height has no transactions.
+*   - events_rollup:       sha256(concat(event_digest_bytes, event_index asc, tx_id asc))
+*     `null` when the height has no events.
+*   - block_digest:        the semantic-v1 block digest itself (one row per
+*                          height, so no rollup needed).
+*
+* `null` is deliberate: an empty rollup is not the sha256 of nothing (which
+* would collide across two empty datasets); an absent-here-but-present-elsewhere
+* dataset must never compare equal to a truly-empty one.
+*/
+interface PerHeightDigestRow {
+	height: number;
+	block_digest: string;
+	transactions_rollup: string | null;
+	events_rollup: string | null;
+}
+declare class PerHeightDigestAccumulator {
+	private readonly rows;
+	setBlockDigest(height: number, blockDigestHex: string): void;
+	appendTransactionDigest(height: number, digestHex: string): void;
+	appendEventDigest(height: number, digestHex: string): void;
+	/**
+	* Drain the accumulator into height-ascending rows. Heights with no block
+	* digest are dropped with a thrown error — a canonical partition MUST have
+	* a block at every height it covers, and silently emitting a row without
+	* one would hide the missing block from downstream verifiers.
+	*/
+	drain(fromBlock: number, toBlock: number): PerHeightDigestRow[];
+	spec(): typeof SEMANTIC_DIGEST_SPEC_V1;
+	private ensure;
+}
+/**
+* Registered in the snapshot manifest under `digest_index[]`. One entry per
+* partition, addressable at height granularity without downloading raw data.
+*/
+interface DigestIndexPartition {
+	from_block: number;
+	to_block: number;
+	path: string;
+	row_count: number;
+	byte_size: number;
+	sha256: string;
+	digest_spec: typeof SEMANTIC_DIGEST_SPEC_V1;
+}
+export { PerHeightDigestRow, PerHeightDigestAccumulator, DigestIndexPartition };

package/dist/src/archive/per-height-digest.js

@@ -0,0 +1,194 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/archive/semantic-digest.ts
+import { createHash } from "node:crypto";
+var SEMANTIC_DIGEST_SPEC_V1 = "sha256:semantic-v1";
+var FIELD_SEP = "\x1F";
+var NULL_MARKER = "\x00";
+var textEncoder = new TextEncoder;
+function canonicalJson(value) {
+  if (value === null)
+    return "null";
+  if (typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("canonicalJson: non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "bigint")
+    return JSON.stringify(value.toString());
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+  }
+  return "null";
+}
+function scalar(value) {
+  if (value === null || value === undefined)
+    return NULL_MARKER;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("semanticDigest: non-finite number");
+    }
+    if (!Number.isInteger(value)) {
+      throw new Error(`semanticDigest: non-integer scalar ${value}`);
+    }
+    return String(value);
+  }
+  if (typeof value === "bigint")
+    return value.toString();
+  return value;
+}
+function jsonScalar(value) {
+  return value === null || value === undefined ? NULL_MARKER : canonicalJson(value);
+}
+function sha256Hex(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function encodeBlock(row) {
+  return [
+    scalar(row.height),
+    scalar(row.hash),
+    scalar(row.parent_hash),
+    scalar(row.burn_block_height),
+    scalar(row.burn_block_hash),
+    scalar(row.index_block_hash),
+    scalar(row.timestamp)
+  ].join(FIELD_SEP);
+}
+function encodeTransaction(row) {
+  return [
+    scalar(row.tx_id),
+    scalar(row.block_height),
+    scalar(row.tx_index),
+    scalar(row.type),
+    scalar(row.sender),
+    scalar(row.status),
+    scalar(row.contract_id),
+    scalar(row.function_name),
+    jsonScalar(row.function_args),
+    scalar(row.raw_result),
+    scalar(row.raw_tx)
+  ].join(FIELD_SEP);
+}
+function encodeEvent(row) {
+  return [
+    scalar(row.tx_id),
+    scalar(row.block_height),
+    scalar(row.event_index),
+    scalar(row.type),
+    jsonScalar(row.data)
+  ].join(FIELD_SEP);
+}
+var semanticDigest = {
+  v1: {
+    spec: SEMANTIC_DIGEST_SPEC_V1,
+    encodeBlock,
+    encodeTransaction,
+    encodeEvent,
+    block: (row) => sha256Hex(textEncoder.encode(encodeBlock(row))),
+    transaction: (row) => sha256Hex(textEncoder.encode(encodeTransaction(row))),
+    event: (row) => sha256Hex(textEncoder.encode(encodeEvent(row)))
+  }
+};
+
+class SemanticDigestRollup {
+  hasher = createHash("sha256");
+  count = 0;
+  static forDataset(_dataset) {
+    return new SemanticDigestRollup;
+  }
+  appendRowDigest(rowDigestHex) {
+    this.hasher.update(Buffer.from(rowDigestHex, "hex"));
+    this.count += 1;
+  }
+  rowCount() {
+    return this.count;
+  }
+  digest() {
+    return this.count === 0 ? null : this.hasher.copy().digest("hex");
+  }
+  spec() {
+    return SEMANTIC_DIGEST_SPEC_V1;
+  }
+}
+
+// src/archive/per-height-digest.ts
+import { createHash as createHash2 } from "node:crypto";
+class PerHeightDigestAccumulator {
+  rows = new Map;
+  setBlockDigest(height, blockDigestHex) {
+    this.ensure(height).block_digest = blockDigestHex;
+  }
+  appendTransactionDigest(height, digestHex) {
+    const a = this.ensure(height);
+    a.tx.update(Buffer.from(digestHex, "hex"));
+    a.tx_count += 1;
+  }
+  appendEventDigest(height, digestHex) {
+    const a = this.ensure(height);
+    a.event.update(Buffer.from(digestHex, "hex"));
+    a.event_count += 1;
+  }
+  drain(fromBlock, toBlock) {
+    const rows = [];
+    for (let h = fromBlock;h <= toBlock; h++) {
+      const a = this.rows.get(h);
+      if (!a)
+        continue;
+      if (!a.block_digest) {
+        throw new Error(`per-height digest at ${h} has tx/event rollups but no block digest`);
+      }
+      rows.push({
+        height: h,
+        block_digest: a.block_digest,
+        transactions_rollup: a.tx_count === 0 ? null : a.tx.copy().digest("hex"),
+        events_rollup: a.event_count === 0 ? null : a.event.copy().digest("hex")
+      });
+    }
+    return rows;
+  }
+  spec() {
+    return SEMANTIC_DIGEST_SPEC_V1;
+  }
+  ensure(height) {
+    let a = this.rows.get(height);
+    if (!a) {
+      a = {
+        block_digest: null,
+        tx: createHash2("sha256"),
+        tx_count: 0,
+        event: createHash2("sha256"),
+        event_count: 0
+      };
+      this.rows.set(height, a);
+    }
+    return a;
+  }
+}
+export {
+  PerHeightDigestAccumulator
+};
+
+//# debugId=2ABEAEFAD6B6D8C464756E2164756E21
+//# sourceMappingURL=per-height-digest.js.map

package/dist/src/archive/per-height-digest.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/semantic-digest.ts", "../src/archive/per-height-digest.ts"],
+  "sourcesContent": [
+    "import { createHash } from \"node:crypto\";\n\n/**\n * v1 canonical byte encoding for chain identity — the shape that lets\n * independently-run runtimes agree on the same block.\n *\n * The exact-body digest (`sha256:parquet-object`) proves capture fidelity to one\n * source: replay the same bytes, get the same rows. It cannot prove two nodes\n * observed the same chain, because their Parquet encoders legally differ in\n * column padding, compression, JSON key order, and null placement — two\n * operators processing the same block can ship byte-different Parquets that\n * carry identical content.\n *\n * The semantic digest is the shape that lets independent runtimes agree. Every\n * value on a block/transaction/event is normalized into a canonical byte string\n * by rules that MUST NOT change without a version bump. Two v1 computations\n * over the same range agree, or one is wrong about the chain — never about\n * formatting.\n *\n * Encoding rules (v1):\n *   - Fields join with `\\x1f` (ASCII US, unit separator — cannot legally\n *     appear in any chain value; a printable delimiter risks collision with\n *     contract-emitted strings).\n *   - Null encodes as `\\x00` (single NUL). Distinct from empty string `\"\"`.\n *   - Integers encode as their base-10 string. bigint → decimal string.\n *   - JSON payload columns (function_args, event data) encode as canonical\n *     JSON: object keys sorted lexicographically, no whitespace, bigint →\n *     quoted decimal string, non-finite numbers rejected.\n *   - Field order per record type is fixed and never reordered.\n *   - Digest = sha256(bytes), lowercase hex.\n *\n * Rollup rules (v1) — order MUST match the archive's stream order or an\n * honest re-export will disagree with the manifest:\n *   - blocks:       (height asc)\n *   - transactions: (block_height asc, tx_index asc, tx_id asc)\n *   - events:       (block_height asc, event_index asc, tx_id asc)\n * Per-partition rollup is `sha256(concat(row_digest_bytes))` in stream order.\n *\n * Test vectors under `packages/shared/src/archive/__fixtures__/semantic-digest/`\n * pin the encoding. Any change to bytes must bump the spec version.\n */\n\nexport const SEMANTIC_DIGEST_SPEC_V1 = \"sha256:semantic-v1\" as const;\nexport type SemanticDigestSpec = typeof SEMANTIC_DIGEST_SPEC_V1;\n\nconst FIELD_SEP = \"\\x1f\";\nconst NULL_MARKER = \"\\x00\";\n\nconst textEncoder = new TextEncoder();\n\n/**\n * Stable JSON — sorted keys, no whitespace, bigint → decimal string. Distinct\n * from `JSON.stringify(x)` which respects insertion order and rejects bigints.\n * Also rejects non-finite numbers, since NaN/Infinity have no on-chain meaning\n * and would silently hash as `null` under `JSON.stringify`.\n */\nexport function canonicalJson(value: unknown): string {\n\tif (value === null) return \"null\";\n\tif (typeof value === \"string\" || typeof value === \"boolean\") {\n\t\treturn JSON.stringify(value);\n\t}\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) {\n\t\t\tthrow new Error(\"canonicalJson: non-finite number\");\n\t\t}\n\t\treturn JSON.stringify(value);\n\t}\n\tif (typeof value === \"bigint\") return JSON.stringify(value.toString());\n\tif (Array.isArray(value)) {\n\t\treturn `[${value.map((item) => canonicalJson(item)).join(\",\")}]`;\n\t}\n\tif (typeof value === \"object\") {\n\t\tconst object = value as Record<string, unknown>;\n\t\treturn `{${Object.keys(object)\n\t\t\t.sort()\n\t\t\t.map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)\n\t\t\t.join(\",\")}}`;\n\t}\n\t// undefined / function / symbol — never present in decoded chain rows.\n\t// Fall through as null so tests catch unexpected shapes.\n\treturn \"null\";\n}\n\nfunction scalar(value: string | number | bigint | null | undefined): string {\n\tif (value === null || value === undefined) return NULL_MARKER;\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) {\n\t\t\tthrow new Error(\"semanticDigest: non-finite number\");\n\t\t}\n\t\tif (!Number.isInteger(value)) {\n\t\t\t// Chain heights, indexes, timestamps are all integer; a fractional\n\t\t\t// value here is a schema bug we want to surface loudly, not silently\n\t\t\t// serialize with float precision that varies by runtime.\n\t\t\tthrow new Error(`semanticDigest: non-integer scalar ${value}`);\n\t\t}\n\t\treturn String(value);\n\t}\n\tif (typeof value === \"bigint\") return value.toString();\n\treturn value;\n}\n\nfunction jsonScalar(value: unknown): string {\n\treturn value === null || value === undefined\n\t\t? NULL_MARKER\n\t\t: canonicalJson(value);\n}\n\nfunction sha256Hex(input: Uint8Array | string): string {\n\treturn createHash(\"sha256\").update(input).digest(\"hex\");\n}\n\nexport interface BlockDigestInput {\n\theight: number | bigint;\n\thash: string;\n\tparent_hash: string;\n\tburn_block_height: number | bigint;\n\tburn_block_hash: string | null;\n\tindex_block_hash: string | null;\n\ttimestamp: number | bigint;\n}\n\nexport interface TransactionDigestInput {\n\ttx_id: string;\n\tblock_height: number | bigint;\n\ttx_index: number;\n\ttype: string;\n\tsender: string;\n\tstatus: string;\n\tcontract_id: string | null;\n\tfunction_name: string | null;\n\tfunction_args: unknown;\n\traw_result: string | null;\n\traw_tx: string;\n}\n\nexport interface EventDigestInput {\n\ttx_id: string;\n\tblock_height: number | bigint;\n\tevent_index: number;\n\ttype: string;\n\tdata: unknown;\n}\n\nfunction encodeBlock(row: BlockDigestInput): string {\n\treturn [\n\t\tscalar(row.height),\n\t\tscalar(row.hash),\n\t\tscalar(row.parent_hash),\n\t\tscalar(row.burn_block_height),\n\t\tscalar(row.burn_block_hash),\n\t\tscalar(row.index_block_hash),\n\t\tscalar(row.timestamp),\n\t].join(FIELD_SEP);\n}\n\nfunction encodeTransaction(row: TransactionDigestInput): string {\n\treturn [\n\t\tscalar(row.tx_id),\n\t\tscalar(row.block_height),\n\t\tscalar(row.tx_index),\n\t\tscalar(row.type),\n\t\tscalar(row.sender),\n\t\tscalar(row.status),\n\t\tscalar(row.contract_id),\n\t\tscalar(row.function_name),\n\t\tjsonScalar(row.function_args),\n\t\tscalar(row.raw_result),\n\t\tscalar(row.raw_tx),\n\t].join(FIELD_SEP);\n}\n\nfunction encodeEvent(row: EventDigestInput): string {\n\treturn [\n\t\tscalar(row.tx_id),\n\t\tscalar(row.block_height),\n\t\tscalar(row.event_index),\n\t\tscalar(row.type),\n\t\tjsonScalar(row.data),\n\t].join(FIELD_SEP);\n}\n\n/**\n * v1 per-row digests. Each is `sha256(encoded_row_bytes)` in lowercase hex.\n * The encoded byte form is stable across runtimes; the sha256 is stable\n * across CPU architectures. Never mutate an encoder without a v-bump.\n */\nexport interface SemanticDigestV1 {\n\treadonly spec: SemanticDigestSpec;\n\treadonly encodeBlock: (row: BlockDigestInput) => string;\n\treadonly encodeTransaction: (row: TransactionDigestInput) => string;\n\treadonly encodeEvent: (row: EventDigestInput) => string;\n\treadonly block: (row: BlockDigestInput) => string;\n\treadonly transaction: (row: TransactionDigestInput) => string;\n\treadonly event: (row: EventDigestInput) => string;\n}\n\nexport interface SemanticDigestApi {\n\treadonly v1: SemanticDigestV1;\n}\n\nexport const semanticDigest: SemanticDigestApi = {\n\tv1: {\n\t\tspec: SEMANTIC_DIGEST_SPEC_V1,\n\t\tencodeBlock,\n\t\tencodeTransaction,\n\t\tencodeEvent,\n\t\tblock: (row: BlockDigestInput): string =>\n\t\t\tsha256Hex(textEncoder.encode(encodeBlock(row))),\n\t\ttransaction: (row: TransactionDigestInput): string =>\n\t\t\tsha256Hex(textEncoder.encode(encodeTransaction(row))),\n\t\tevent: (row: EventDigestInput): string =>\n\t\t\tsha256Hex(textEncoder.encode(encodeEvent(row))),\n\t},\n};\n\n/**\n * Streaming rollup — feed rows one at a time in their declared order, read the\n * rolled digest at the end. Two callers passing the same rows in the same order\n * produce the same rollup, regardless of batching.\n *\n * The rollup composes: partition_digest = sha256(concat(row_digest_bytes)),\n * where each row_digest_bytes = sha256(encode(row)). This is why the streaming\n * implementation can be constant-memory — the outer sha256 accepts row digests\n * incrementally.\n */\nexport class SemanticDigestRollup {\n\tprivate readonly hasher = createHash(\"sha256\");\n\tprivate count = 0;\n\n\tstatic forDataset(\n\t\t_dataset: \"blocks\" | \"transactions\" | \"events\",\n\t): SemanticDigestRollup {\n\t\treturn new SemanticDigestRollup();\n\t}\n\n\tappendRowDigest(rowDigestHex: string): void {\n\t\tthis.hasher.update(Buffer.from(rowDigestHex, \"hex\"));\n\t\tthis.count += 1;\n\t}\n\n\trowCount(): number {\n\t\treturn this.count;\n\t}\n\n\t/** Empty rollups return `null`, not the sha256 of nothing, so an empty\n\t *  range never compares equal to another empty range on a different\n\t *  dataset. Callers assign `null` semantics deliberately. */\n\tdigest(): string | null {\n\t\treturn this.count === 0 ? null : this.hasher.copy().digest(\"hex\");\n\t}\n\n\tspec(): SemanticDigestSpec {\n\t\treturn SEMANTIC_DIGEST_SPEC_V1;\n\t}\n}\n\n/**\n * Per-partition digest record — the shape that lands in the snapshot manifest.\n * Complements the existing `sha256:parquet-object` per-partition digest by\n * proving semantic identity independent of file encoding.\n */\nexport interface PartitionSemanticDigest {\n\tdataset: \"blocks\" | \"transactions\" | \"events\";\n\tfrom_block: number;\n\tto_block: number;\n\trow_count: number;\n\tdigest: string | null;\n\tdigest_spec: SemanticDigestSpec;\n}\n",
+    "import { createHash } from \"node:crypto\";\nimport { SEMANTIC_DIGEST_SPEC_V1 } from \"./semantic-digest.ts\";\n\n/**\n * Per-height semantic digest sidecars — enable \"verify one block\" without\n * downloading a whole 50k-block partition.\n *\n * The partition-level semantic digest is the shape a byte-level comparator\n * wants: one string per partition, cheap to compare in bulk. But a caller who\n * only cares about block 8_500_017 has to pull an entire Parquet file to check\n * one row. The per-height sidecar closes that gap: one 32-byte block digest and\n * two roll-up digests per height (transactions and events), addressable by\n * height without touching the raw datasets.\n *\n * Rollup rules (v1) — MUST match the exporter's stream order or an honest\n * re-derivation will disagree:\n *   - transactions_rollup: sha256(concat(tx_digest_bytes, tx_index asc, tx_id asc))\n *     `null` when the height has no transactions.\n *   - events_rollup:       sha256(concat(event_digest_bytes, event_index asc, tx_id asc))\n *     `null` when the height has no events.\n *   - block_digest:        the semantic-v1 block digest itself (one row per\n *                          height, so no rollup needed).\n *\n * `null` is deliberate: an empty rollup is not the sha256 of nothing (which\n * would collide across two empty datasets); an absent-here-but-present-elsewhere\n * dataset must never compare equal to a truly-empty one.\n */\n\nexport interface PerHeightDigestRow {\n\theight: number;\n\tblock_digest: string;\n\ttransactions_rollup: string | null;\n\tevents_rollup: string | null;\n}\n\ninterface Accumulator {\n\tblock_digest: string | null;\n\ttx: ReturnType<typeof createHash>;\n\ttx_count: number;\n\tevent: ReturnType<typeof createHash>;\n\tevent_count: number;\n}\n\nexport class PerHeightDigestAccumulator {\n\tprivate readonly rows = new Map<number, Accumulator>();\n\n\tsetBlockDigest(height: number, blockDigestHex: string): void {\n\t\tthis.ensure(height).block_digest = blockDigestHex;\n\t}\n\n\tappendTransactionDigest(height: number, digestHex: string): void {\n\t\tconst a = this.ensure(height);\n\t\ta.tx.update(Buffer.from(digestHex, \"hex\"));\n\t\ta.tx_count += 1;\n\t}\n\n\tappendEventDigest(height: number, digestHex: string): void {\n\t\tconst a = this.ensure(height);\n\t\ta.event.update(Buffer.from(digestHex, \"hex\"));\n\t\ta.event_count += 1;\n\t}\n\n\t/**\n\t * Drain the accumulator into height-ascending rows. Heights with no block\n\t * digest are dropped with a thrown error — a canonical partition MUST have\n\t * a block at every height it covers, and silently emitting a row without\n\t * one would hide the missing block from downstream verifiers.\n\t */\n\tdrain(fromBlock: number, toBlock: number): PerHeightDigestRow[] {\n\t\tconst rows: PerHeightDigestRow[] = [];\n\t\tfor (let h = fromBlock; h <= toBlock; h++) {\n\t\t\tconst a = this.rows.get(h);\n\t\t\tif (!a) continue; // Missing entirely — surfaced by canonical audit, not here.\n\t\t\tif (!a.block_digest) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`per-height digest at ${h} has tx/event rollups but no block digest`,\n\t\t\t\t);\n\t\t\t}\n\t\t\trows.push({\n\t\t\t\theight: h,\n\t\t\t\tblock_digest: a.block_digest,\n\t\t\t\ttransactions_rollup:\n\t\t\t\t\ta.tx_count === 0 ? null : a.tx.copy().digest(\"hex\"),\n\t\t\t\tevents_rollup:\n\t\t\t\t\ta.event_count === 0 ? null : a.event.copy().digest(\"hex\"),\n\t\t\t});\n\t\t}\n\t\treturn rows;\n\t}\n\n\tspec(): typeof SEMANTIC_DIGEST_SPEC_V1 {\n\t\treturn SEMANTIC_DIGEST_SPEC_V1;\n\t}\n\n\tprivate ensure(height: number): Accumulator {\n\t\tlet a = this.rows.get(height);\n\t\tif (!a) {\n\t\t\ta = {\n\t\t\t\tblock_digest: null,\n\t\t\t\ttx: createHash(\"sha256\"),\n\t\t\t\ttx_count: 0,\n\t\t\t\tevent: createHash(\"sha256\"),\n\t\t\t\tevent_count: 0,\n\t\t\t};\n\t\t\tthis.rows.set(height, a);\n\t\t}\n\t\treturn a;\n\t}\n}\n\n/**\n * Registered in the snapshot manifest under `digest_index[]`. One entry per\n * partition, addressable at height granularity without downloading raw data.\n */\nexport interface DigestIndexPartition {\n\tfrom_block: number;\n\tto_block: number;\n\tpath: string;\n\trow_count: number;\n\tbyte_size: number;\n\tsha256: string;\n\tdigest_spec: typeof SEMANTIC_DIGEST_SPEC_V1;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "2ABEAEFAD6B6D8C464756E2164756E21",
+  "names": []
+}