@classytic/repo-core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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)
+
+Every optional prop on `TenantConfig` (`strategy`, `enabled`, `tenantField`,
+`fieldType`, `ref`, `contextKey`, `required`, `resolve`) is now typed
+`T | undefined`, so downstream packages compiling with
+`exactOptionalPropertyTypes: true` can extend it without redeclaring props
+(unblocks `@classytic/ledger`'s `MultiTenantConfig.required` exception).
+
+`resolveTenantConfig` strips explicit-`undefined` keys before spreading
+over `DEFAULT_TENANT_CONFIG`, so `{ required: maybeUndefined }` can never
+clobber a default with `undefined` — previously the un-widened type made
+that unrepresentable; now it's handled at runtime and pinned by tests.
+`DEFAULT_TENANT_CONFIG`'s annotation moved from `Required<Pick<...>>` to an
+`Exclude<..., undefined>` mapping (`-?` does not strip an explicit
+undefined union member). No runtime behavior change for existing callers.
+
 ## [0.6.0] - 2026-06-11
 
 Standardization release. Coordinated with mongokit 3.16 + sqlitekit 0.6.

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/dist/tenant/resolve.d.mts

@@ -10,18 +10,8 @@ import { ResolvedTenantConfig, TenantConfig } from "./types.mjs";
  * runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
  * type-level alignment without forcing a runtime default change.
  */
-declare const DEFAULT_TENANT_CONFIG: Required<Pick<TenantConfig, 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required'>>;
-/**
- * Resolve a possibly-partial {@link TenantConfig} against the defaults.
- *
- * - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
- * - `true` / `undefined` → default field strategy.
- * - Object with `strategy: 'custom'` → `resolve` is required; throws
- *   otherwise so the misconfiguration surfaces at boot, not runtime.
- * - Object with `strategy: 'none'` → `enabled: false` (preserves
- *   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
- *   stays correctly typed even with scoping off).
- */
+type TenantDefaults = { [K in 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required']-?: Exclude<TenantConfig[K], undefined> };
+declare const DEFAULT_TENANT_CONFIG: TenantDefaults;
 declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
 //#endregion
 export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };

package/dist/tenant/resolve.mjs

@@ -1,13 +1,4 @@
 //#region src/tenant/resolve.ts
-/**
-* Sensible defaults for a freshly-built package (field strategy).
-*
-* `fieldType: 'objectId'` is the recommended default for new Mongo-shaped
-* kits because it enables `$lookup` / `.populate()`. Existing kits that
-* historically defaulted to `'string'` (mongokit pre-3.x) keep their own
-* runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
-* type-level alignment without forcing a runtime default change.
-*/
 const DEFAULT_TENANT_CONFIG = {
 	strategy: "field",
 	enabled: true,
@@ -17,17 +8,11 @@ const DEFAULT_TENANT_CONFIG = {
 	contextKey: "organizationId",
 	required: true
 };
-/**
-* Resolve a possibly-partial {@link TenantConfig} against the defaults.
-*
-* - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
-* - `true` / `undefined` → default field strategy.
-* - Object with `strategy: 'custom'` → `resolve` is required; throws
-*   otherwise so the misconfiguration surfaces at boot, not runtime.
-* - Object with `strategy: 'none'` → `enabled: false` (preserves
-*   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
-*   stays correctly typed even with scoping off).
-*/
+function stripUndefined(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
+	return out;
+}
 function resolveTenantConfig(config) {
 	if (config === false) return {
 		...DEFAULT_TENANT_CONFIG,
@@ -36,33 +21,34 @@ function resolveTenantConfig(config) {
 		required: false
 	};
 	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
-	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
-	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
+	const cleaned = stripUndefined(config);
+	const strategy = cleaned.strategy ?? (cleaned.enabled === false ? "none" : "field");
+	const contextKey = cleaned.contextKey ?? cleaned.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
 	if (strategy === "none") return {
 		...DEFAULT_TENANT_CONFIG,
-		...config,
+		...cleaned,
 		contextKey,
 		strategy: "none",
 		enabled: false,
 		required: false
 	};
 	if (strategy === "custom") {
-		if (typeof config.resolve !== "function") throw new Error("[repo-core] TenantConfig.strategy 'custom' requires a 'resolve' function");
+		if (typeof cleaned.resolve !== "function") throw new Error("[repo-core] TenantConfig.strategy 'custom' requires a 'resolve' function");
 		return {
 			...DEFAULT_TENANT_CONFIG,
-			...config,
+			...cleaned,
 			contextKey,
 			strategy: "custom",
-			enabled: config.enabled ?? true,
-			resolve: config.resolve
+			enabled: cleaned.enabled ?? true,
+			resolve: cleaned.resolve
 		};
 	}
 	return {
 		...DEFAULT_TENANT_CONFIG,
-		...config,
+		...cleaned,
 		contextKey,
 		strategy: "field",
-		enabled: config.enabled ?? true
+		enabled: cleaned.enabled ?? true
 	};
 }
 //#endregion

package/dist/tenant/types.d.mts

@@ -50,7 +50,7 @@ interface TenantConfig {
    *
    * @default 'field'
    */
-  strategy?: TenantStrategy;
+  strategy?: TenantStrategy | undefined;
   /**
    * Whether tenant scoping is active. When `false`, the package runs in
    * single-tenant mode — no filter injection, no tenant field on documents.
@@ -58,27 +58,27 @@ interface TenantConfig {
    *
    * @default true
    */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /**
    * Document / column field name that stores the tenant id. Used when
    * `strategy === 'field'`.
    *
    * @default 'organizationId'
    */
-  tenantField?: string;
+  tenantField?: string | undefined;
   /**
    * How to store / cast the tenant id.
    *
    * @default 'objectId'
    */
-  fieldType?: TenantFieldType;
+  fieldType?: TenantFieldType | undefined;
   /**
    * Mongoose ref for `'objectId'` types. Ignored by SQL kits and when
    * `fieldType === 'string'`.
    *
    * @default 'organization'
    */
-  ref?: string;
+  ref?: string | undefined;
   /**
    * Which key on the repository context to read the tenant id from.
    *
@@ -92,14 +92,14 @@ interface TenantConfig {
    *
    * @default tenantField ?? 'organizationId'
    */
-  contextKey?: string;
+  contextKey?: string | undefined;
   /**
    * Whether the field is required. When `false`, the package permits
    * unscoped / cross-tenant reads (typically only for admin paths).
    *
    * @default true
    */
-  required?: boolean;
+  required?: boolean | undefined;
   /**
    * Custom resolver — called when `strategy === 'custom'` to produce the
    * filter object injected into queries. Packages pass the request /
@@ -121,7 +121,7 @@ interface TenantConfig {
    * }
    * ```
    */
-  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown>;
+  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown> | undefined;
 }
 /**
  * Resolved shape returned by `resolveTenantConfig`. Always includes the
@@ -136,7 +136,7 @@ type ResolvedTenantConfig = {
   ref: string;
   contextKey: string;
   required: boolean;
-  resolve?: TenantConfig['resolve'];
+  resolve?: TenantConfig['resolve'] | undefined;
 };
 //#endregion
 export { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.6.0",
+  "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",