cursedbelt 2.6.0 → 2.7.0

package/src/server/sync/types.ts

@@ -0,0 +1,108 @@
+/**
+ * The wire and store types every consumer of this sync engine shares. The op
+ * envelope is the notes shape — `(origin, originSeq)` gives exactly-once application
+ * with no coordination — and the report is vault's cursor discipline (the reader may
+ * advance exactly to `cursor`, never further) merged with notes' `seen` (a duplicate
+ * is not an error, it is proof the dedupe ledger works).
+ *
+ * ── 🔴 "sync-kit" is a PAST NAME. The engine is `cursedbelt/sync` ────────────
+ * The retired generation published this as `@satellites/sync-kit`. It came across
+ * whole into `apps/vault/src/kit/sync/` when that app graduated, and came here —
+ * `cursedbelt/sync` — on 2026-09-15, before `apps/station` could graduate and fork
+ * it a second time. That is the move this header used to call an open question in
+ * `tasks/`; it is done, and the app-local copies are what is temporary now.
+ *
+ * `@satellites/sync-kit` is NOT installable and never was — it was never published
+ * to npm — and its design plan (`plans/01-sync-kit-adoption-design.md`) belonged to
+ * the retired monorepo and did not come across. Comments in consuming apps still say
+ * "the sync-kit adoption": that is the NAME OF AN EVENT, the 2026-08 change that
+ * moved vault from its own `oplog` table onto this engine's `sync_ops`, and it is
+ * worth keeping because the dual-compat code only makes sense in its light.
+ */
+
+/** One durable mutation in the shared op log. `payload` is app-defined per `kind`. */
+export interface SyncOp {
+	/** This instance's monotonic sequence for the op (assigned by the local log). */
+	seq: number;
+	/** The instance id that BORN the op (stable per instance, never per device). */
+	origin: string;
+	/** The origin's own monotonic counter — `(origin, originSeq)` is the identity. */
+	originSeq: number;
+	/** Wall-clock ms when the op was born. LWW inputs, display, nothing structural. */
+	ts: number;
+	/** App-defined kind, e.g. `doc.set`. The version-negotiation unit. */
+	kind: string;
+	payload: unknown;
+}
+
+/** What applying one batch did. `cursor` is the last seq FULLY applied — a stopped
+ *  batch leaves it just before the failure so the next run resumes there. */
+export interface ApplyReport {
+	/** Ops that changed local state. */
+	applied: number;
+	/** Ops already held (dedupe hit) — counted, never re-applied. */
+	seen: number;
+	/** Concurrent edits reconciled (however the app's applier chose to). */
+	conflicts: number;
+	cursor: number;
+	/** Non-null when the batch stopped early (version skew, deferred ordering…). */
+	error: string | null;
+}
+
+/** The peer info handshake. `opKinds` is the compatibility advertisement — a dialer
+ *  stops BEFORE the first op a peer cannot take (notes' version-skew lesson: sending
+ *  it wedges the push with an error that reads like corruption). */
+export interface PeerInfo {
+	instanceId: string;
+	head: number;
+	opKinds: string[];
+}
+
+/** The transport seam. Pure interface so tests drive the engine against a REAL second
+ *  store mounted in a Hono app — no HTTP mocks (the notes/vault discipline). */
+export interface RemoteApi {
+	info(): Promise<PeerInfo>;
+	pull(
+		after: number,
+		excludeOrigin: string,
+	): Promise<{ ops: SyncOp[]; cursor: number; head: number }>;
+	push(payload: { ops: SyncOp[]; peerHas: number }): Promise<ApplyReport>;
+	/** The receiver's "someone pressed Sync now here" stamp; null when unsupported. */
+	requestedAt?(): Promise<number | null>;
+}
+
+/** Context the applier gets per batch — vault's concurrency bound. */
+export interface ApplyContext {
+	/** The peer's stable instance id. */
+	peerId: string;
+	/** Max LOCAL-born seq the peer already holds of OURS — an entity whose newest
+	 *  local op is beyond this AND diverges is a true concurrent edit. */
+	peerReceivedUpTo: number;
+}
+
+/** The app's merge logic for ONE op that passed the dedupe ledger. Return value:
+ *  - `"applied"`   — state changed
+ *  - `"ignored"`   — stale/no-op (still recorded in the ledger, cursor advances)
+ *  - `"conflict"`  — applied with a materialized conflict artifact
+ *  Throw {@link StopBatch} to stop BEFORE this op (cursor stays short of it). */
+export type ApplyOne = (op: SyncOp, ctx: ApplyContext) => "applied" | "ignored" | "conflict";
+
+/** Stop the current batch before the offending op — deferred ordering, a payload this
+ *  build cannot hold yet, anything where "retry after the world changes" is right. */
+export class StopBatch extends Error {
+	constructor(reason: string) {
+		super(reason);
+		this.name = "StopBatch";
+	}
+}
+
+export interface SyncSummary {
+	remoteId: string;
+	pushed: number;
+	pulled: number;
+	conflicts: number;
+	/** Ops the export policy held back (counted, never sent). */
+	held: number;
+	/** Set when the remote runs an older schema and cannot take what comes next. */
+	blockedBy?: string;
+}