@artblocks/abx-indexer 0.1.0-alpha.4 → 0.1.0-alpha.41

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# @artblocks/abx-indexer
+
+## 0.1.0-alpha.41
+
+### Patch Changes
+
+- Updated dependencies [b9197bc]
+  - @artblocks/abx-sdk@0.1.0-alpha.40
+
+## 0.1.0-alpha.40
+
+### Patch Changes
+
+- Updated dependencies [3d7fe3c]
+- Updated dependencies [7b462e2]
+  - @artblocks/abx-sdk@0.1.0-alpha.39
+
+## 0.1.0-alpha.39
+
+### Patch Changes
+
+- Updated dependencies [c2400a7]
+  - @artblocks/abx-sdk@0.1.0-alpha.38
+
+## 0.1.0-alpha.38
+
+### Patch Changes
+
+- Updated dependencies [4512962]
+  - @artblocks/abx-sdk@0.1.0-alpha.37
+
+## 0.1.0-alpha.37
+
+### Patch Changes
+
+- Updated dependencies [5522192]
+  - @artblocks/abx-sdk@0.1.0-alpha.36
+
+## 0.1.0-alpha.36
+
+### Patch Changes
+
+- Updated dependencies [21e3d6c]
+- Updated dependencies [a73922c]
+  - @artblocks/abx-sdk@0.1.0-alpha.35
+
+## 0.1.0-alpha.35
+
+### Patch Changes
+
+- Updated dependencies [3ddba71]
+- Updated dependencies [9065128]
+  - @artblocks/abx-sdk@0.1.0-alpha.34
+
+## 0.1.0-alpha.34
+
+### Patch Changes
+
+- 9242a05: Prepare package metadata, release notes, and public-facing source comments for the initial public
+  source release.
+- Updated dependencies [9242a05]
+  - @artblocks/abx-sdk@0.1.0-alpha.33

package/dist/index.d.ts

@@ -4,6 +4,6 @@
  * Replays the event spine from chain into a disposable, rebuildable projection.
  * The canonical re-index: how every service onboards or exits a project.
  */
-export { SelfHostIndexer, type IndexResult } from './indexer.js';
+export { SelfHostIndexer, DEFAULT_INCREMENTAL_VACUUM_PAGES, DEFAULT_VACUUM_INTERVAL_MS, type IndexResult, type ReindexOptions, } from './indexer.js';
 export { SqliteStore, type Store, type ProjectRegistration, type EffectStatusRow, type EffectArtifactRow, } from './store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAC,eAAe,EAAE,KAAK,WAAW,EAAC,MAAM,cAAc,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,eAAe,EACf,gCAAgC,EAChC,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -4,6 +4,6 @@
  * Replays the event spine from chain into a disposable, rebuildable projection.
  * The canonical re-index: how every service onboards or exits a project.
  */
-export { SelfHostIndexer } from './indexer.js';
+export { SelfHostIndexer, DEFAULT_INCREMENTAL_VACUUM_PAGES, DEFAULT_VACUUM_INTERVAL_MS, } from './indexer.js';
 export { SqliteStore, } from './store.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAC,eAAe,EAAmB,MAAM,cAAc,CAAC;AAC/D,OAAO,EACL,WAAW,GAKZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,eAAe,EACf,gCAAgC,EAChC,0BAA0B,GAG3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,GAKZ,MAAM,YAAY,CAAC"}

package/dist/indexer.d.ts

@@ -1,10 +1,45 @@
-import { type Address, type ProjectState, type PublicClient } from '@artblocks/abx-sdk';
+import { type Address, type GetLogsAdaptiveOptions, type ProjectState, type PublicClient, type ReconstructBlockTag } from '@artblocks/abx-sdk';
+import type { Log } from 'viem';
 import { type IndexStatusRow, type Store, type ProjectRegistration } from './store.js';
