@sovereignbase/sequencer 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -24,26 +24,33 @@ footage?: ReadonlyArray<T | undefined>]>;
 /**
  * Describes one Actor's acknowledgement frontier.
  * `[actorID, sessionID, sessionEnd, ...]` contains removal Session/frontier pairs.
- * The application is responsible for acknowledging complete received Session prefixes.
+ * Actor-only tuples establish membership before removals, including offline Actors.
+ * Compaction requires equal complete Session frontiers from every active Actor.
+ * The application must deliver pending history before claiming that frontier.
  */
 type Acknowledgement = U32List;
-/** Ordered replication batch; delivery may be duplicated or causally reordered. */
+/** Replication batch within retained history; delivery may be duplicated or causally reordered. */
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
  * Retained state required to hydrate the same visible Projection.
- * One structural array and one JavaScript-owned content array.
+ * One structural array and JavaScript-owned Footage.
  * Small snapshots use six-word insertion records after length-prefixed ACKs;
  * `words[0]` locates those records. Large snapshots begin with
  * `[0, frontiersEnd, insertionCount]` and omit predictable coordinate fields.
- * Both layouts retain complete coordinates and acknowledgements.
+ * Both layouts encode the retained coordinates and acknowledgements.
+ * Eligible masks, deleted Footage and compacted Session claims are omitted;
+ * Actor membership remains. Compaction may translate retained coordinates.
  * Positive insertion diffs consume successive spans of `footage`.
+ * String-encoded Footage preserves Insertion order, not visible text order.
+ * It uses one UTF-16 code unit per Frame. Missing slots use
+ * NUL (`\u0000`); hydration splits the string with `split('')`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
-type Sequence<T> = Readonly<[
+type Sequence<T, StringEncoded extends boolean = false> = Readonly<[
 /** Acknowledgements followed by canonical Insertions in Structural Order. */
 words: U32List,
 /** Consecutive positive Insertion spans, including missing Footage slots. */
-footage: ReadonlyArray<T | undefined>]>;
+footage: StringEncoded extends true ? string : ReadonlyArray<T | undefined>]>;
 /** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
 type Splice<T> = Readonly<[
 /** First affected position in the Projection after preceding Splices. */
@@ -59,7 +66,7 @@ type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/errors/class.d.ts
 /** Semantic error codes reported by the Sequencer public API. */
