@g9tm/syncdata 1.2.1

package/dist/client/progress.js

@@ -0,0 +1,251 @@
+// Twins of G9SyncData.Client/Progress/G9DtSyncProgress.cs and G9CSyncProgressTracker.cs
+// (AiGuides/09-Progress-Model.md): monotonic progress from phase transitions and row/byte counts.
+/** Phases of a sync run, in execution order (`G9ESyncPhase`). */
+export const G9ESyncPhase = {
+    Queued: 0,
+    Connecting: 1,
+    Pushing: 2,
+    Reconciling: 3,
+    Planning: 4,
+    Downloading: 5,
+    Applying: 6,
+    PostStep: 7,
+    Completed: 8,
+    Canceled: 9,
+    Failed: 10,
+};
+const PHASE_NAMES = ['Queued', 'Connecting', 'Pushing', 'Reconciling', 'Planning', 'Downloading', 'Applying', 'PostStep', 'Completed', 'Canceled', 'Failed'];
+/** The .NET enum member name of a phase (the statistics and PhaseMs keys), e.g. `Downloading`. */
+export function phaseName(phase) {
+    var _a;
+    return (_a = PHASE_NAMES[phase]) !== null && _a !== void 0 ? _a : String(phase);
+}
+/**
+ * Turns phase transitions and counts into monotonic progress. Each phase entered gets a span of the REMAINING bar in
+ * proportion to its expected share of the remaining work, so monotonicity holds by construction; a phase without a
+ * real signal creeps toward 90% of its span along an exponential curve scaled by its expected duration.
+ */
+export class G9SyncProgressTracker {
+    constructor(runId, publish, queuedBehind, maxHz) {
+        this._plan = [];
+        this._durations = {};
+        this._runStart = Date.now();
+        this._phaseStart = Date.now();
+        this._timer = null;
+        this._phase = G9ESyncPhase.Queued;
+        this._postStep = null;
+        this._table = null;
+        this._subscription = null;
+        this._base = 0;
+        this._span = 0;
+        this._overall = 0;
+        this._fraction = 0;
+        this._phaseExpectedMs = 0;
+        this._rowsDone = 0;
+        this._rowsTotal = 0;
+        this._bytesDone = 0;
+        this._bytesTotal = 0;
+        this._lastPublish = 0;
+        this._realSignal = false;
+        this._terminal = false;
+        this._cancelPending = false;
+        this._disposed = false;
+        this._lastPublished = null;
+        this._runId = runId;
+        this._publish = publish;
+        this._queuedBehind = queuedBehind;
+        this._minIntervalMs = maxHz <= 0 ? 0 : 1000 / maxHz;
+    }
+    get overall() {
+        return this._overall;
+    }
+    /** Measured milliseconds per phase (post steps keyed `PostStep:name`). */
+    get durations() {
+        const out = {};
+        for (const key of Object.keys(this._durations))
+            out[key] = this._durations[key];
+        return out;
+    }
+    /** Appends a phase to the plan with its expected duration. */
+    plan(phase, expectedMs, name = null) {
+        if (!this._terminal)
+            this._plan.push({ phase, name, expectedMs: Math.max(0, expectedMs) });
+    }
+    /** Updates the expected duration of a planned phase that has not started yet. */
+    expect(phase, expectedMs, name = null) {
+        for (const entry of this._plan) {
+            if (entry.phase === phase && entry.name === name) {
+                entry.expectedMs = Math.max(0, expectedMs);
+                return;
+            }
+        }
+    }
+    enter(phase, rowsTotal = 0, bytesTotal = 0, name = null) {
+        if (this._terminal || this._disposed)
+            return;
+        this._close();
+        let index = -1;
+        for (let i = 0; i < this._plan.length; i++) {
+            const entry = this._plan[i];
+            if (entry.phase === phase && entry.name === name) {
+                index = i;
+                break;
+            }
+        }
+        let expected = 500;
+        if (index >= 0) {
+            expected = this._plan[index].expectedMs;
+            this._plan.splice(0, index + 1);
+        }
+        expected = Math.max(1, expected);
+        let remaining = 0;
+        for (const entry of this._plan)
+            remaining += entry.expectedMs;
+        this._base = this._overall;
+        this._span = ((1 - this._base) * expected) / (expected + remaining);
+        this._phase = phase;
+        this._postStep = name;
+        this._rowsDone = 0;
+        this._rowsTotal = Math.max(0, rowsTotal);
+        this._bytesDone = 0;
+        this._bytesTotal = Math.max(0, bytesTotal);
+        this._fraction = 0;
+        this._realSignal = false;
+        this._phaseExpectedMs = expected;
+        this._phaseStart = Date.now();
+        if (this._timer === null)
+            this._timer = setInterval(() => this._creep(), 200);
+        this._emit(this._sample(true));
+    }
+    /** Reports absolute counts for the current phase. */
+    report(rowsDone, bytesDone = -1, table = null, subscriptionKey = null) {
+        if (this._terminal || this._disposed)
+            return;
+        this._rowsDone = Math.max(0, rowsDone);
+        if (bytesDone >= 0)
+            this._bytesDone = bytesDone;
+        if (table !== null)
+            this._table = table;
+        if (subscriptionKey !== null)
+            this._subscription = subscriptionKey;
+        const fraction = this._rowsTotal > 0 ? this._rowsDone / this._rowsTotal : this._bytesTotal > 0 ? this._bytesDone / this._bytesTotal : this._fraction;
+        this._realSignal = this._rowsTotal > 0 || this._bytesTotal > 0;
+        this._advance(fraction);
+        this._emit(this._sample(false));
+    }
+    /** Reports a 0..1 fraction of the current phase (post steps). */
+    reportFraction(fraction) {
+        if (this._terminal || this._disposed)
+            return;
+        this._realSignal = true;
+        this._advance(fraction);
+        this._emit(this._sample(false));
+    }
+    setCancelPending() {
+        if (this._terminal || this._disposed)
+            return;
+        this._cancelPending = true;
+        this._emit(this._sample(true));
+    }
+    complete(terminal) {
+        if (this._terminal || this._disposed)
+            return;
+        this._close();
+        this._terminal = true;
+        this._stopTimer();
+        if (terminal === G9ESyncPhase.Completed) {
+            this._overall = 1;
+            this._fraction = 1;
+        }
+        this._phase = terminal;
+        this._emit(this._sample(true));
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._stopTimer();
+    }
+    _stopTimer() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+    _creep() {
+        if (this._terminal || this._disposed || this._realSignal || this._phase === G9ESyncPhase.Queued)
+            return;
+        const elapsed = Date.now() - this._phaseStart;
+        this._advance(0.9 * (1 - Math.exp(-elapsed / Math.max(100, this._phaseExpectedMs))));
+        this._emit(this._sample(false));
+    }
+    _advance(fraction) {
+        const clamped = Math.min(Math.max(fraction, 0), 0.995);
+        if (clamped > this._fraction)
+            this._fraction = clamped;
+        const overall = Math.min(0.999, this._base + this._span * this._fraction);
+        if (overall > this._overall)
+            this._overall = overall;
+    }
+    _close() {
+        var _a, _b;
+        const phase = this._phase;
+        if (phase === G9ESyncPhase.Queued || phase === G9ESyncPhase.Completed || phase === G9ESyncPhase.Canceled || phase === G9ESyncPhase.Failed)
+            return;
+        const key = phase === G9ESyncPhase.PostStep ? 'PostStep:' + ((_a = this._postStep) !== null && _a !== void 0 ? _a : '') : phaseName(phase);
+        this._durations[key] = ((_b = this._durations[key]) !== null && _b !== void 0 ? _b : 0) + (Date.now() - this._phaseStart);
+        this._overall = Math.max(this._overall, Math.min(0.999, this._base + this._span));
+    }
+    _sample(force) {
+        const now = Date.now();
+        if (!force && now - this._lastPublish < this._minIntervalMs)
+            return null;
+        this._lastPublish = now;
+        const phaseSeconds = Math.max(0.001, (now - this._phaseStart) / 1000);
+        let eta = null;
+        if (this._terminal)
+            eta = 0;
+        else if (this._overall > 0.02)
+            eta = ((now - this._runStart) * (1 - this._overall)) / this._overall;
+        let queued = 0;
+        try {
+            queued = this._queuedBehind();
+        }
+        catch {
+            queued = 0;
+        }
+        return {
+            runId: this._runId,
+            phase: this._phase,
+            overall: this._overall,
+            phaseFraction: this._fraction,
+            rowsDone: this._rowsDone,
+            rowsTotal: this._rowsTotal,
+            bytesDone: this._bytesDone,
+            bytesTotal: this._bytesTotal,
+            subscriptionKey: this._subscription,
+            table: this._table,
+            rowsPerSecond: this._rowsDone / phaseSeconds,
+            etaMs: eta,
+            queuedBehind: queued,
+            postStepName: this._postStep,
+            cancelPending: this._cancelPending,
+        };
+    }
+    /** Publishes a sample unless it would go backwards (lower overall or an earlier phase). */
+    _emit(sample) {
+        if (sample === null)
+            return;
+        const last = this._lastPublished;
+        if (last !== null && (sample.overall < last.overall || sample.phase < last.phase))
+            return;
+        this._lastPublished = sample;
+        try {
+            this._publish(sample);
+        }
+        catch {
+            // A progress consumer must never break the sync.
+        }
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/client/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/client/progress.ts"],"names":[],"mappings":"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","sourcesContent":["// Twins of G9SyncData.Client/Progress/G9DtSyncProgress.cs and G9CSyncProgressTracker.cs\n// (AiGuides/09-Progress-Model.md): monotonic progress from phase transitions and row/byte counts.\n\n/** Phases of a sync run, in execution order (`G9ESyncPhase`). */\nexport const G9ESyncPhase = {\n  Queued: 0,\n  Connecting: 1,\n  Pushing: 2,\n  Reconciling: 3,\n  Planning: 4,\n  Downloading: 5,\n  Applying: 6,\n  PostStep: 7,\n  Completed: 8,\n  Canceled: 9,\n  Failed: 10,\n} as const;\nexport type G9ESyncPhase = (typeof G9ESyncPhase)[keyof typeof G9ESyncPhase];\n\nconst PHASE_NAMES = ['Queued', 'Connecting', 'Pushing', 'Reconciling', 'Planning', 'Downloading', 'Applying', 'PostStep', 'Completed', 'Canceled', 'Failed'];\n\n/** The .NET enum member name of a phase (the statistics and PhaseMs keys), e.g. `Downloading`. */\nexport function phaseName(phase: number): string {\n  return PHASE_NAMES[phase] ?? String(phase);\n}\n\n/**\n * One progress sample. `overall` is monotonic within a run and reaches 1 only when the run completed. The library emits\n * numbers and phases; localising them is the app's job.\n */\nexport interface G9DtSyncProgress {\n  runId: string;\n  phase: G9ESyncPhase;\n  /** 0..1, monotonic. */\n  overall: number;\n  /** 0..1 inside the phase. */\n  phaseFraction: number;\n  rowsDone: number;\n  rowsTotal: number;\n  bytesDone: number;\n  bytesTotal: number;\n  subscriptionKey: string | null;\n  table: string | null;\n  rowsPerSecond: number;\n  /** Estimated milliseconds to completion of the run, or null while unknown. */\n  etaMs: number | null;\n  queuedBehind: number;\n  postStepName: string | null;\n  cancelPending: boolean;\n}\n\ninterface PlanEntry {\n  phase: G9ESyncPhase;\n  name: string | null;\n  expectedMs: number;\n}\n\n/**\n * Turns phase transitions and counts into monotonic progress. Each phase entered gets a span of the REMAINING bar in\n * proportion to its expected share of the remaining work, so monotonicity holds by construction; a phase without a\n * real signal creeps toward 90% of its span along an exponential curve scaled by its expected duration.\n */\nexport class G9SyncProgressTracker {\n  private readonly _runId: string;\n  private readonly _publish: (progress: G9DtSyncProgress) => void;\n  private readonly _queuedBehind: () => number;\n  private readonly _minIntervalMs: number;\n  private readonly _plan: PlanEntry[] = [];\n  private readonly _durations: { [key: string]: number } = {};\n  private readonly _runStart = Date.now();\n  private _phaseStart = Date.now();\n  private _timer: ReturnType<typeof setInterval> | null = null;\n\n  private _phase: G9ESyncPhase = G9ESyncPhase.Queued;\n  private _postStep: string | null = null;\n  private _table: string | null = null;\n  private _subscription: string | null = null;\n  private _base = 0;\n  private _span = 0;\n  private _overall = 0;\n  private _fraction = 0;\n  private _phaseExpectedMs = 0;\n  private _rowsDone = 0;\n  private _rowsTotal = 0;\n  private _bytesDone = 0;\n  private _bytesTotal = 0;\n  private _lastPublish = 0;\n  private _realSignal = false;\n  private _terminal = false;\n  private _cancelPending = false;\n  private _disposed = false;\n  private _lastPublished: G9DtSyncProgress | null = null;\n\n  constructor(runId: string, publish: (progress: G9DtSyncProgress) => void, queuedBehind: () => number, maxHz: number) {\n    this._runId = runId;\n    this._publish = publish;\n    this._queuedBehind = queuedBehind;\n    this._minIntervalMs = maxHz <= 0 ? 0 : 1000 / maxHz;\n  }\n\n  get overall(): number {\n    return this._overall;\n  }\n\n  /** Measured milliseconds per phase (post steps keyed `PostStep:name`). */\n  get durations(): { [key: string]: number } {\n    const out: { [key: string]: number } = {};\n    for (const key of Object.keys(this._durations)) out[key] = this._durations[key] as number;\n    return out;\n  }\n\n  /** Appends a phase to the plan with its expected duration. */\n  plan(phase: G9ESyncPhase, expectedMs: number, name: string | null = null): void {\n    if (!this._terminal) this._plan.push({ phase, name, expectedMs: Math.max(0, expectedMs) });\n  }\n\n  /** Updates the expected duration of a planned phase that has not started yet. */\n  expect(phase: G9ESyncPhase, expectedMs: number, name: string | null = null): void {\n    for (const entry of this._plan) {\n      if (entry.phase === phase && entry.name === name) {\n        entry.expectedMs = Math.max(0, expectedMs);\n        return;\n      }\n    }\n  }\n\n  enter(phase: G9ESyncPhase, rowsTotal = 0, bytesTotal = 0, name: string | null = null): void {\n    if (this._terminal || this._disposed) return;\n    this._close();\n    let index = -1;\n    for (let i = 0; i < this._plan.length; i++) {\n      const entry = this._plan[i] as PlanEntry;\n      if (entry.phase === phase && entry.name === name) {\n        index = i;\n        break;\n      }\n    }\n    let expected = 500;\n    if (index >= 0) {\n      expected = (this._plan[index] as PlanEntry).expectedMs;\n      this._plan.splice(0, index + 1);\n    }\n    expected = Math.max(1, expected);\n    let remaining = 0;\n    for (const entry of this._plan) remaining += entry.expectedMs;\n    this._base = this._overall;\n    this._span = ((1 - this._base) * expected) / (expected + remaining);\n    this._phase = phase;\n    this._postStep = name;\n    this._rowsDone = 0;\n    this._rowsTotal = Math.max(0, rowsTotal);\n    this._bytesDone = 0;\n    this._bytesTotal = Math.max(0, bytesTotal);\n    this._fraction = 0;\n    this._realSignal = false;\n    this._phaseExpectedMs = expected;\n    this._phaseStart = Date.now();\n    if (this._timer === null) this._timer = setInterval(() => this._creep(), 200);\n    this._emit(this._sample(true));\n  }\n\n  /** Reports absolute counts for the current phase. */\n  report(rowsDone: number, bytesDone = -1, table: string | null = null, subscriptionKey: string | null = null): void {\n    if (this._terminal || this._disposed) return;\n    this._rowsDone = Math.max(0, rowsDone);\n    if (bytesDone >= 0) this._bytesDone = bytesDone;\n    if (table !== null) this._table = table;\n    if (subscriptionKey !== null) this._subscription = subscriptionKey;\n    const fraction = this._rowsTotal > 0 ? this._rowsDone / this._rowsTotal : this._bytesTotal > 0 ? this._bytesDone / this._bytesTotal : this._fraction;\n    this._realSignal = this._rowsTotal > 0 || this._bytesTotal > 0;\n    this._advance(fraction);\n    this._emit(this._sample(false));\n  }\n\n  /** Reports a 0..1 fraction of the current phase (post steps). */\n  reportFraction(fraction: number): void {\n    if (this._terminal || this._disposed) return;\n    this._realSignal = true;\n    this._advance(fraction);\n    this._emit(this._sample(false));\n  }\n\n  setCancelPending(): void {\n    if (this._terminal || this._disposed) return;\n    this._cancelPending = true;\n    this._emit(this._sample(true));\n  }\n\n  complete(terminal: G9ESyncPhase): void {\n    if (this._terminal || this._disposed) return;\n    this._close();\n    this._terminal = true;\n    this._stopTimer();\n    if (terminal === G9ESyncPhase.Completed) {\n      this._overall = 1;\n      this._fraction = 1;\n    }\n    this._phase = terminal;\n    this._emit(this._sample(true));\n  }\n\n  dispose(): void {\n    if (this._disposed) return;\n    this._disposed = true;\n    this._stopTimer();\n  }\n\n  private _stopTimer(): void {\n    if (this._timer !== null) {\n      clearInterval(this._timer);\n      this._timer = null;\n    }\n  }\n\n  private _creep(): void {\n    if (this._terminal || this._disposed || this._realSignal || this._phase === G9ESyncPhase.Queued) return;\n    const elapsed = Date.now() - this._phaseStart;\n    this._advance(0.9 * (1 - Math.exp(-elapsed / Math.max(100, this._phaseExpectedMs))));\n    this._emit(this._sample(false));\n  }\n\n  private _advance(fraction: number): void {\n    const clamped = Math.min(Math.max(fraction, 0), 0.995);\n    if (clamped > this._fraction) this._fraction = clamped;\n    const overall = Math.min(0.999, this._base + this._span * this._fraction);\n    if (overall > this._overall) this._overall = overall;\n  }\n\n  private _close(): void {\n    const phase = this._phase;\n    if (phase === G9ESyncPhase.Queued || phase === G9ESyncPhase.Completed || phase === G9ESyncPhase.Canceled || phase === G9ESyncPhase.Failed) return;\n    const key = phase === G9ESyncPhase.PostStep ? 'PostStep:' + (this._postStep ?? '') : phaseName(phase);\n    this._durations[key] = (this._durations[key] ?? 0) + (Date.now() - this._phaseStart);\n    this._overall = Math.max(this._overall, Math.min(0.999, this._base + this._span));\n  }\n\n  private _sample(force: boolean): G9DtSyncProgress | null {\n    const now = Date.now();\n    if (!force && now - this._lastPublish < this._minIntervalMs) return null;\n    this._lastPublish = now;\n    const phaseSeconds = Math.max(0.001, (now - this._phaseStart) / 1000);\n    let eta: number | null = null;\n    if (this._terminal) eta = 0;\n    else if (this._overall > 0.02) eta = ((now - this._runStart) * (1 - this._overall)) / this._overall;\n    let queued = 0;\n    try {\n      queued = this._queuedBehind();\n    } catch {\n      queued = 0;\n    }\n    return {\n      runId: this._runId,\n      phase: this._phase,\n      overall: this._overall,\n      phaseFraction: this._fraction,\n      rowsDone: this._rowsDone,\n      rowsTotal: this._rowsTotal,\n      bytesDone: this._bytesDone,\n      bytesTotal: this._bytesTotal,\n      subscriptionKey: this._subscription,\n      table: this._table,\n      rowsPerSecond: this._rowsDone / phaseSeconds,\n      etaMs: eta,\n      queuedBehind: queued,\n      postStepName: this._postStep,\n      cancelPending: this._cancelPending,\n    };\n  }\n\n  /** Publishes a sample unless it would go backwards (lower overall or an earlier phase). */\n  private _emit(sample: G9DtSyncProgress | null): void {\n    if (sample === null) return;\n    const last = this._lastPublished;\n    if (last !== null && (sample.overall < last.overall || sample.phase < last.phase)) return;\n    this._lastPublished = sample;\n    try {\n      this._publish(sample);\n    } catch {\n      // A progress consumer must never break the sync.\n    }\n  }\n}\n"]}

package/dist/client/runs.d.ts

@@ -0,0 +1,219 @@
+import type { G9ESyncColumnType } from '../abstractions/enums.js';
+import { G9SyncException } from '../abstractions/errors.js';
+import type { G9DtSubscriptionState } from '../protocol/dtos.js';
+import { type G9AbortController } from '../internal/abort.js';
+import type { G9DtSyncProgress, G9ESyncPhase } from './progress.js';
+import { G9ApplyReport, type G9ApplySlice, type G9PendingSummary, type G9SyncRunReport, type G9SyncSubscriptionRecord } from './storeTypes.js';
+/** Scheduling priority (`G9ESyncPriority`). A higher priority pre-empts a running background run. */
+export declare const G9ESyncPriority: {
+    readonly Background: 0;
+    readonly Foreground: 1;
+    readonly UserInteractive: 2;
+};
+export type G9ESyncPriority = (typeof G9ESyncPriority)[keyof typeof G9ESyncPriority];
+export declare function priorityName(priority: number): string;
+/** `G9ESyncOutcome`. */
+export declare const G9ESyncOutcome: {
+    readonly Succeeded: 0;
+    /** Data moved, but some rows were rejected or some subscriptions reported problems. */
+    readonly CompletedWithRejections: 1;
+    readonly Failed: 2;
+    readonly Canceled: 3;
+};
+export type G9ESyncOutcome = (typeof G9ESyncOutcome)[keyof typeof G9ESyncOutcome];
+export declare function outcomeName(outcome: number): string;
+/** Context handed to an app-owned post step (`G9CSyncPostStepContext`). */
+export interface G9SyncPostStepContext {
+    run: G9SyncRun;
+    /** Everything this run changed so far. */
+    changes: G9ApplyReport;
+    /** Report 0..1 of the step; mapped into the step's slice of the bar. */
+    progress: (fraction: number) => void;
+}
+/** An app-owned step that runs after the data applied and owns a slice of the progress bar (`G9CSyncPostStep`). */
+export declare class G9SyncPostStep {
+    readonly name: string;
+    readonly weightHint: number;
+    readonly action: (context: G9SyncPostStepContext, signal: AbortSignal) => Promise<void>;
+    constructor(name: string, weightHint: number, action: (context: G9SyncPostStepContext, signal: AbortSignal) => Promise<void>);
+}
+/** A sync request (`G9CSyncRequest`). */
+export interface G9SyncRequest {
+    /** Subscription keys or names to pull; omitted = every local subscription (background runs skip heavy ones). */
+    subscriptions?: readonly string[] | null;
+    push?: boolean;
+    pull?: boolean;
+    /** Reconcile the selected subscriptions even when nothing asks for it. */
+    forceReconcile?: boolean;
+    priority?: G9ESyncPriority;
+    postSteps?: readonly G9SyncPostStep[];
+    progress?: ((progress: G9DtSyncProgress) => void) | null;
+    signal?: AbortSignal | null;
+}
+/** The request with its defaults filled in. */
+export interface G9ResolvedSyncRequest {
+    subscriptions: readonly string[] | null;
+    push: boolean;
+    pull: boolean;
+    forceReconcile: boolean;
+    priority: G9ESyncPriority;
+    postSteps: readonly G9SyncPostStep[];
+    progress: ((progress: G9DtSyncProgress) => void) | null;
+    signal: AbortSignal | null;
+}
+export declare function resolveRequest(request: G9SyncRequest | null | undefined): G9ResolvedSyncRequest;
+/** `G9CSyncRequest.CanCoalesce`. */
+export declare function canCoalesce(request: G9ResolvedSyncRequest): boolean;
+/** `G9CSyncRequest.Signature`. */
+export declare function requestSignature(request: G9ResolvedSyncRequest): string;
+/** One defect of the client model, as the server sees it (`G9CSyncModelProblem`). */
+export interface G9SyncModelProblem {
+    code: string;
+    table: string;
+    column: string;
+    clientType: G9ESyncColumnType;
+    serverType: G9ESyncColumnType;
+}
+export declare function describeModelProblem(problem: G9SyncModelProblem): string;
+/** The result of a run (`G9CSyncRunResult`). */
+export interface G9SyncRunResult {
+    runId: string;
+    outcome: G9ESyncOutcome;
+    error: G9SyncException | null;
+    pushed: number;
+    rejected: number;
+    conflicts: number;
+    downloaded: number;
+    applied: number;
+    durationMs: number;
+    /** Milliseconds spent in each phase of this run, keyed by phase name. */
+    phaseMs: {
+        [phase: string]: number;
+    };
+    subscriptions: string[];
+    /** Subscriptions that could not sync, with the server's reason. */
+    problems: G9DtSubscriptionState[];
+    /** Defects of the client model the server reported in this run's hello (ADR-0061). */
+    modelProblems: G9SyncModelProblem[];
+    changes: G9ApplyReport;
+    isSuccess: boolean;
+}
+export declare function makeRunResult(fields: Partial<G9SyncRunResult> & {
+    runId: string;
+    outcome: G9ESyncOutcome;
+}): G9SyncRunResult;
+/** A queued or running sync (`G9CSyncRun`). Await {@link completion}; read progress with {@link onProgress} or {@link progress}. */
+export declare class G9SyncRun {
+    readonly runId: string;
+    readonly request: G9ResolvedSyncRequest;
+    readonly completion: Promise<G9SyncRunResult>;
+    latestProgress: G9DtSyncProgress | null;
+    isStarted: boolean;
+    /** @internal */
+    readonly cancellation: G9AbortController;
+    /** @internal */
+    preempted: boolean;
+    private _resolve;
+    private readonly _listeners;
+    private readonly _buffer;
+    private readonly _waiters;
+    private _done;
+    private _unlink;
+    constructor(request: G9ResolvedSyncRequest);
+    /** Requests cancellation. Network phases stop at once; an apply in progress finishes atomically first. */
+    cancel(): void;
+    /** Subscribes to progress samples; returns the unsubscribe function. */
+    onProgress(listener: (progress: G9DtSyncProgress) => void): () => void;
+    /** The progress stream (bounded: the oldest samples are dropped when a reader falls 64 behind), ending with the run. */
+    progress(): AsyncIterable<G9DtSyncProgress>;
+    /** @internal */
+    publish(progress: G9DtSyncProgress): void;
+    /** @internal */
+    complete(result: G9SyncRunResult): void;
+}
+/** `G9CSubscriptionOptions`. */
+export interface G9SubscriptionOptions {
+    /** Overrides the server definition's ephemeral flag. */
+    ephemeral?: boolean;
+    ttlMs?: number;
+    /** The rows already exist locally: reconcile instead of downloading a snapshot. Call adoptExistingRows first. */
+    adoptExistingRows?: boolean;
+}
+/** Engine options (`G9CSyncEngineOptions`). Durations are milliseconds. */
+export interface G9SyncEngineOptions {
+    /** Sent at Hello; the server's connect gates may refuse old versions. */
+    appVersion?: string | null;
+    pushBatchRows?: number;
+    /** Transient failures retried inside one run. */
+    maxRetries?: number;
+    retryBaseDelayMs?: number;
+    /** Queue a background pull when the server pokes about changed tables. */
+    pullOnChangesAvailable?: boolean;
+    changesDebounceMs?: number;
+    progressMaxHz?: number;
+    fetchKeysPerRequest?: number;
+    /** Rows a reconciliation fetches before it applies them (ADR-0066). */
+    reconcileApplyRows?: number;
+    /** A reconciliation that would fetch at least this many rows of one table hands them to a staged snapshot (ADR-0066). 0 = never. */
+    reconcileSnapshotThreshold?: number;
+    /** The largest decoded body accepted from one server frame (ADR-0051). */
+    maxDecodedFrameBytes?: number;
+    /** The newest G9RowBatch body layout to ask the server for (ADR-0040). */
+    maxFrameVersion?: number;
+    /** Fail a run when the server reports a client column whose type differs (ADR-0061). */
+    failOnTypeMismatch?: boolean;
+    /** A staged pull older than this is discarded instead of resumed. */
+    stagedPullMaxAgeMs?: number;
+    /** Most payload bytes kept in stages other than the one a run resumes (ADR-0060). */
+    stagedPullsMaxBytes?: number;
+    keepDeletedFeedEntries?: number;
+    keepRunReports?: number;
+    /** Where the engine logs (the ILogger twin); silent when omitted. */
+    logger?: G9SyncLogger | null;
+    /** Platform integration (foreground service, keep-awake, connectivity). */
+    hooks?: G9SyncHostHooks | null;
+}
+export type G9ResolvedEngineOptions = Required<Omit<G9SyncEngineOptions, 'appVersion' | 'logger' | 'hooks'>> & {
+    appVersion: string | null;
+    logger: G9SyncLogger | null;
+    hooks: G9SyncHostHooks | null;
+};
+export declare function resolveEngineOptions(options: G9SyncEngineOptions | null | undefined): G9ResolvedEngineOptions;
+/** Log levels of {@link G9SyncLogger} (Microsoft.Extensions.Logging's). */
+export type G9SyncLogLevel = 'debug' | 'information' | 'warning' | 'error';
+/** Where the library logs. `eventId` is the .NET LoggerMessage event id of the same message. */
+export interface G9SyncLogger {
+    log(level: G9SyncLogLevel, eventId: number, message: string, error?: unknown): void;
+}
+/** Platform integration points (`IG9SyncHostHooks`). */
+export interface G9SyncHostHooks {
+    /** Called when a run starts executing; the returned scope's `dispose` runs when it ends. */
+    beginRun(run: G9SyncRun, signal: AbortSignal): Promise<{
+        dispose(): void | Promise<void>;
+    } | null>;
+    /** False skips automatic background runs. */
+    readonly isNetworkAvailable: boolean;
+}
+/** `G9CSyncHealth`. */
+export interface G9SyncHealth {
+    clientId: string;
+    isConnected: boolean;
+    isRunning: boolean;
+    queuedRuns: number;
+    serverEpoch: string | null;
+    lastHelloUtcMs: number | null;
+    pending: G9PendingSummary;
+    subscriptions: G9SyncSubscriptionRecord[];
+    recentRuns: G9SyncRunReport[];
+}
+/** `G9CRowsAppliedEventArgs`. */
+export interface G9RowsAppliedEvent {
+    report: G9ApplyReport;
+    source: G9ESyncPhase;
+    /** Set for a staged pull applied in slices (ADR-0053). */
+    slice: G9ApplySlice | null;
+}
+/** `G9CSyncErrors.Normalize`: every failure becomes a G9SyncException with a stable code. */
+export declare function normalizeError(error: unknown): G9SyncException;
+/** `G9CSyncErrors.IsTransient`. */
+export declare function isTransientError(error: unknown): boolean;