+export interface ReindexOptions {
+    full?: boolean;
+    readUriDocuments?: boolean;
+    rpcUrl?: string;
+    /** Already-fetched logs for this project covering {@link toBlock}. Skips the
+     *  per-project `eth_getLogs` — the watch loop that scanned the registered set
+     *  holds the delta and should be the only getLogs. */
+    logs?: readonly Log[];
+    /** Inclusive scan head `logs` cover. Required with `logs`. */
+    toBlock?: bigint;
+    /**
+     * Stop the scan boundary at this block tag instead of chain head (the default, unchanged
+     * behavior). Resolved to a concrete block number BEFORE scanning (`resolveBlockTag` in the SDK),
+     * so the stored watermark (`ProjectState.toBlock`) is always a literal number, never the tag —
+     * see {@link ReconstructBlockTag}. Ignored when `logs` is supplied: that path's own `toBlock` is
+     * the caller's already-resolved scan head, from a watch loop that has nothing to do with a
+     * per-project tag choice.
+     */
+    blockTag?: ReconstructBlockTag;
+    /** See {@link GetLogsAdaptiveOptions.onChunk} — the only progress signal during a large scan. */
+    onChunk?: GetLogsAdaptiveOptions['onChunk'];
+}
 export interface IndexResult {
     state: ProjectState;
     elapsedMs: number;
     mode: 'full' | 'incremental';
 }
+/** Bounded per-pass reclaim for {@link SelfHostIndexer.runIncrementalVacuum} — ~100 pages is ~400KB
+ *  at SQLite's default 4096-byte page size, cheap enough to run synchronously without a request or a
+ *  watch tick noticing, while a long-running node with a large freelist still drains it over several
+ *  passes instead of never. */
+export declare const DEFAULT_INCREMENTAL_VACUUM_PAGES = 100;
+/** Default cadence for automatic SQLite maintenance (see
+ *  {@link SelfHostIndexer.startVacuumMaintenance}). Deliberately far coarser than the chain watcher's
+ *  poll (`ABX_WATCH_INTERVAL_MS`, 12s by default): freed pages accumulate slowly (a reclaim, a
+ *  dropped projection, a pruned bound artifact), so there is nothing to gain from touching the file
+ *  every tick — and this is process-internal scheduling, not an operator-facing knob, so it isn't
+ *  read from the environment the way the watcher's interval is. */
+export declare const DEFAULT_VACUUM_INTERVAL_MS: number;
 /**
  * The reference indexer (Layer 3). It does one thing well: replay the event
  * spine from chain into the store. Because every state change rides a standard,
@@ -19,6 +54,16 @@ export declare class SelfHostIndexer {
     /** Catch-up runs in flight, per lowercased address — see {@link reindexShared}. */
     private inFlight;
     constructor(store?: Store);
+    /**
+     * The pooled read client for a chain, or — with `rpcUrl` — one pinned to a SINGLE endpoint.
+     *
+     * The default (no `rpcUrl`) is a viem `fallback` across every configured endpoint, which fails
+     * over on an *error*. It does not fail over on a successful empty answer, which is exactly what an
+     * endpoint that has pruned its log history returns for an old block: `[]`, HTTP 200. Pinning one
+     * endpoint is how a caller can re-run the same scan against each in turn and find one that holds
+     * the history (see the CLI's empty-scan recovery). Pooled per (chain, endpoint) so the pinned
+     * clients don't evict the shared one.
+     */
     private client;
     /** The RPC client for a chain — exposed for reads that aren't a reindex (e.g. deploy-block
      *  discovery in the admin control plane). Reuses the same pooled client as `reindex`. */
