@g9tm/syncdata 1.2.1

package/dist/protocol/dtos.d.ts

@@ -0,0 +1,280 @@
+import type { G9EConflictPolicy, G9EMoveOutPolicy, G9ESyncColumnType, G9ESyncDirection } from '../abstractions/enums.js';
+import { G9SyncException } from '../abstractions/errors.js';
+import type { G9Long } from '../abstractions/long.js';
+/** What a subscription must do next, as decided by the server (`G9ESubscriptionAction`). */
+export declare const G9ESubscriptionAction: {
+    readonly Ok: 0;
+    readonly Initial: 1;
+    readonly Reconcile: 2;
+    readonly ResyncRequired: 3;
+    readonly Unknown: 4;
+    readonly InvalidParameters: 5;
+    readonly Forbidden: 6;
+};
+export type G9ESubscriptionAction = (typeof G9ESubscriptionAction)[keyof typeof G9ESubscriptionAction];
+/** Kind of a planned pull part (`G9EPullPartKind`). */
+export declare const G9EPullPartKind: {
+    readonly Snapshot: 0;
+    readonly Delta: 1;
+    readonly Backfill: 2;
+};
+export type G9EPullPartKind = (typeof G9EPullPartKind)[keyof typeof G9EPullPartKind];
+/** Outcome of a command executed by the server (`G9ECommandStatus`). */
+export declare const G9ECommandStatus: {
+    readonly Ok: 0;
+    readonly Rejected: 1;
+    readonly Superseded: 2;
+};
+export type G9ECommandStatus = (typeof G9ECommandStatus)[keyof typeof G9ECommandStatus];
+export interface G9DtSyncError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: string | null;
+}
+/** `G9DtSyncError.ToException()`. */
+export declare function syncErrorToException(error: G9DtSyncError): G9SyncException;
+/** `G9DtSyncError.From(exception)`. */
+export declare function syncErrorFrom(exception: G9SyncException): G9DtSyncError;
+export interface G9DtColumnModel {
+    name: string;
+    type: G9ESyncColumnType;
+    nullable: boolean;
+}
+/** A subscription as the client holds it: name, canonical parameters and its sync state. */
+export interface G9DtSubscriptionRef {
+    name: string;
+    parameters: {
+        [name: string]: string;
+    };
+    /** Opaque server cursor of the last completed pull. Null before the first pull. */
+    cursor?: string | null;
+    definitionHash?: string | null;
+    authHash?: string | null;
+}
+/** Resume point after a chunk. Only chunks that carry one are safe restart points. */
+export interface G9DtPullContinuation {
+    partIndex: number;
+    afterKey?: string | null;
+    nextSequence: number;
+}
+/** One unit of a data stream; `payload` is a G9RowBatch frame. */
+export interface G9DtSyncChunk {
+    sequence: number;
+    payload?: Uint8Array | null;
+    rowCount: number;
+    subscriptionKey?: string | null;
+    isFinal: boolean;
+    continuation?: G9DtPullContinuation | null;
+    reconcileSummary?: G9DtReconcileSummary | null;
+}
+/** Server → client hint that tables changed. */
+export interface G9DtChangesAvailable {
+    tables: string[];
+}
+export interface G9DtClientTableModel {
+    name: string;
+    keyColumn: string;
+    keyType: G9ESyncColumnType;
+    columns: G9DtColumnModel[];
+}
+export interface G9DtHelloRequest {
+    clientId: string;
+    appVersion?: string | null;
+    protocolVersion: number;
+    tables: G9DtClientTableModel[];
+    subscriptions: G9DtSubscriptionRef[];
+}
+export interface G9DtColumnTypeMismatch {
+    name: string;
+    clientType: G9ESyncColumnType;
+    serverType: G9ESyncColumnType;
+}
+/** The column set both sides agreed on for one table. */
+export interface G9DtNegotiatedTable {
+    tableId: number;
+    name: string;
+    keyColumn: string;
+    keyType: G9ESyncColumnType;
+    columns: G9DtColumnModel[];
+    computedColumns: string[];
+    readOnlyColumns: string[];
+    missingColumns: string[];
+    typeMismatchColumns: G9DtColumnTypeMismatch[];
+    direction: G9ESyncDirection;
+    conflictPolicy: G9EConflictPolicy;
+}
+export interface G9DtParameterDefinition {
+    name: string;
+    type: G9ESyncColumnType;
+    required: boolean;
+    isList: boolean;
+}
+export interface G9DtSubscriptionDependency {
+    name: string;
+    required: boolean;
+}
+export interface G9DtSubscriptionDefinition {
+    name: string;
+    parameters: G9DtParameterDefinition[];
+    dependsOn: G9DtSubscriptionDependency[];
+    tables: string[];
+    ephemeral: boolean;
+    ttlSeconds: number;
+    heavy: boolean;
+    moveOutPolicy: G9EMoveOutPolicy;
+    reconcileIntervalMinutes: number;
+    definitionHash: string;
+}
+export interface G9DtSubscriptionState {
+    key: string;
+    action: G9ESubscriptionAction;
+    definitionHash?: string | null;
+    authHash?: string | null;
+    message?: string | null;
+}
+export interface G9DtHelloResult {
+    epoch: string;
+    /** Server clock at the answer, epoch milliseconds UTC (.NET `DateTime ServerTimeUtc`). */
+    serverTimeUtcMs: number;
+    protocolVersion: number;
+    tables: G9DtNegotiatedTable[];
+    unknownTables: string[];
+    definitions: G9DtSubscriptionDefinition[];
+    subscriptions: G9DtSubscriptionState[];
+    maxPushRows: number;
+    maxPushBytes: number;
+    error?: G9DtSyncError | null;
+}
+export interface G9DtTableColumns {
+    tableId: number;
+    columns: string[];
+}
+export interface G9DtRowRef {
+    tableId: number;
+    key: string;
+}
+export interface G9DtCommand {
+    commandId: string;
+    sequence: number;
+    name: string;
+    version: number;
+    payload: string;
+    createdUtcMs: number;
+    touched: G9DtRowRef[];
+}
+export interface G9DtCommandResult {
+    commandId: string;
+    status: G9ECommandStatus;
+    code?: string | null;
+    message?: string | null;
+    result?: string | null;
+}
+export interface G9DtPushRequest {
+    clientId: string;
+    batchId: number;
+    subscriptions: G9DtSubscriptionRef[];
+    tables: G9DtTableColumns[];
+    commands: G9DtCommand[];
+    heldTables: G9DtTableColumns[];
+    frameVersion: number;
+}
+export interface G9DtAcceptedRows {
+    tableId: number;
+    keys: string[];
+    versions: number[];
+    deleted: boolean[];
+}
+export interface G9DtRowRejection {
+    tableId: number;
+    key: string;
+    code: string;
+    message?: string | null;
+    sqlState?: string | null;
+    constraint?: string | null;
+    column?: string | null;
+    details?: string | null;
+}
+export interface G9DtRowConflict {
+    tableId: number;
+    key: string;
+    code: string;
+    /** Bits (push column order) the server changed after the client's base version; -1 when unknown. */
+    serverChangedMask: G9Long;
+    partiallyApplied: boolean;
+}
+export interface G9DtPushResult {
+    batchId: number;
+    alreadyApplied: boolean;
+    accepted: G9DtAcceptedRows[];
+    rejections: G9DtRowRejection[];
+    conflicts: G9DtRowConflict[];
+    canonicalFrames: Uint8Array[];
+    commandResults: G9DtCommandResult[];
+    error?: G9DtSyncError | null;
+}
+export interface G9DtBackfillRequest {
+    tableId: number;
+    columns: string[];
+}
+export interface G9DtPullRequest {
+    clientId: string;
+    subscriptions: G9DtSubscriptionRef[];
+    tables: G9DtTableColumns[];
+    backfills: G9DtBackfillRequest[];
+    frameVersion: number;
+}
+export interface G9DtPlannedPart {
+    subscriptionKey: string;
+    tableId: number;
+    kind: G9EPullPartKind;
+    rows: number;
+    estimatedBytes: number;
+}
+export interface G9DtSubscriptionCursor {
+    key: string;
+    cursor: string;
+    definitionHash: string;
+    authHash: string;
+}
+export interface G9DtPullPlan {
+    token: string;
+    parts: G9DtPlannedPart[];
+    totalRows: number;
+    estimatedBytes: number;
+    cursors: G9DtSubscriptionCursor[];
+    skipped: G9DtSubscriptionState[];
+    error?: G9DtSyncError | null;
+}
+export interface G9DtTableDigest {
+    tableId: number;
+    computedColumns: string[];
+    /** 256 bucket digests (XOR of row hashes). */
+    digests: G9Long[];
+    /** 256 bucket row counts. */
+    counts: number[];
+}
+export interface G9DtReconcileRequest {
+    clientId: string;
+    subscription: G9DtSubscriptionRef;
+    tables: G9DtTableDigest[];
+    frameVersion: number;
+}
+export interface G9DtTableBuckets {
+    tableId: number;
+    buckets: number[];
+}
+export interface G9DtReconcileSummary {
+    cursor: string;
+    definitionHash: string;
+    authHash: string;
+    mismatched: G9DtTableBuckets[];
+}
+export interface G9DtFetchRowsRequest {
+    clientId: string;
+    subscription: G9DtSubscriptionRef;
+    tableId: number;
+    keys: string[];
+    columns: string[];
+    frameVersion: number;
+}

