@classytic/repo-core 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-07-04
+
+### Added — `./sync` change-log / cursor contract
+
+Storage-agnostic data-sync spine for offline-first + incremental replication:
+`ChangeLogStore`, `ChangeEntry` (tombstone deletes), pull `ChangesPage`
+(opaque exclusive cursors, `hasMore` paging), Replicache-style `PushMutation`
+/ `PushVerdict` (idempotent client mutation ids, server-authoritative
+conflicts), `CursorExpiredError` (compaction horizon → full resync), and the
+`MemoryChangeLogStore` reference impl pinning the contract semantics.
+
+Synthesized from CouchDB `_changes` (tombstones/checkpoints), Drive/Graph
+delta APIs (opaque server-issued cursors), Mongo change-stream resume tokens,
+and Replicache push/pull. Contract only — kits (mongokit/prismakit/sqlitekit)
+implement capture + durable stores via repository plugins; arc re-exports the
+surface at `@classytic/arc/sync`; sync HTTP endpoints are an arc module.
+
 ## [0.6.1] - 2026-07-04
 
 ### Changed — `TenantConfig` optionals widened to `T | undefined` (P10)

package/dist/sync/index.d.mts

@@ -0,0 +1,131 @@
+//#region src/sync/index.d.ts
+/**
+ * Change-log / cursor contract — the data-sync spine for offline-first and
+ * incremental replication (`arc-sync`-style capability packages, POS offline,
+ * bulk delta export, cross-service read models).
+ *
+ * Synthesized from the proven protocols, taking the best of each:
+ *
+ *   - CouchDB `_changes`      → append-only feed, TOMBSTONES for deletes,
+ *                               client checkpoints
+ *   - Drive/Graph delta APIs  → OPAQUE server-issued cursors (`deltaLink` /
+ *                               `startPageToken`) — clients never parse them
+ *   - Mongo change streams    → resumable, ordered, per-scope feeds
+ *   - Replicache push/pull    → client mutation ids for idempotent PUSH,
+ *                               server-authoritative conflict verdicts
+ *
+ * CONTRACT ONLY — storage-agnostic (repo-core is the cross-kit contract home,
+ * like DataAdapter/EventTransport/IdempotencyStore). `MemoryChangeLogStore` is
+ * the reference impl. Durable stores + capture plugins live in the KITS
+ * (mongokit/prismakit/sqlitekit repository plugins); the HTTP surface
+ * (`/sync/pull`, `/sync/push`) is an arc module; arc re-exports this contract
+ * at `@classytic/arc/sync`. repo-core is source of truth.
+ *
+ * ## Required semantics (stores MUST honor)
+ *
+ * 1. **Cursors are opaque, totally ordered per store.** Clients echo them
+ *    verbatim. A cursor from one store/scope-set is meaningless elsewhere.
+ * 2. **`append` is ordered and atomic with the business write** when a
+ *    `session` is provided (same transaction — the outbox discipline).
+ * 3. **Deletes are tombstones**, never gaps. A client at cursor C must be able
+ *    to converge by applying every entry after C — including deletions.
+ * 4. **`since` is exclusive** of the given cursor and returns entries in
+ *    cursor order. `hasMore: true` means call again with the new cursor.
+ * 5. **Compaction (`prune`) may drop superseded intermediate versions but
+ *    NEVER the latest state or an un-consumed tombstone horizon** — a store
+ *    advertises its horizon so clients older than it do a full resync.
+ */
+/** What happened to a document. Field-level patches are deliberately out of
+ *  scope — version-checked upserts + server authority beat CRDT complexity
+ *  for ERP data (the Sheets/Replicache position, not the Figma one). */
+type ChangeOp = "upsert" | "delete";
+interface ChangeEntry<TDoc = unknown> {
+  /** Which logical collection/resource this change belongs to (e.g. `pos-order`). */
+  readonly scope: string;
+  /** Document identity within the scope. */
+  readonly docId: string;
+  readonly op: ChangeOp;
+  /**
+   * Monotonic per-document version — the optimistic-concurrency token.
+   * Conflict rule: a push carrying `baseVersion < current` is a conflict.
+   */
+  readonly version: number;
+  /** Full document snapshot for `upsert`; absent for `delete` (tombstone). */
+  readonly doc?: TDoc;
+  /** Tenant partition (organizationId) — sync feeds are tenant-scoped. */
+  readonly tenantId?: string;
+  /** Server clock at capture — informational; ORDERING comes from the cursor. */
+  readonly at: Date;
+  /** Opaque position of THIS entry in the feed (assigned by the store). */
+  readonly cursor: string;
+}
+interface ChangesSinceOptions {
+  /** Max entries to return. Stores should default sensibly (e.g. 500). */
+  readonly limit?: number;
+  /** Restrict to these scopes (a client syncs the resources it opted into). */
+  readonly scopes?: readonly string[];
+  /** Tenant partition — REQUIRED by multi-tenant stores. */
+  readonly tenantId?: string;
+}
+interface ChangesPage<TDoc = unknown> {
+  readonly changes: ReadonlyArray<ChangeEntry<TDoc>>;
+  /** Checkpoint AFTER applying this page — echo into the next `since`. */
+  readonly cursor: string;
+  /** True → more entries exist; pull again immediately. */
+  readonly hasMore: boolean;
+}
+interface PushMutation<TDoc = unknown> {
+  readonly scope: string;
+  readonly docId: string;
+  readonly op: ChangeOp;
+  /** Version the client last saw — the optimistic-concurrency precondition. */
+  readonly baseVersion?: number;
+  readonly doc?: TDoc;
+  /**
+   * Client-unique id (`<clientId>:<seq>`) — replays of the same id MUST be
+   * acknowledged as already-applied, never re-executed (at-least-once safe).
+   */
+  readonly mutationId: string;
+}
+type PushVerdictStatus = "applied" | "already_applied" | "conflict" | "rejected";
+interface PushVerdict<TDoc = unknown> {
+  readonly mutationId: string;
+  readonly status: PushVerdictStatus;
+  /** Authoritative post-push version (also on conflict: the WINNING version). */
+  readonly version?: number;
+  /** Authoritative doc on conflict so the client can rebase (server wins). */
+  readonly current?: TDoc;
+  readonly reason?: string;
+}
+interface ChangeLogAppendOptions {
+  /** DB session/transaction handle — append atomically with the business write. */
+  readonly session?: unknown;
+}
+interface ChangeLogStore<TDoc = unknown> {
+  /** Record a change. `cursor`/`at` are ASSIGNED by the store; callers pass the rest. */
+  append(entry: Omit<ChangeEntry<TDoc>, "cursor" | "at">, options?: ChangeLogAppendOptions): Promise<ChangeEntry<TDoc>>;
+  /** Entries strictly AFTER `cursor` (empty string = from the beginning). */
+  since(cursor: string, options?: ChangesSinceOptions): Promise<ChangesPage<TDoc>>;
+  /** The current head checkpoint — what a fresh client stores after a full load. */
+  latestCursor(options?: Pick<ChangesSinceOptions, "tenantId" | "scopes">): Promise<string>;
+  /**
+   * Compact entries older than `before`, keeping per-doc latest state.
+   * Returns the new HORIZON cursor: clients checkpointed before it must full-resync.
+   */
+  prune?(before: Date): Promise<string>;
+}
+/** Client checkpoint older than the store's compaction horizon → full resync. */
+declare class CursorExpiredError extends Error {
+  readonly cursor: string;
+  readonly horizon: string;
+  constructor(cursor: string, horizon: string);
+}
+declare class MemoryChangeLogStore<TDoc = unknown> implements ChangeLogStore<TDoc> {
+  private entries;
+  private seq;
+  append(entry: Omit<ChangeEntry<TDoc>, "cursor" | "at">, _options?: ChangeLogAppendOptions): Promise<ChangeEntry<TDoc>>;
+  since(cursor: string, options?: ChangesSinceOptions): Promise<ChangesPage<TDoc>>;
+  latestCursor(): Promise<string>;
+}
+//#endregion
+export { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangeOp, ChangesPage, ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, PushMutation, PushVerdict, PushVerdictStatus };