-type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED';
+type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
 export declare class SequencerError extends Error {
   /** Machine-readable code identifying the failure condition. */
@@ -84,7 +91,7 @@ export declare class Projection<T> {
    * Prepares to sequence a projection, optionally hydrating from a trusted sequence stored by the application.
    *
    * @param actorID Actor identifier used in acknowledgements.
-   * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
    * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
@@ -155,10 +162,17 @@ export declare class Projection<T> {
   /**
    * Sequences state into a compact serializable format.
    *
+   * @remarks
+   * Register active Actors before removal. Equal complete Session frontiers
+   * permit masks and deleted Footage to be omitted from the retained checkpoint.
+   * Compaction may translate retained anchors without rewriting this instance.
+   *
+   * @param stringEncode Whether to concatenate Footage into a string; each text Frame must be one UTF-16 code unit. Defaults to `false`.
    * @returns A Sequence with acknowledged removals compacted in the exported state.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
+   * @throws {@link SequencerError} with code `STRING_ENCODING_FAILED` if Footage concatenation fails.
    */
-  sequence(): Sequence<T>;
+  sequence<StringEncoded extends boolean = false>(stringEncode?: StringEncoded): Sequence<T, StringEncoded>;
   /**
    * Returns the value at a Projection position.
    *

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;KAShB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;KAYtD,SAAS,KAAK;;AAGtB,OAAO;;AAEP,SAAS,cAAc;;KAKf,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KCtEzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;EAUP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;KAiBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;KAKrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KC7EzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;;;EAiBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAWf,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}

package/dist/index.d.ts

@@ -24,26 +24,33 @@ footage?: ReadonlyArray<T | undefined>]>;
 /**
  * Describes one Actor's acknowledgement frontier.
  * `[actorID, sessionID, sessionEnd, ...]` contains removal Session/frontier pairs.
- * The application is responsible for acknowledging complete received Session prefixes.
+ * Actor-only tuples establish membership before removals, including offline Actors.
+ * Compaction requires equal complete Session frontiers from every active Actor.
+ * The application must deliver pending history before claiming that frontier.
  */
 type Acknowledgement = U32List;
-/** Ordered replication batch; delivery may be duplicated or causally reordered. */
+/** Replication batch within retained history; delivery may be duplicated or causally reordered. */
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
  * Retained state required to hydrate the same visible Projection.
- * One structural array and one JavaScript-owned content array.
+ * One structural array and JavaScript-owned Footage.
  * Small snapshots use six-word insertion records after length-prefixed ACKs;
  * `words[0]` locates those records. Large snapshots begin with
  * `[0, frontiersEnd, insertionCount]` and omit predictable coordinate fields.
- * Both layouts retain complete coordinates and acknowledgements.
+ * Both layouts encode the retained coordinates and acknowledgements.
+ * Eligible masks, deleted Footage and compacted Session claims are omitted;
+ * Actor membership remains. Compaction may translate retained coordinates.
  * Positive insertion diffs consume successive spans of `footage`.
+ * String-encoded Footage preserves Insertion order, not visible text order.
+ * It uses one UTF-16 code unit per Frame. Missing slots use
+ * NUL (`\u0000`); hydration splits the string with `split('')`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
-type Sequence<T> = Readonly<[
+type Sequence<T, StringEncoded extends boolean = false> = Readonly<[
 /** Acknowledgements followed by canonical Insertions in Structural Order. */
 words: U32List,
 /** Consecutive positive Insertion spans, including missing Footage slots. */
-footage: ReadonlyArray<T | undefined>]>;
+footage: StringEncoded extends true ? string : ReadonlyArray<T | undefined>]>;
 /** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
 type Splice<T> = Readonly<[
 /** First affected position in the Projection after preceding Splices. */
@@ -59,7 +66,7 @@ type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/errors/class.d.ts
 /** Semantic error codes reported by the Sequencer public API. */
-type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED';
+type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
 export declare class SequencerError extends Error {
   /** Machine-readable code identifying the failure condition. */
@@ -84,7 +91,7 @@ export declare class Projection<T> {
    * Prepares to sequence a projection, optionally hydrating from a trusted sequence stored by the application.
    *
    * @param actorID Actor identifier used in acknowledgements.
-   * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
    * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
@@ -155,10 +162,17 @@ export declare class Projection<T> {
   /**
    * Sequences state into a compact serializable format.
    *
+   * @remarks
+   * Register active Actors before removal. Equal complete Session frontiers
+   * permit masks and deleted Footage to be omitted from the retained checkpoint.
+   * Compaction may translate retained anchors without rewriting this instance.
+   *
+   * @param stringEncode Whether to concatenate Footage into a string; each text Frame must be one UTF-16 code unit. Defaults to `false`.
    * @returns A Sequence with acknowledged removals compacted in the exported state.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
+   * @throws {@link SequencerError} with code `STRING_ENCODING_FAILED` if Footage concatenation fails.
    */
-  sequence(): Sequence<T>;
+  sequence<StringEncoded extends boolean = false>(stringEncode?: StringEncoded): Sequence<T, StringEncoded>;
   /**
    * Returns the value at a Projection position.
    *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;KAShB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;KAYtD,SAAS,KAAK;;AAGtB,OAAO;;AAEP,SAAS,cAAc;;KAKf,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KCtEzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;EAUP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;KAiBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;KAKrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KC7EzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;;;EAiBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAWf,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}