@xyo-network/event-kit-statement-graph 0.1.5 → 0.1.8

package/README.md

@@ -30,27 +30,41 @@ const replay = await createFinalizedEventKitReplayController({
 
 await replay.sync()
 
+// A bounded worker still reports the real live finalized head while advancing
+// its durable projection by at most the requested number of blocks.
+await replay.sync({ maxBlocks: 4_096, signal })
+
+// The durable projection exposes its exact canonical XL1 root.
+const at = replay.anchor() // { block, hash } or null before the first commit
+
 const handshakes = createEventKitHandshakeReadModel({
   body: hash => replay.body(hash),
   viewer: replay.viewer(),
 })
 ```
 
-The candidate controller walks one finalized block at a time through Statement
-Graph with the exact Event Kit object-schema allowlist. Each block is staged
-before publication. An unresolved Statement Graph event, a missing or corrupt
-claimed object, or a missing or corrupt challenge/response attachment records
-an explicit blocked boundary and leaves `indexedThrough` before that block. A
-later `sync()` retries the same block; unavailability is never interpreted as
-absence or revocation.
-
-Published Statement Graph `0.5.0` admits consensus-elevated, subject-bearing
+The controller bulk-stages contiguous finalized ranges through Statement Graph
+with the exact Event Kit object-schema allowlist. The default full `sync()`
+catches up to the independently observed live head; `sync({ maxBlocks, signal })`
+lets a bounded worker retain that real `finalizedHead` while advancing
+`indexedThrough` by at most `maxBlocks`. A staged range is published only after
+every publisher-scoped object and required challenge/response attachment in it
+is verified. An unresolved Statement Graph event, a missing or corrupt claimed
+object, or a missing or corrupt attachment records the earliest affected block
+as an explicit blocked boundary and leaves `indexedThrough` before that block.
+A clean prefix is re-scanned and may be committed first. A later `sync()` retries
+the same blocked block; unavailability is never interpreted as absence or
+revocation. Cancellation retains only prefixes whose atomic checkpoint save has
+already resolved.
+
+Published Statement Graph `0.5.3` admits consensus-elevated, subject-bearing
 Claims and decodes Claim bodies from finalized block carriers while resolving
 claimed objects and acceptance attachments through the datalake. The Gate 2
 live rerun against that release remains the acceptance boundary.
 
-Statement Graph `0.5.0` uses fold version 4 and scan-checkpoint format 2. Event
-Kit's publisher-scoped outer checkpoint is also format 2. Only the exact
+Statement Graph `0.5.x` uses fold version 4 and scan-checkpoint format 2. Event
+Kit's publisher-scoped outer checkpoint is format 3 and binds
+`indexedThrough` to the exact canonical XL1 root hash. Only the exact
 current checkpoint and ordered Event Kit schema policy are accepted. Missing,
 additional, reordered, or version-suffixed policy entries fail closed as
 invalid content; no alternative-policy reader or in-place migration exists.
@@ -61,6 +75,10 @@ invalid content; no alternative-policy reader or in-place migration exists.
 - `indexedThrough` is the highest block whose Event Kit projection was fully
   committed, or `null` before the floor block has been indexed.
 
+`anchor()` returns the durable `{block, hash}` pair for `indexedThrough`. A
+height-only checkpoint from the previous format is replayed from the floor; it
+is never upgraded into root-bound evidence by assumption.
+
 The strict `EventKitReplayCheckpointZod` checkpoint binds network, chain ID,
 publisher, datalake source identity, floor block, Statement Graph fold version,
 and the ordered schema policy. It retains the complete canonical

package/dist/neutral/finalizedReplayChain.d.ts

@@ -0,0 +1,16 @@
+import type { FinalizedBlockViewer } from '@xyo-network/xl1-statement-graph-sdk';
+type Promisable<T> = PromiseLike<T> | T;
+/**
+ * Public XL1 viewers expose height-aware chain identity through `chainId(block)`.
+ * Fakes and older adapters may omit it, in which case replay remains deliberately
+ * restricted to a single ChainId.
+ */
+export interface FinalizedEventKitReplayChain extends FinalizedBlockViewer {
+    chainId?(block: number | 'latest'): Promisable<unknown>;
+}
+export declare function exactFinalizedBlockHash(chain: FinalizedEventKitReplayChain, block: number, chainId: string): Promise<string>;
+/** Validates every block actually consumed by the scanner without adding a second range read. */
+export declare function lineageValidatingScanChain(chain: FinalizedEventKitReplayChain, chainId: string): FinalizedBlockViewer;
+export declare function requireCurrentReplayChain(chain: FinalizedEventKitReplayChain, finalizedHead: number, chainId: string): Promise<void>;
+export {};
+//# sourceMappingURL=finalizedReplayChain.d.ts.map

package/dist/neutral/finalizedReplayChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalizedReplayChain.d.ts","sourceRoot":"","sources":["../../src/finalizedReplayChain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAA;AAEhF,KAAK,UAAU,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAEvC;;;;GAIG;AACH,MAAM,WAAW,4BAA6B,SAAQ,oBAAoB;IACxE,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;CACxD;AA2BD,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,EACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,iGAAiG;AACjG,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,4BAA4B,EACnC,OAAO,EAAE,MAAM,GACd,oBAAoB,CAoBtB;AAED,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,4BAA4B,EACnC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/neutral/finalizedReplayController.d.ts

@@ -1,5 +1,6 @@
 import type { StatementGraphViewer } from '@xyo-network/xl1-statement-graph-engine';
-import type { BodyReader, FinalizedBlockViewer } from '@xyo-network/xl1-statement-graph-sdk';
+import type { BodyReader } from '@xyo-network/xl1-statement-graph-sdk';
+import type { FinalizedEventKitReplayChain } from './finalizedReplayChain.ts';
 import type { EventKitReplayCheckpoint, EventKitReplayCheckpointIdentity, ReplayBlockedState } from './replayCheckpoint.ts';
 export interface EventKitReplayCheckpointStore {
     /** Returns durable JSON-compatible checkpoint content, if one exists. */
@@ -9,21 +10,36 @@ export interface EventKitReplayCheckpointStore {
 }
 export interface FinalizedEventKitReplayOptions extends EventKitReplayCheckpointIdentity {
     readonly bodies: BodyReader;
-    readonly chain: FinalizedBlockViewer;
+    readonly chain: FinalizedEventKitReplayChain;
+    /** Maximum contiguous blocks staged before one atomic checkpoint save. */
+    readonly checkpointBatchSize?: number;
     readonly checkpointStore: EventKitReplayCheckpointStore;
+    /** Maximum blocks requested by each Statement Graph bulk read. */
+    readonly scanBatchSize?: number;
 }
 export interface FinalizedEventKitReplayStatus {
     readonly blocked?: ReplayBlockedState;
     readonly finalizedHead: number;
     readonly indexedThrough: number | null;
 }
+export interface FinalizedEventKitReplayAnchor {
+    readonly block: number;
+    readonly hash: string;
+}
+export interface FinalizedEventKitReplaySyncOptions {
+    /** Advance at most this many blocks while still reporting the uncapped live finalized head. */
+    readonly maxBlocks?: number;
+    readonly signal?: AbortSignal;
+}
 export interface FinalizedEventKitReplayController {
+    /** Exact canonical XL1 root retained with the current durable projection. */
+    anchor(): Readonly<FinalizedEventKitReplayAnchor> | null;
     /** Resolve a verified lifecycle or acceptance-attachment body from the durable projection. */
     body(hash: string): Readonly<Record<string, unknown>> | undefined;
     snapshot(): Readonly<EventKitReplayCheckpoint>;
     status(): FinalizedEventKitReplayStatus;
     /** Walks clean finalized blocks and stops before the first unavailable body boundary. */
-    sync(): Promise<FinalizedEventKitReplayStatus>;
+    sync(options?: FinalizedEventKitReplaySyncOptions): Promise<FinalizedEventKitReplayStatus>;
     /** Snapshot viewer; request it again after `sync()` to observe the new checkpoint. */
     viewer(): StatementGraphViewer;
 }

package/dist/neutral/finalizedReplayController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finalizedReplayController.d.ts","sourceRoot":"","sources":["../../src/finalizedReplayController.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAMnF,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EAErB,MAAM,sCAAsC,CAAA;AAQ7C,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,kBAAkB,EAGnB,MAAM,uBAAuB,CAAA;AAO9B,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,oFAAoF;IACpF,IAAI,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAA;CACxD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,iCAAiC;IAChD,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACjE,QAAQ,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAAA;IAC9C,MAAM,IAAI,6BAA6B,CAAA;IACvC,yFAAyF;IACzF,IAAI,IAAI,OAAO,CAAC,6BAA6B,CAAC,CAAA;IAC9C,sFAAsF;IACtF,MAAM,IAAI,oBAAoB,CAAA;CAC/B;AAgRD,wBAAsB,uCAAuC,CAC3D,UAAU,EAAE,8BAA8B,GACzC,OAAO,CAAC,iCAAiC,CAAC,CAkB5C;AAED,uFAAuF;AACvF,wBAAgB,yCAAyC,CACvD,OAAO,CAAC,EAAE,OAAO,GAChB,6BAA6B,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAA;CAAE,CAazF"}
+{"version":3,"file":"finalizedReplayController.d.ts","sourceRoot":"","sources":["../../src/finalizedReplayController.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAMnF,OAAO,KAAK,EACV,UAAU,EAEX,MAAM,sCAAsC,CAAA;AAQ7C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAA;AAM7E,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,kBAAkB,EAGnB,MAAM,uBAAuB,CAAA;AAO9B,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,oFAAoF;IACpF,IAAI,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAA;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAA;IACvD,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,kCAAkC;IACjD,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,iCAAiC;IAChD,6EAA6E;IAC7E,MAAM,IAAI,QAAQ,CAAC,6BAA6B,CAAC,GAAG,IAAI,CAAA;IACxD,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACjE,QAAQ,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAAA;IAC9C,MAAM,IAAI,6BAA6B,CAAA;IACvC,yFAAyF;IACzF,IAAI,CAAC,OAAO,CAAC,EAAE,kCAAkC,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAAA;IAC1F,sFAAsF;IACtF,MAAM,IAAI,oBAAoB,CAAA;CAC/B;AA0YD,wBAAsB,uCAAuC,CAC3D,UAAU,EAAE,8BAA8B,GACzC,OAAO,CAAC,iCAAiC,CAAC,CAwB5C;AAED,uFAAuF;AACvF,wBAAgB,yCAAyC,CACvD,OAAO,CAAC,EAAE,OAAO,GAChB,6BAA6B,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAA;CAAE,CAazF"}

package/dist/neutral/index.d.ts

@@ -2,7 +2,8 @@ export type { ActiveSourceWakeGrantAuthorizerOptions } from './activeSourceWakeG
 export { createActiveSourceWakeGrantAuthorizer } from './activeSourceWakeGrantAuthorizer.ts';
 export { createCheckpointStatementGraphViewer } from './checkpointViewer.ts';
 export { EventKitClaimedObjectSchemas, EventKitClaimedObjectSchemaSet, } from './eventKitSchemaPolicy.ts';
-export type { EventKitReplayCheckpointStore, FinalizedEventKitReplayController, FinalizedEventKitReplayOptions, FinalizedEventKitReplayStatus, } from './finalizedReplayController.ts';
+export type { FinalizedEventKitReplayChain } from './finalizedReplayChain.ts';
+export type { EventKitReplayCheckpointStore, FinalizedEventKitReplayController, FinalizedEventKitReplayOptions, FinalizedEventKitReplayStatus, FinalizedEventKitReplaySyncOptions, } from './finalizedReplayController.ts';
 export { createFinalizedEventKitReplayController, createMemoryEventKitReplayCheckpointStore, } from './finalizedReplayController.ts';
 export type { StatementGraphGrantReadModelOptions } from './grantReadModel.ts';
 export { createStatementGraphGrantReadModel } from './grantReadModel.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAA;AAClG,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAA;AAC5F,OAAO,EAAE,oCAAoC,EAAE,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,uCAAuC,EACvC,yCAAyC,GAC1C,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAA;AAC1E,YAAY,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,qCAAqC,EACrC,4CAA4C,EAC5C,iCAAiC,EACjC,uBAAuB,EACvB,sBAAsB,EACtB,6BAA6B,EAC7B,wCAAwC,EACxC,2CAA2C,EAC3C,yBAAyB,EACzB,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,yBAAyB,EACzB,4BAA4B,EAC5B,mCAAmC,EACnC,8CAA8C,EAC9C,iDAAiD,EACjD,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,wBAAwB,EACxB,gCAAgC,EAChC,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAA;AAClG,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAA;AAC5F,OAAO,EAAE,oCAAoC,EAAE,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAA;AAClC,YAAY,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAA;AAC7E,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,8BAA8B,EAC9B,6BAA6B,EAC7B,kCAAkC,GACnC,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,uCAAuC,EACvC,yCAAyC,GAC1C,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAA;AAC1E,YAAY,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,qCAAqC,EACrC,4CAA4C,EAC5C,iCAAiC,EACjC,uBAAuB,EACvB,sBAAsB,EACtB,6BAA6B,EAC7B,wCAAwC,EACxC,2CAA2C,EAC3C,yBAAyB,EACzB,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,yBAAyB,EACzB,4BAA4B,EAC5B,mCAAmC,EACnC,8CAA8C,EAC9C,iDAAiD,EACjD,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,wBAAwB,EACxB,gCAAgC,EAChC,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,uBAAuB,CAAA"}