@sovereignbase/sequencer 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -24,10 +24,12 @@ 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.
@@ -35,7 +37,9 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * 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`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
@@ -57,6 +61,23 @@ type Change<T> = ReadonlyArray<Splice<T>>;
 /** Visible changes and optional Gossip returned by `apply()` or `merge()`. */
 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';
+/** 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. */
+  readonly code: SequencerErrorCode;
+  /**
+   * Creates a Sequencer error.
+   *
+   * @param code Stable code identifying the failure condition.
+   * @param message Human-readable detail; defaults to `code`.
+   * @param options Standard error options; `cause` retains an underlying error.
+   */
+  constructor(code: SequencerErrorCode, message?: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/typescript/class.d.ts
 /** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
@@ -68,6 +89,7 @@ export declare class Projection<T> {
    *
    * @param actorID Actor identifier used in acknowledgements.
    * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
   /**
@@ -76,6 +98,7 @@ export declare class Projection<T> {
    * @param gossip Batch of Insertion and Acknowledgement tuples.
    * @returns Visible changes and optional acknowledgement Gossip, or
    * `undefined` for invalid input. Earlier entries may already have been applied.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   apply(gossip: unknown): Result<T> | undefined;
   /**
@@ -84,12 +107,14 @@ export declare class Projection<T> {
    * @param values Nonempty array of values to insert.
    * @param at Insertion position in `0..length()`, inclusive.
    * @returns Gossip describing the insertion.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   insert(values: Array<T>, at: number): Gossip<T>;
   /**
    * Returns the length, A.K.A. amount of entries of this projection.
    *
    * @returns Current Projection length.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   length(): number;
   /**
@@ -98,6 +123,7 @@ export declare class Projection<T> {
    * @param sequence Sequence to merge.
    * @returns Visible changes and optional acknowledgement Gossip, or
    * `undefined` if the Sequence has an invalid runtime shape.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   merge(sequence: unknown): Result<T> | undefined;
   /**
@@ -106,6 +132,7 @@ export declare class Projection<T> {
    * @param startAt First position to remove; defaults to 0.
    * @param endWith Last position to remove; defaults to `length() - 1`.
    * @returns Reducing Insertions and their acknowledgement as Gossip.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   remove(startAt?: number, endWith?: number): Gossip<T>;
   /**
@@ -115,6 +142,7 @@ export declare class Projection<T> {
    * @param startAt First position to replace; defaults to 0.
    * @param endWith Last position to replace; defaults to `length() - 1`.
    * @returns Removal and insertion Gossip, in that order.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
   /**
@@ -125,12 +153,19 @@ export declare class Projection<T> {
    * for propagating that decision to the relevant replicas.
    *
    * @param actorID Actor whose Acknowledgements are no longer required for compaction.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   retire(actorID: number): void;
   /**
    * 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.
+   *
    * @returns A Sequence with acknowledged removals compacted in the exported state.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   sequence(): Sequence<T>;
   /**
@@ -138,6 +173,7 @@ export declare class Projection<T> {
    *
    * @param at Valid visible position in `0..length() - 1`.
    * @returns The corresponding Footage value.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   value(at: number): T | undefined;
   /**
@@ -146,11 +182,12 @@ export declare class Projection<T> {
    * @param startAt First included position; defaults to 0.
    * @param endWith Last included position; defaults to `length() - 1`.
    * @returns A new array of values, or an empty array for an empty range.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   values(startAt?: number, endWith?: number): Array<T>;
   /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
 //#endregion
-export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, Splice, U32List };
+export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, U32List };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.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;;;;qBClExD,WAAW;WAWJ;;UATV;;;;;;;EASU,YAAA,iBAChB;;;;;;;;EAYF,MAAM,kBAAkB,OAAO;;;;;;;;EAW/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;EAS7C;;;;;;;;EAWA,MAAM,oBAAoB,OAAO;;;;;;;;EAWjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;EAYnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAmB1E,OAAO;;;;;;EASP,YAAY,SAAS;;;;;;;EAUrB,MAAM,aAAa;;;;;;;;EAWnB,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;;;;;;;;;;;;;KActD,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;;;;KC1EzD;;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;;;;;;;;;;;;EAeP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}

package/dist/index.d.ts

@@ -24,10 +24,12 @@ 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.
@@ -35,7 +37,9 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * 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`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
@@ -57,6 +61,23 @@ type Change<T> = ReadonlyArray<Splice<T>>;
 /** Visible changes and optional Gossip returned by `apply()` or `merge()`. */
 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';