package/dist/protocol/dtos.js

@@ -0,0 +1,33 @@
+import { G9SyncException } from '../abstractions/errors.js';
+/** What a subscription must do next, as decided by the server (`G9ESubscriptionAction`). */
+export const G9ESubscriptionAction = {
+    Ok: 0,
+    Initial: 1,
+    Reconcile: 2,
+    ResyncRequired: 3,
+    Unknown: 4,
+    InvalidParameters: 5,
+    Forbidden: 6,
+};
+/** Kind of a planned pull part (`G9EPullPartKind`). */
+export const G9EPullPartKind = {
+    Snapshot: 0,
+    Delta: 1,
+    Backfill: 2,
+};
+/** Outcome of a command executed by the server (`G9ECommandStatus`). */
+export const G9ECommandStatus = {
+    Ok: 0,
+    Rejected: 1,
+    Superseded: 2,
+};
+/** `G9DtSyncError.ToException()`. */
+export function syncErrorToException(error) {
+    var _a;
+    return new G9SyncException(error.code, error.message, { retryable: error.retryable, details: (_a = error.details) !== null && _a !== void 0 ? _a : null });
+}
+/** `G9DtSyncError.From(exception)`. */
+export function syncErrorFrom(exception) {
+    return { code: exception.code, message: exception.message, retryable: exception.retryable, details: exception.details };
+}
+//# sourceMappingURL=dtos.js.map