@@ -34,9 +79,7 @@ export declare class SelfHostIndexer {
      * replay. `{full: true}` forces a replay from the deploy block (the durability
      * proof, and what runs automatically when there's no prior state). Idempotent.
      */
-    reindex(address: Address, opts?: {
-        full?: boolean;
-    }): Promise<IndexResult>;
+    reindex(address: Address, opts?: ReindexOptions): Promise<IndexResult>;
     /**
      * {@link reindex}, but concurrent calls for the same project COALESCE into one run.
      *
@@ -46,9 +89,7 @@ export declare class SelfHostIndexer {
      * the bottleneck — so the second caller joins the first run instead. A caller that needs a *full*
      * replay while an incremental is in flight gets its replay queued after it, never dropped.
      */
-    reindexShared(address: Address, opts?: {
-        full?: boolean;
-    }): Promise<IndexResult>;
+    reindexShared(address: Address, opts?: ReindexOptions): Promise<IndexResult>;
     /** Is a catch-up for this project running right now? (Lets a caller answer "still backfilling"
      *  without starting more work.) */
     isCatchingUp(address: Address): boolean;
@@ -61,14 +102,44 @@ export declare class SelfHostIndexer {
     indexStatus(address: Address): IndexStatusRow;
     private track;
     /** Re-index every registered project. */
-    reindexAll(opts?: {
-        full?: boolean;
-    }): Promise<IndexResult[]>;
+    reindexAll(opts?: ReindexOptions): Promise<IndexResult[]>;
     getProject(address: Address): ProjectState | null;
     /** Throw away a project's reconstructed projection, keeping its registration — the next
      *  {@link reindex} then rebuilds it from the deploy block. The projection is a disposable cache of
      *  chain state; this is how you prove it (`abx demo` deletes and replays to show identical state). */
     dropProjection(address: Address): void;
     listProjects(): ProjectState[];
+    /**
+     * Run one bounded `PRAGMA incremental_vacuum` pass, delegating to {@link SqliteStore.runIncrementalVacuum}.
+     * A no-op (returns 0) for any `Store` implementation that isn't a `SqliteStore` — vacuuming is a
+     * SQLite-specific concern, so a Postgres-backed deploy (which owns its own manual VACUUM story)
+     * simply has nothing to do here. Exposed on its own (not just via {@link startVacuumMaintenance})
+     * so a caller can also run one pass on demand — e.g. right after `abx vacuum convert`, to reclaim
+     * whatever the full VACUUM already didn't (it shouldn't leave anything, but this makes "did it
+     * work" independently checkable).
+     */
+    runIncrementalVacuum(maxPages?: number): number;
+    /**
+     * Start automatic SQLite maintenance: {@link runIncrementalVacuum} on its own
+     * timer, decoupled from the chain watcher's poll loop (`packages/token-api/src/watcher.ts`) so a
+     * reclaim pass can never sit inline with a request or a watch tick — it runs BETWEEN them, on
+     * whatever cadence the caller (or the default) picks, and a slow pass only ever delays the next
+     * pass, never a request being served concurrently (`node:sqlite`'s `DatabaseSync` is synchronous,
+     * but each pass is bounded — see `SqliteStore.runIncrementalVacuum` — precisely so that's cheap).
+     *
+     * `abx serve` is the intended caller, started once alongside `startChainWatcher`. Safe to call
+     * unconditionally: for a non-`SqliteStore` backend this still returns a working `stop()`, it just
+     * schedules calls that are themselves no-ops (see {@link runIncrementalVacuum}).
+     *
+     * A failed pass is logged and swallowed — maintenance must never be the thing that takes a node
+     * down; the freelist simply waits for the next pass.
+     */
+    startVacuumMaintenance(opts?: {
+        intervalMs?: number;
+        maxPages?: number;
+        log?: (line: string) => void;
+    }): {
+        stop(): void;
+    };
 }
 //# sourceMappingURL=indexer.d.ts.map

package/dist/indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAc,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,KAAK,mBAAmB,EAAC,MAAM,YAAY,CAAC;AAElG,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,OAAO,CAAC,OAAO,CAAmC;IAClD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAqE;gBAEzE,KAAK,CAAC,EAAE,KAAK;IAIzB,OAAO,CAAC,MAAM;IAMd;6FACyF;IACzF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY;IAI5C;;6DAEyD;IACzD,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,GAAG,mBAAmB;IAO7E;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAiDlF;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYlF;uCACmC;IACnC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAIvC;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc;IAU7C,OAAO,CAAC,KAAK;IAoBb,yCAAyC;IACnC,UAAU,CAAC,IAAI,GAAE;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQrE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI;IAIjD;;0GAEsG;IACtG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAItC,YAAY,IAAI,YAAY,EAAE;CAG/B"}
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAC9B,OAAO,EAAc,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,KAAK,mBAAmB,EAAC,MAAM,YAAY,CAAC;AAElG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;0DAEsD;IACtD,IAAI,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC;IACtB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,iGAAiG;IACjG,OAAO,CAAC,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;CAC9B;AAED;;;+BAG+B;AAC/B,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;;;mEAKmE;AACnE,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,OAAO,CAAC,OAAO,CAAmC;IAClD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAqE;gBAEzE,KAAK,CAAC,EAAE,KAAK;IAIzB;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM;IAOd;6FACyF;IACzF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY;IAI5C;;6DAEyD;IACzD,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,GAAG,mBAAmB;IAO7E;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IA2FhF;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAYhF;uCACmC;IACnC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAIvC;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc;IAU7C,OAAO,CAAC,KAAK;IAoBb,yCAAyC;IACnC,UAAU,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQnE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI;IAIjD;;0GAEsG;IACtG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAItC,YAAY,IAAI,YAAY,EAAE;IAO9B;;;;;;;;OAQG;IACH,oBAAoB,CAAC,QAAQ,GAAE,MAAyC,GAAG,MAAM;IAIjF;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,CAAC,IAAI,GAAE;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAM,GAAG;QAAC,IAAI,IAAI,IAAI,CAAA;KAAC;CAiB1H"}

package/dist/indexer.js

@@ -1,5 +1,17 @@
-import { classifyIndexError, makePublicClient, reconstructIncremental, reconstructProject, } from '@artblocks/abx-sdk';
+import { classifyIndexError, makePublicClient, reconstructFromLogs, reconstructIncremental, reconstructProject, } from '@artblocks/abx-sdk';
 import { SqliteStore } from './store.js';
+/** Bounded per-pass reclaim for {@link SelfHostIndexer.runIncrementalVacuum} — ~100 pages is ~400KB
+ *  at SQLite's default 4096-byte page size, cheap enough to run synchronously without a request or a
+ *  watch tick noticing, while a long-running node with a large freelist still drains it over several
+ *  passes instead of never. */
+export const DEFAULT_INCREMENTAL_VACUUM_PAGES = 100;
+/** Default cadence for automatic SQLite maintenance (see
+ *  {@link SelfHostIndexer.startVacuumMaintenance}). Deliberately far coarser than the chain watcher's
+ *  poll (`ABX_WATCH_INTERVAL_MS`, 12s by default): freed pages accumulate slowly (a reclaim, a
+ *  dropped projection, a pruned bound artifact), so there is nothing to gain from touching the file
+ *  every tick — and this is process-internal scheduling, not an operator-facing knob, so it isn't
+ *  read from the environment the way the watcher's interval is. */
+export const DEFAULT_VACUUM_INTERVAL_MS = 5 * 60_000;
 /**
  * The reference indexer (Layer 3). It does one thing well: replay the event
  * spine from chain into the store. Because every state change rides a standard,
@@ -16,10 +28,21 @@ export class SelfHostIndexer {
     constructor(store) {
         this.store = store ?? new SqliteStore();
     }
-    client(chainKey) {
-        let c = this.clients.get(chainKey);
+    /**
+     * The pooled read client for a chain, or — with `rpcUrl` — one pinned to a SINGLE endpoint.
+     *
+     * The default (no `rpcUrl`) is a viem `fallback` across every configured endpoint, which fails
+     * over on an *error*. It does not fail over on a successful empty answer, which is exactly what an
+     * endpoint that has pruned its log history returns for an old block: `[]`, HTTP 200. Pinning one
+     * endpoint is how a caller can re-run the same scan against each in turn and find one that holds
+     * the history (see the CLI's empty-scan recovery). Pooled per (chain, endpoint) so the pinned
+     * clients don't evict the shared one.
+     */
+    client(chainKey, rpcUrl) {
+        const key = rpcUrl ? `${chainKey}|${rpcUrl}` : chainKey;
+        let c = this.clients.get(key);
         if (!c)
-            this.clients.set(chainKey, (c = makePublicClient({ chainKey })));
+            this.clients.set(key, (c = makePublicClient({ chainKey, rpcUrl })));
         return c;
     }
     /** The RPC client for a chain — exposed for reads that aren't a reindex (e.g. deploy-block
@@ -64,15 +87,54 @@ export class SelfHostIndexer {
         let state;
         let mode;
         try {
-            if (incremental) {
-                state = await reconstructIncremental(this.client(reg.chainKey), prior, { factory });
+            if (incremental && opts.logs !== undefined) {
+                if (opts.toBlock === undefined) {
+                    throw new Error('reindex({logs}) requires toBlock — the inclusive scan head those logs cover');
+                }
+                state = await reconstructFromLogs(this.client(reg.chainKey, opts.rpcUrl), prior, opts.logs, {
+                    factory,
+                    readUriDocuments: opts.readUriDocuments,
+                    toBlock: opts.toBlock,
+                });
+                mode = 'incremental';
+            }
+            else if (incremental) {
+                state = await reconstructIncremental(this.client(reg.chainKey, opts.rpcUrl), prior, {
+                    factory,
+                    readUriDocuments: opts.readUriDocuments,
+                    onChunk: opts.onChunk,
+                    toBlock: opts.blockTag,
+                });
                 mode = 'incremental';
             }
             else {
-                state = await reconstructProject(this.client(reg.chainKey), {
+                state = await reconstructProject(this.client(reg.chainKey, opts.rpcUrl), {
                     address,
                     fromBlock: BigInt(reg.fromBlock),
                     factory,
+                    readUriDocuments: opts.readUriDocuments,
+                    onChunk: opts.onChunk,
+                    toBlock: opts.blockTag,
+                });
+                mode = 'full';
+            }
+            // Self-heal, never loop: an incremental fold that yields FEWER events than what's already
+            // stored signals a damaged projection. `eventCount` can only grow with append-only chain
+            // history, so a decrease is
+            // never legitimate — discard the bad fold before it's written, and repair with exactly ONE
+            // full replay from the deploy block. That result is written unconditionally, even in the
+            // (pathological) case where it too looks smaller: a full reconstruct from chain is
+            // definitionally correct, so there is nothing left to fall back to and no second attempt.
+            if (mode === 'incremental' && prior && state.eventCount < prior.eventCount) {
+                console.error(`[indexer] ${address}: an incremental fold produced ${state.eventCount} events, fewer than the ` +
+                    `${prior.eventCount} already stored — discarding it and falling back to one full reconstruct.`);
+                state = await reconstructProject(this.client(reg.chainKey, opts.rpcUrl), {
+                    address,
+                    fromBlock: BigInt(reg.fromBlock),
+                    factory,
+                    readUriDocuments: opts.readUriDocuments,
+                    onChunk: opts.onChunk,
+                    toBlock: opts.blockTag,
                 });
                 mode = 'full';
             }
@@ -88,7 +150,9 @@ export class SelfHostIndexer {
             });
             throw err;
         }
-        this.store.putProject(state);
+        // A full replay is the repair path — it purges + rebuilds the append-only event log so a
+        // reorg-replaced event can't survive as a stale row (incremental writes never delete).
+        this.store.putProject(state, { fullReplay: mode === 'full' });
         const now = new Date().toISOString();
         this.store.setIndexStatus(address, { status: 'live', error: null, attempts: 0, lastAttemptAt: now, lastIndexedAt: now });
         return { state, elapsedMs: Date.now() - started, mode };
@@ -172,5 +236,53 @@ export class SelfHostIndexer {
     listProjects() {
         return this.store.listProjects();
     }
+    // ── SQLite maintenance — the bounded-automatic half; the explicit one-time
+    // conversion for a pre-existing store lives on `SqliteStore.vacuumConvert` / `abx vacuum convert`.
+    /**
+     * Run one bounded `PRAGMA incremental_vacuum` pass, delegating to {@link SqliteStore.runIncrementalVacuum}.
+     * A no-op (returns 0) for any `Store` implementation that isn't a `SqliteStore` — vacuuming is a
+     * SQLite-specific concern, so a Postgres-backed deploy (which owns its own manual VACUUM story)
+     * simply has nothing to do here. Exposed on its own (not just via {@link startVacuumMaintenance})
+     * so a caller can also run one pass on demand — e.g. right after `abx vacuum convert`, to reclaim
+     * whatever the full VACUUM already didn't (it shouldn't leave anything, but this makes "did it
+     * work" independently checkable).
+     */
+    runIncrementalVacuum(maxPages = DEFAULT_INCREMENTAL_VACUUM_PAGES) {
+        return this.store instanceof SqliteStore ? this.store.runIncrementalVacuum(maxPages) : 0;
+    }
+    /**
+     * Start automatic SQLite maintenance: {@link runIncrementalVacuum} on its own
+     * timer, decoupled from the chain watcher's poll loop (`packages/token-api/src/watcher.ts`) so a
+     * reclaim pass can never sit inline with a request or a watch tick — it runs BETWEEN them, on
+     * whatever cadence the caller (or the default) picks, and a slow pass only ever delays the next
+     * pass, never a request being served concurrently (`node:sqlite`'s `DatabaseSync` is synchronous,
+     * but each pass is bounded — see `SqliteStore.runIncrementalVacuum` — precisely so that's cheap).
+     *
+     * `abx serve` is the intended caller, started once alongside `startChainWatcher`. Safe to call
+     * unconditionally: for a non-`SqliteStore` backend this still returns a working `stop()`, it just
+     * schedules calls that are themselves no-ops (see {@link runIncrementalVacuum}).
+     *
+     * A failed pass is logged and swallowed — maintenance must never be the thing that takes a node
+     * down; the freelist simply waits for the next pass.
+     */
+    startVacuumMaintenance(opts = {}) {
+        const intervalMs = opts.intervalMs ?? DEFAULT_VACUUM_INTERVAL_MS;
+        const maxPages = opts.maxPages ?? DEFAULT_INCREMENTAL_VACUUM_PAGES;
+        const log = opts.log ?? ((line) => console.error(`[maintenance] ${line}`));
+        const timer = setInterval(() => {
+            try {
+                const reclaimed = this.runIncrementalVacuum(maxPages);
+                if (reclaimed > 0)
+                    log(`incremental_vacuum reclaimed ${reclaimed} page(s)`);
+            }
+            catch (err) {
+                log(`incremental_vacuum failed (will retry next pass): ${err.message}`);
+            }
+        }, intervalMs);
+        // Never keeps the process alive on its own — a plain background convenience, not a reason `abx
+        // serve` (or a test) would hang waiting for it.
+        timer.unref?.();
+        return { stop: () => clearInterval(timer) };
+    }
 }
 //# sourceMappingURL=indexer.js.map

package/dist/indexer.js.map

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

package/dist/store.d.ts

@@ -22,11 +22,12 @@ export interface ProjectRegistration {
     registeredAt: string;
 }
 /** One producer-published effect artifact — a row in the data plane's enumeration registry
- *  (`specs/protocol/data-plane.md`). The resolver lists a token's rows and keeps only those whose
+ *  (`site/content/docs/protocol/data-plane.mdx`). The resolver lists a token's rows and keeps only those whose
  *  `key` matches the recomputed address at the CURRENT settled inputsHash, so stale rows go
  *  silently unlisted (self-invalidation). `locator === null` means the bytes live in custody
- *  (the shared backend at `key`, or resolver-held published bytes). Producer-published, NOT
- *  chain-derived: rows survive a projection wipe and self-heal from a runner's next sweep. */
+ *  (a co-located producer's bytes in the shared backend at `key`, or a bound output's `bytes` below).
+ *  Producer-registered, NOT chain-derived: rows survive a projection wipe and self-heal from a
+ *  runner's next sweep. */
 export interface EffectArtifactRow {
     /** renderArtifactKey (keccak hex; encodes effectKey + settled inputsHash). */
     key: string;
@@ -38,10 +39,26 @@ export interface EffectArtifactRow {
     /** The effect's DECLARED output mimeType — what the manifest and byte route serve. */
     contentType: string | null;
     locator: string | null;
+    /**
+     * A **bound** output's content (`site/content/docs/protocol/effects.mdx → Bound vs referenced`): the bytes that
+     * stitch into the metadata JSON — `render/traits` today. Capped at
+     * {@link BOUND_ARTIFACT_MAX_BYTES}; `null` for every **referenced** output, whose bytes stay with
+     * the producer and reach us only as `locator`.
+     *
+     * These live HERE, next to the row, and deliberately not in a `StorageBackend`: byte custody holds
+     * *source* bytes an on-chain keccak commits to (switchable, never lapsable), while these are
+     * re-creatable projection state whose loss is a re-render. One write instead of two also removes a
+     * way for the row and its content to disagree.
+     */
+    bytes?: Uint8Array | null;
     updatedAt?: string;
 }
+/** The cap a serving node MUST accept per bound output, and MUST refuse above
+ *  (`site/content/docs/using-abx/remote-services.mdx → The mode is decided by the binding`). ~100× a real
+ *  traits payload: generous for what it is for, far too small to become blob storage. */
+export declare const BOUND_ARTIFACT_MAX_BYTES: number;
 /**
- * Where one project sits in the indexing lifecycle (`specs/self-host-toolkit/remote-services.md` →
+ * Where one project sits in the indexing lifecycle (`site/content/docs/using-abx/remote-services.mdx` →
  * The indexing lifecycle) — what the control plane's `status`/list routes report and what
  * `abx status` prints, for a managed provider and for your own node in the same words.
  *
@@ -119,6 +136,20 @@ export interface Store {
     /** Every registered artifact row for (project, token) — the manifest's effect-source listing.
      *  Callers filter by recomputing the current-inputsHash key per row (stale rows unlisted). */
     listEffectArtifacts(address: string, tokenId: string): EffectArtifactRow[];
+    /**
+     * Drop the **bound** content of every superseded row for (project, token, effectKey, outputKey) —
+     * everything whose `inputs_hash` isn't `currentHash`.
+     *
+     * The spec makes this a **MAY**, not a MUST (`site/content/docs/protocol/effects.mdx → Bound vs referenced`):
+     * what's normative is that superseded content is never *served* or stitched, which leaves it with
+     * no legal reader. Dropping it is therefore free of consequence, and this node drops eagerly — on
+     * each bound registration — because that is what turns "held bytes" into
+     * `cap × minted × bound outputs` rather than a number that grows with every param change. A node
+     * that chose to keep history would be equally conforming and simply carry the cost.
+     *
+     * The rows themselves survive as provenance; only the unreadable content goes.
+     */
+    pruneBoundArtifactBytes(address: string, tokenId: string, effectKey: string, outputKey: string, currentHash: string): void;
     /** Merge a lifecycle patch for one project (preserve-on-omit, clear-on-`null`) and return the
      *  stored row. Creates the row on first write. */
     setIndexStatus(address: string, patch: IndexStatusPatch): IndexStatusRow;
@@ -134,7 +165,12 @@ export interface Store {
     /** Clear one artifact key's status — the run finished; artifact presence takes over as truth. */
     clearEffectStatus(key: string): void;
     listEffectStatuses(address: string): EffectStatusRow[];
-    putProject(state: ProjectState): void;
+    /** Persist a folded projection. `fullReplay: true` (the repair path — `abx index --full`) purges
+     *  the project's append-only event log first, so a reorg-replaced event can't survive as a stale
+     *  row; routine incremental writes leave the log append-only. */
+    putProject(state: ProjectState, opts?: {
+        fullReplay?: boolean;
+    }): void;
     getProject(address: string): ProjectState | null;
     listProjects(): ProjectState[];
     /** Drop the rebuildable projection (keeps registrations). Proves replay. */
@@ -167,12 +203,31 @@ export declare class SqliteStore implements Store {
     /** Idempotently add columns introduced after a DB was first created (CREATE IF NOT
      *  EXISTS won't backfill them). Keeps an existing projection working across upgrades. */
     private migrate;
+    /**
+     * One-time data migration, gated on `PRAGMA user_version` (unused before this — starts at 0 on
+     * every existing store). `migrate()` above only ever ADDs columns; recomputing `seq` rewrites
+     * VALUES in an existing column, which a `PRAGMA table_info` presence check can't gate — hence a
+     * separate versioned step.
+     *
+     * `events.seq` used to be the array index at write time (positional — renumbers on every re-fold).
+     * This recomputes every existing row to the chain-derived value `(block_number << 32) | log_index`
+     * — the same formula {@link eventSeq} uses going forward — so an upgraded store's history becomes
+     * append-only-compatible without re-indexing from chain. No collisions are possible: `(block,
+     * logIndex)` is already unique per project (the table's own history proves it — it was a valid
+     * event log before this ran), and the shift preserves that uniqueness.
+     *
+     * A fresh install has no rows yet, so the `UPDATE` is a no-op — but `user_version` still advances,
+     * so this never re-scans an empty table on every open. Wrapped in a transaction: a crash mid-way
+     * leaves `user_version` at 0 and retries the whole thing next open, never a half-migrated table.
+     */
+    private migrateSeq;
     register(reg: ProjectRegistration): void;
     listRegistrations(): ProjectRegistration[];
     getRegistration(address: string): ProjectRegistration | null;
     dropProjection(address: string): void;
     deregister(address: string): void;
     putEffectArtifact(row: EffectArtifactRow): void;
+    pruneBoundArtifactBytes(address: string, tokenId: string, effectKey: string, outputKey: string, currentHash: string): void;
     getEffectArtifact(key: string): EffectArtifactRow | null;
     listEffectArtifacts(address: string, tokenId: string): EffectArtifactRow[];
     putMeta(key: string, value: string): void;
@@ -189,11 +244,78 @@ export declare class SqliteStore implements Store {
     putEffectStatus(row: EffectStatusRow): void;
     clearEffectStatus(key: string): void;
     listEffectStatuses(address: string): EffectStatusRow[];
-    putProject(state: ProjectState): void;
+    /**
+     * Persist a reconstructed `ProjectState`. O(delta), not O(history): the routine case — one new
+     * mint on an otherwise-unchanged project — writes one project row and one token row, appends
+     * whatever events are new, and touches nothing else. A delete-and-reinsert approach would rewrite
+     * the entire projection (every token, every event) on every call.
+     *
+     * `contract_uri`/`token_uri` are bound NULL unconditionally regardless of what `state` carries —
+     * see the schema comments on those columns. This is deliberate even when a caller passed populated
+     * values (e.g. a reconstruct run with `readUriDocuments: true`): the store's job is never to cache
+     * a value with no settled state, only to serve it live when asked.
+     */
+    putProject(state: ProjectState, opts?: {
+        fullReplay?: boolean;
+    }): void;
     getProject(address: string): ProjectState | null;
     listProjects(): ProjectState[];
     wipeProjections(): void;
     destroy(): void;
+    /**
+     * This store's actual `PRAGMA auto_vacuum` mode, right now. A store opened from a file created
+     * before `SCHEMA` started setting `PRAGMA auto_vacuum = INCREMENTAL` BEFORE its first `CREATE
+     * TABLE` (see the comment on that pragma above) is permanently stuck at `'none'` — the pragma
+     * silently no-ops on a database that already has tables — until {@link vacuumConvert} runs. This
+     * is the detection half of the two-part approach: every other read/write path in this class is
+     * indifferent to the mode, so nothing breaks for a store still at `'none'`; only reclamation cares.
+     */
+    autoVacuumMode(): 'none' | 'full' | 'incremental';
+    /** Diagnostics behind `abx vacuum status`: {@link autoVacuumMode} alongside the raw page/freelist
+     *  counts a caller (or a test) can watch move as maintenance runs. */
+    vacuumStats(): {
+        mode: 'none' | 'full' | 'incremental';
+        freelistPages: number;
+        pageCount: number;
+    };
+    /**
+     * The one-time, EXPLICIT conversion for a store stuck at `auto_vacuum='none'`: sets the pragma —
+     * on its own a no-op here, same as it was at construction, since the database already has tables
+     * — and then runs a full `VACUUM`, the only operation that actually rebuilds the file under the
+     * new mode. This is deliberately not run automatically anywhere in this class or in
+     * {@link SelfHostIndexer}: a full `VACUUM` rewrites the ENTIRE database file and can briefly need
+     * up to ~2x its on-disk size while it runs, so it must be an operator's explicit choice, made with
+     * that cost understood — `abx vacuum convert` (and the docs it points at) is that explicit surface.
+     * A no-op, returning the mode unchanged, once the store is already `'full'` or `'incremental'`.
+     */
+    vacuumConvert(): 'none' | 'full' | 'incremental';
+    /**
+     * Bounded `PRAGMA incremental_vacuum(N)`: reclaims at most `maxPages` freed pages THIS call, never
+     * the whole freelist at once. `node:sqlite`'s `DatabaseSync` is SYNCHRONOUS and shares this process
+     * with token-api reads on a co-located `abx serve` — an unbounded reclaim would block every request
+     * in flight for however long a large freelist takes to drain. Bounding it is what makes it safe to
+     * call automatically between watch-loop ticks (see {@link SelfHostIndexer.runIncrementalVacuum})
+     * rather than only from the explicit `abx vacuum convert` command above.
+     *
+     * A no-op (returns 0, touches nothing) before the store has been converted to `'incremental'` mode
+     * — `incremental_vacuum` only does anything in that mode, and running it blind on a `'none'` store
+     * would be silent maintenance with no effect, which is worse than an honest no-op.
+     *
+     * Returns the number of pages actually REQUESTED of SQLite this call (capped by the freelist's
+     * current size), not a guarantee it moved exactly that many — draining an already-small freelist
+     * legitimately returns fewer than `maxPages`.
+     */
+    runIncrementalVacuum(maxPages: number): number;
+    /**
+     * Drop one project's projection — `extensions` / `tokens` / `projects` — but deliberately NOT
+     * `events`. The event log is append-only and chain-derived (`seq` is `(block << 32) | logIndex`,
+     * so a re-fold always lands on the same rows): a re-index after this re-derives the identical
+     * event set from chain and re-inserts it as a no-op (`ON CONFLICT DO NOTHING`), so nothing is lost
+     * by leaving the rows in place, and `abx demo`'s "drop + replay" proof doesn't depend on the log
+     * being gone. `deregister`/forget-the-project-entirely paths delete events explicitly — this
+     * helper is for `dropProjection`, which keeps the registration precisely so the next reindex can
+     * rebuild from it.
+     */
     private deleteProjection;
     private hydrate;
 }