+/** 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. */
+  readonly code: SequencerErrorCode;
+  /**
+   * Creates a Sequencer error.
+   *
+   * @param code Stable code identifying the failure condition.
+   * @param message Human-readable detail; defaults to `code`.
+   * @param options Standard error options; `cause` retains an underlying error.
+   */
+  constructor(code: SequencerErrorCode, message?: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/typescript/class.d.ts
 /** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
@@ -68,6 +89,7 @@ export declare class Projection<T> {
    *
    * @param actorID Actor identifier used in acknowledgements.
    * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
   /**
@@ -76,6 +98,7 @@ export declare class Projection<T> {
    * @param gossip Batch of Insertion and Acknowledgement tuples.
    * @returns Visible changes and optional acknowledgement Gossip, or
    * `undefined` for invalid input. Earlier entries may already have been applied.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   apply(gossip: unknown): Result<T> | undefined;
   /**
@@ -84,12 +107,14 @@ export declare class Projection<T> {
    * @param values Nonempty array of values to insert.
    * @param at Insertion position in `0..length()`, inclusive.
    * @returns Gossip describing the insertion.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   insert(values: Array<T>, at: number): Gossip<T>;
   /**
    * Returns the length, A.K.A. amount of entries of this projection.
    *
    * @returns Current Projection length.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   length(): number;
   /**
@@ -98,6 +123,7 @@ export declare class Projection<T> {
    * @param sequence Sequence to merge.
    * @returns Visible changes and optional acknowledgement Gossip, or
    * `undefined` if the Sequence has an invalid runtime shape.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   merge(sequence: unknown): Result<T> | undefined;
   /**
@@ -106,6 +132,7 @@ export declare class Projection<T> {
    * @param startAt First position to remove; defaults to 0.
    * @param endWith Last position to remove; defaults to `length() - 1`.
    * @returns Reducing Insertions and their acknowledgement as Gossip.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   remove(startAt?: number, endWith?: number): Gossip<T>;
   /**
@@ -115,6 +142,7 @@ export declare class Projection<T> {
    * @param startAt First position to replace; defaults to 0.
    * @param endWith Last position to replace; defaults to `length() - 1`.
    * @returns Removal and insertion Gossip, in that order.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
   /**
@@ -125,12 +153,19 @@ export declare class Projection<T> {
    * for propagating that decision to the relevant replicas.
    *
    * @param actorID Actor whose Acknowledgements are no longer required for compaction.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   retire(actorID: number): void;
   /**
    * 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.
+   *
    * @returns A Sequence with acknowledged removals compacted in the exported state.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   sequence(): Sequence<T>;
   /**
@@ -138,6 +173,7 @@ export declare class Projection<T> {
    *
    * @param at Valid visible position in `0..length() - 1`.
    * @returns The corresponding Footage value.
+   * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   value(at: number): T | undefined;
   /**
@@ -146,11 +182,12 @@ export declare class Projection<T> {
    * @param startAt First included position; defaults to 0.
    * @param endWith Last included position; defaults to `length() - 1`.
    * @returns A new array of values, or an empty array for an empty range.
+   * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   values(startAt?: number, endWith?: number): Array<T>;
   /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
 //#endregion
-export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, Splice, U32List };
+export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, U32List };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.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;;;;qBClExD,WAAW;WAWJ;;UATV;;;;;;;EASU,YAAA,iBAChB;;;;;;;;EAYF,MAAM,kBAAkB,OAAO;;;;;;;;EAW/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;EAS7C;;;;;;;;EAWA,MAAM,oBAAoB,OAAO;;;;;;;;EAWjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;EAYnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAmB1E,OAAO;;;;;;EASP,YAAY,SAAS;;;;;;;EAUrB,MAAM,aAAa;;;;;;;;EAWnB,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;;;;;;;;;;;;;KActD,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;;;;KC1EzD;;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;;;;;;;;;;;;EAeP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}