package/dist/protocol/dtos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dtos.js","sourceRoot":"","sources":["../../src/protocol/dtos.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,EAAE,EAAE,CAAC;IACL,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,cAAc,EAAE,CAAC;IACjB,OAAO,EAAE,CAAC;IACV,iBAAiB,EAAE,CAAC;IACpB,SAAS,EAAE,CAAC;CACJ,CAAC;AAGX,uDAAuD;AACvD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;CACH,CAAC;AAGX,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,EAAE,EAAE,CAAC;IACL,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;CACL,CAAC;AAYX,qCAAqC;AACrC,MAAM,UAAU,oBAAoB,CAAC,KAAoB;;IACvD,OAAO,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,MAAA,KAAK,CAAC,OAAO,mCAAI,IAAI,EAAE,CAAC,CAAC;AACxH,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,aAAa,CAAC,SAA0B;IACtD,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;AAC1H,CAAC","sourcesContent":["// Twins of G9SyncData.Protocol/Dtos/*.cs. Property names are the camelCase of the .NET names (the JSON wire names);\n// the MessagePack codec maps them to the PascalCase keys Nerdbank.MessagePack writes. .NET `long` values are numbers\n// except where they must stay exact: reconciliation digests and conflict masks are G9Long.\nimport type { G9EConflictPolicy, G9EMoveOutPolicy, G9ESyncColumnType, G9ESyncDirection } from '../abstractions/enums.js';\nimport { G9SyncException } from '../abstractions/errors.js';\nimport type { G9Long } from '../abstractions/long.js';\n\n/** What a subscription must do next, as decided by the server (`G9ESubscriptionAction`). */\nexport const G9ESubscriptionAction = {\n  Ok: 0,\n  Initial: 1,\n  Reconcile: 2,\n  ResyncRequired: 3,\n  Unknown: 4,\n  InvalidParameters: 5,\n  Forbidden: 6,\n} as const;\nexport type G9ESubscriptionAction = (typeof G9ESubscriptionAction)[keyof typeof G9ESubscriptionAction];\n\n/** Kind of a planned pull part (`G9EPullPartKind`). */\nexport const G9EPullPartKind = {\n  Snapshot: 0,\n  Delta: 1,\n  Backfill: 2,\n} as const;\nexport type G9EPullPartKind = (typeof G9EPullPartKind)[keyof typeof G9EPullPartKind];\n\n/** Outcome of a command executed by the server (`G9ECommandStatus`). */\nexport const G9ECommandStatus = {\n  Ok: 0,\n  Rejected: 1,\n  Superseded: 2,\n} as const;\nexport type G9ECommandStatus = (typeof G9ECommandStatus)[keyof typeof G9ECommandStatus];\n\n// ---------------------------------------------------------------- common\n\nexport interface G9DtSyncError {\n  code: string;\n  message: string;\n  retryable: boolean;\n  details?: string | null;\n}\n\n/** `G9DtSyncError.ToException()`. */\nexport function syncErrorToException(error: G9DtSyncError): G9SyncException {\n  return new G9SyncException(error.code, error.message, { retryable: error.retryable, details: error.details ?? null });\n}\n\n/** `G9DtSyncError.From(exception)`. */\nexport function syncErrorFrom(exception: G9SyncException): G9DtSyncError {\n  return { code: exception.code, message: exception.message, retryable: exception.retryable, details: exception.details };\n}\n\nexport interface G9DtColumnModel {\n  name: string;\n  type: G9ESyncColumnType;\n  nullable: boolean;\n}\n\n/** A subscription as the client holds it: name, canonical parameters and its sync state. */\nexport interface G9DtSubscriptionRef {\n  name: string;\n  parameters: { [name: string]: string };\n  /** Opaque server cursor of the last completed pull. Null before the first pull. */\n  cursor?: string | null;\n  definitionHash?: string | null;\n  authHash?: string | null;\n}\n\n/** Resume point after a chunk. Only chunks that carry one are safe restart points. */\nexport interface G9DtPullContinuation {\n  partIndex: number;\n  afterKey?: string | null;\n  nextSequence: number;\n}\n\n/** One unit of a data stream; `payload` is a G9RowBatch frame. */\nexport interface G9DtSyncChunk {\n  sequence: number;\n  payload?: Uint8Array | null;\n  rowCount: number;\n  subscriptionKey?: string | null;\n  isFinal: boolean;\n  continuation?: G9DtPullContinuation | null;\n  reconcileSummary?: G9DtReconcileSummary | null;\n}\n\n/** Server → client hint that tables changed. */\nexport interface G9DtChangesAvailable {\n  tables: string[];\n}\n\n// ---------------------------------------------------------------- hello\n\nexport interface G9DtClientTableModel {\n  name: string;\n  keyColumn: string;\n  keyType: G9ESyncColumnType;\n  columns: G9DtColumnModel[];\n}\n\nexport interface G9DtHelloRequest {\n  clientId: string;\n  appVersion?: string | null;\n  protocolVersion: number;\n  tables: G9DtClientTableModel[];\n  subscriptions: G9DtSubscriptionRef[];\n}\n\nexport interface G9DtColumnTypeMismatch {\n  name: string;\n  clientType: G9ESyncColumnType;\n  serverType: G9ESyncColumnType;\n}\n\n/** The column set both sides agreed on for one table. */\nexport interface G9DtNegotiatedTable {\n  tableId: number;\n  name: string;\n  keyColumn: string;\n  keyType: G9ESyncColumnType;\n  columns: G9DtColumnModel[];\n  computedColumns: string[];\n  readOnlyColumns: string[];\n  missingColumns: string[];\n  typeMismatchColumns: G9DtColumnTypeMismatch[];\n  direction: G9ESyncDirection;\n  conflictPolicy: G9EConflictPolicy;\n}\n\nexport interface G9DtParameterDefinition {\n  name: string;\n  type: G9ESyncColumnType;\n  required: boolean;\n  isList: boolean;\n}\n\nexport interface G9DtSubscriptionDependency {\n  name: string;\n  required: boolean;\n}\n\nexport interface G9DtSubscriptionDefinition {\n  name: string;\n  parameters: G9DtParameterDefinition[];\n  dependsOn: G9DtSubscriptionDependency[];\n  tables: string[];\n  ephemeral: boolean;\n  ttlSeconds: number;\n  heavy: boolean;\n  moveOutPolicy: G9EMoveOutPolicy;\n  reconcileIntervalMinutes: number;\n  definitionHash: string;\n}\n\nexport interface G9DtSubscriptionState {\n  key: string;\n  action: G9ESubscriptionAction;\n  definitionHash?: string | null;\n  authHash?: string | null;\n  message?: string | null;\n}\n\nexport interface G9DtHelloResult {\n  epoch: string;\n  /** Server clock at the answer, epoch milliseconds UTC (.NET `DateTime ServerTimeUtc`). */\n  serverTimeUtcMs: number;\n  protocolVersion: number;\n  tables: G9DtNegotiatedTable[];\n  unknownTables: string[];\n  definitions: G9DtSubscriptionDefinition[];\n  subscriptions: G9DtSubscriptionState[];\n  maxPushRows: number;\n  maxPushBytes: number;\n  error?: G9DtSyncError | null;\n}\n\n// ---------------------------------------------------------------- push / pull\n\nexport interface G9DtTableColumns {\n  tableId: number;\n  columns: string[];\n}\n\nexport interface G9DtRowRef {\n  tableId: number;\n  key: string;\n}\n\nexport interface G9DtCommand {\n  commandId: string;\n  sequence: number;\n  name: string;\n  version: number;\n  payload: string;\n  createdUtcMs: number;\n  touched: G9DtRowRef[];\n}\n\nexport interface G9DtCommandResult {\n  commandId: string;\n  status: G9ECommandStatus;\n  code?: string | null;\n  message?: string | null;\n  result?: string | null;\n}\n\nexport interface G9DtPushRequest {\n  clientId: string;\n  batchId: number;\n  subscriptions: G9DtSubscriptionRef[];\n  tables: G9DtTableColumns[];\n  commands: G9DtCommand[];\n  heldTables: G9DtTableColumns[];\n  frameVersion: number;\n}\n\nexport interface G9DtAcceptedRows {\n  tableId: number;\n  keys: string[];\n  versions: number[];\n  deleted: boolean[];\n}\n\nexport interface G9DtRowRejection {\n  tableId: number;\n  key: string;\n  code: string;\n  message?: string | null;\n  sqlState?: string | null;\n  constraint?: string | null;\n  column?: string | null;\n  details?: string | null;\n}\n\nexport interface G9DtRowConflict {\n  tableId: number;\n  key: string;\n  code: string;\n  /** Bits (push column order) the server changed after the client's base version; -1 when unknown. */\n  serverChangedMask: G9Long;\n  partiallyApplied: boolean;\n}\n\nexport interface G9DtPushResult {\n  batchId: number;\n  alreadyApplied: boolean;\n  accepted: G9DtAcceptedRows[];\n  rejections: G9DtRowRejection[];\n  conflicts: G9DtRowConflict[];\n  canonicalFrames: Uint8Array[];\n  commandResults: G9DtCommandResult[];\n  error?: G9DtSyncError | null;\n}\n\nexport interface G9DtBackfillRequest {\n  tableId: number;\n  columns: string[];\n}\n\nexport interface G9DtPullRequest {\n  clientId: string;\n  subscriptions: G9DtSubscriptionRef[];\n  tables: G9DtTableColumns[];\n  backfills: G9DtBackfillRequest[];\n  frameVersion: number;\n}\n\nexport interface G9DtPlannedPart {\n  subscriptionKey: string;\n  tableId: number;\n  kind: G9EPullPartKind;\n  rows: number;\n  estimatedBytes: number;\n}\n\nexport interface G9DtSubscriptionCursor {\n  key: string;\n  cursor: string;\n  definitionHash: string;\n  authHash: string;\n}\n\nexport interface G9DtPullPlan {\n  token: string;\n  parts: G9DtPlannedPart[];\n  totalRows: number;\n  estimatedBytes: number;\n  cursors: G9DtSubscriptionCursor[];\n  skipped: G9DtSubscriptionState[];\n  error?: G9DtSyncError | null;\n}\n\nexport interface G9DtTableDigest {\n  tableId: number;\n  computedColumns: string[];\n  /** 256 bucket digests (XOR of row hashes). */\n  digests: G9Long[];\n  /** 256 bucket row counts. */\n  counts: number[];\n}\n\nexport interface G9DtReconcileRequest {\n  clientId: string;\n  subscription: G9DtSubscriptionRef;\n  tables: G9DtTableDigest[];\n  frameVersion: number;\n}\n\nexport interface G9DtTableBuckets {\n  tableId: number;\n  buckets: number[];\n}\n\nexport interface G9DtReconcileSummary {\n  cursor: string;\n  definitionHash: string;\n  authHash: string;\n  mismatched: G9DtTableBuckets[];\n}\n\nexport interface G9DtFetchRowsRequest {\n  clientId: string;\n  subscription: G9DtSubscriptionRef;\n  tableId: number;\n  keys: string[];\n  columns: string[];\n  frameVersion: number;\n}\n"]}