package/dist/sync/index.mjs

@@ -0,0 +1,41 @@
+//#region src/sync/index.ts
+/** Client checkpoint older than the store's compaction horizon → full resync. */
+var CursorExpiredError = class extends Error {
+	constructor(cursor, horizon) {
+		super(`[repo-core:sync] cursor "${cursor}" predates the compaction horizon — full resync required.`);
+		this.cursor = cursor;
+		this.horizon = horizon;
+		this.name = "CursorExpiredError";
+	}
+};
+var MemoryChangeLogStore = class {
+	entries = [];
+	seq = 0;
+	async append(entry, _options) {
+		const cursor = String(++this.seq).padStart(16, "0");
+		const full = {
+			...entry,
+			cursor,
+			at: /* @__PURE__ */ new Date()
+		};
+		this.entries.push(full);
+		return full;
+	}
+	async since(cursor, options = {}) {
+		const { limit = 500, scopes, tenantId } = options;
+		const filtered = this.entries.filter((e) => e.cursor > cursor && (!scopes || scopes.includes(e.scope)) && (tenantId === void 0 || e.tenantId === tenantId));
+		const page = filtered.slice(0, limit);
+		const last = page[page.length - 1];
+		return {
+			changes: page,
+			cursor: last ? last.cursor : cursor,
+			hasMore: filtered.length > page.length
+		};
+	}
+	async latestCursor() {
+		const last = this.entries[this.entries.length - 1];
+		return last ? last.cursor : "";
+	}
+};
+//#endregion
+export { CursorExpiredError, MemoryChangeLogStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,
@@ -94,7 +94,11 @@
       "types": "./dist/lock/index.d.mts",
       "default": "./dist/lock/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./sync": {
+      "types": "./dist/sync/index.d.mts",
+      "default": "./dist/sync/index.mjs"
+    }
   },
   "keywords": [
     "repository",