package/dist/protocol/protocol.d.ts

@@ -0,0 +1,36 @@
+import { G9SyncException } from '../abstractions/errors.js';
+/** Protocol constants shared by every transport (`G9SyncProtocol`). */
+export declare const G9SyncProtocol: {
+    /** Wire protocol version. The server refuses a Hello from a different major version. */
+    readonly Version: 1;
+    /** The newest G9RowBatch body layout this build reads and writes (1 row-wise, 2 column-grouped; ADR-0040). */
+    readonly MaxFrameVersion: 2;
+    /** Default SignalR hub route. */
+    readonly DefaultHubRoute: "/g9sync";
+    /** Hub method names (client → server). */
+    readonly Methods: {
+        readonly Hello: "Hello";
+        readonly Push: "Push";
+        readonly PlanPull: "PlanPull";
+        readonly Pull: "Pull";
+        readonly Reconcile: "Reconcile";
+        readonly FetchRows: "FetchRows";
+    };
+    /** Listener method names (server → client). */
+    readonly Listeners: {
+        readonly OnChangesAvailable: "OnChangesAvailable";
+    };
+};
+/** The frame layout to answer a request with: the newest both sides know, and 1 for a sender that did not say. */
+export declare function negotiateFrameVersion(requested: number): number;
+/** The SignalR group of connections that negotiated a table (`G9SyncProtocol.TableGroup`). */
+export declare function tableGroup(logicalTable: string): string;
+/**
+ * Carries a G9SyncException through SignalR (`G9SyncHubErrors`): a HubException message is the only error text SignalR
+ * forwards, so the code travels inside it as `[G9S|{code}|{retryable 0/1}] {message}`.
+ */
+export declare const G9SyncHubErrors: {
+    format(exception: G9SyncException): string;
+    /** Finds the marker anywhere in `text` (the client wraps it in its own words); null when there is none. */
+    tryParse(text: string | null | undefined): G9SyncException | null;
+};

package/dist/protocol/protocol.js

@@ -0,0 +1,63 @@
+// Twins of G9SyncData.Protocol/G9SyncProtocol.cs and G9SyncHubContract.cs (G9SyncHubErrors).
+import { G9SyncException } from '../abstractions/errors.js';
+/** Protocol constants shared by every transport (`G9SyncProtocol`). */
+export const G9SyncProtocol = {
+    /** Wire protocol version. The server refuses a Hello from a different major version. */
+    Version: 1,
+    /** The newest G9RowBatch body layout this build reads and writes (1 row-wise, 2 column-grouped; ADR-0040). */
+    MaxFrameVersion: 2,
+    /** Default SignalR hub route. */
+    DefaultHubRoute: '/g9sync',
+    /** Hub method names (client → server). */
+    Methods: {
+        Hello: 'Hello',
+        Push: 'Push',
+        PlanPull: 'PlanPull',
+        Pull: 'Pull',
+        Reconcile: 'Reconcile',
+        FetchRows: 'FetchRows',
+    },
+    /** Listener method names (server → client). */
+    Listeners: {
+        OnChangesAvailable: 'OnChangesAvailable',
+    },
+};
+/** The frame layout to answer a request with: the newest both sides know, and 1 for a sender that did not say. */
+export function negotiateFrameVersion(requested) {
+    return Math.min(Math.max(requested, 1), G9SyncProtocol.MaxFrameVersion);
+}
+/** The SignalR group of connections that negotiated a table (`G9SyncProtocol.TableGroup`). */
+export function tableGroup(logicalTable) {
+    if (typeof logicalTable !== 'string' || logicalTable.trim() === '')
+        throw new TypeError('A table name is required.');
+    return 'g9sync:' + logicalTable.toLowerCase();
+}
+const PREFIX = '[G9S|';
+/**
+ * Carries a G9SyncException through SignalR (`G9SyncHubErrors`): a HubException message is the only error text SignalR
+ * forwards, so the code travels inside it as `[G9S|{code}|{retryable 0/1}] {message}`.
+ */
+export const G9SyncHubErrors = {
+    format(exception) {
+        return PREFIX + exception.code + '|' + (exception.retryable ? '1' : '0') + '] ' + exception.message;
+    },
+    /** Finds the marker anywhere in `text` (the client wraps it in its own words); null when there is none. */
+    tryParse(text) {
+        if (!text)
+            return null;
+        const start = text.indexOf(PREFIX);
+        if (start < 0)
+            return null;
+        const end = text.indexOf(']', start);
+        if (end < 0)
+            return null;
+        const header = text.slice(start + PREFIX.length, end);
+        const bar = header.lastIndexOf('|');
+        if (bar <= 0)
+            return null;
+        const code = header.slice(0, bar);
+        const retryable = header.slice(bar + 1) === '1';
+        return new G9SyncException(code, text.slice(end + 1).trim(), { retryable });
+    },
+};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol/protocol.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,wFAAwF;IACxF,OAAO,EAAE,CAAC;IACV,8GAA8G;IAC9G,eAAe,EAAE,CAAC;IAClB,iCAAiC;IACjC,eAAe,EAAE,SAAS;IAC1B,0CAA0C;IAC1C,OAAO,EAAE;QACP,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,WAAW;QACtB,SAAS,EAAE,WAAW;KACvB;IACD,+CAA+C;IAC/C,SAAS,EAAE;QACT,kBAAkB,EAAE,oBAAoB;KACzC;CACO,CAAC;AAEX,kHAAkH;AAClH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;AAC1E,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,SAAS,CAAC,2BAA2B,CAAC,CAAC;IACrH,OAAO,SAAS,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,MAAM,GAAG,OAAO,CAAC;AAEvB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,CAAC,SAA0B;QAC/B,OAAO,MAAM,GAAG,SAAS,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC;IACtG,CAAC;IAED,2GAA2G;IAC3G,QAAQ,CAAC,IAA+B;QACtC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACrC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC;QAChD,OAAO,IAAI,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF,CAAC","sourcesContent":["// Twins of G9SyncData.Protocol/G9SyncProtocol.cs and G9SyncHubContract.cs (G9SyncHubErrors).\nimport { G9SyncException } from '../abstractions/errors.js';\n\n/** Protocol constants shared by every transport (`G9SyncProtocol`). */\nexport const G9SyncProtocol = {\n  /** Wire protocol version. The server refuses a Hello from a different major version. */\n  Version: 1,\n  /** The newest G9RowBatch body layout this build reads and writes (1 row-wise, 2 column-grouped; ADR-0040). */\n  MaxFrameVersion: 2,\n  /** Default SignalR hub route. */\n  DefaultHubRoute: '/g9sync',\n  /** Hub method names (client → server). */\n  Methods: {\n    Hello: 'Hello',\n    Push: 'Push',\n    PlanPull: 'PlanPull',\n    Pull: 'Pull',\n    Reconcile: 'Reconcile',\n    FetchRows: 'FetchRows',\n  },\n  /** Listener method names (server → client). */\n  Listeners: {\n    OnChangesAvailable: 'OnChangesAvailable',\n  },\n} as const;\n\n/** The frame layout to answer a request with: the newest both sides know, and 1 for a sender that did not say. */\nexport function negotiateFrameVersion(requested: number): number {\n  return Math.min(Math.max(requested, 1), G9SyncProtocol.MaxFrameVersion);\n}\n\n/** The SignalR group of connections that negotiated a table (`G9SyncProtocol.TableGroup`). */\nexport function tableGroup(logicalTable: string): string {\n  if (typeof logicalTable !== 'string' || logicalTable.trim() === '') throw new TypeError('A table name is required.');\n  return 'g9sync:' + logicalTable.toLowerCase();\n}\n\nconst PREFIX = '[G9S|';\n\n/**\n * Carries a G9SyncException through SignalR (`G9SyncHubErrors`): a HubException message is the only error text SignalR\n * forwards, so the code travels inside it as `[G9S|{code}|{retryable 0/1}] {message}`.\n */\nexport const G9SyncHubErrors = {\n  format(exception: G9SyncException): string {\n    return PREFIX + exception.code + '|' + (exception.retryable ? '1' : '0') + '] ' + exception.message;\n  },\n\n  /** Finds the marker anywhere in `text` (the client wraps it in its own words); null when there is none. */\n  tryParse(text: string | null | undefined): G9SyncException | null {\n    if (!text) return null;\n    const start = text.indexOf(PREFIX);\n    if (start < 0) return null;\n    const end = text.indexOf(']', start);\n    if (end < 0) return null;\n    const header = text.slice(start + PREFIX.length, end);\n    const bar = header.lastIndexOf('|');\n    if (bar <= 0) return null;\n    const code = header.slice(0, bar);\n    const retryable = header.slice(bar + 1) === '1';\n    return new G9SyncException(code, text.slice(end + 1).trim(), { retryable });\n  },\n};\n"]}

package/dist/protocol/rowBatch/columnLayout.d.ts

@@ -0,0 +1,4 @@
+/** Converts a version 1 (row-wise) body to the version 2 (column-grouped) layout. */
+export declare function fromRows(rows: Uint8Array): Uint8Array;
+/** Converts a version 2 (column-grouped) body back to the version 1 layout, which is never longer. */
+export declare function toRows(columns: Uint8Array): Uint8Array;