@classytic/repo-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,7 +4,39 @@ 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).
 
-## [Unreleased]
+## [0.2.0] - 2026-04-22
+
+### Added — Update IR (portable write-side primitive)
+
+- **New `@classytic/repo-core/update` subpath.** The write-side counterpart to `@classytic/repo-core/filter`. Plugins and arc's infrastructure stores compose an `UpdateSpec` once; each kit compiles it to its native shape.
+  - **Types:** `UpdateSpec` (tagged union on `op: 'update'`, four buckets: `set` / `unset` / `setOnInsert` / `inc`), `UpdateInput` (union of `UpdateSpec` | kit-native `Record<string, unknown>` | Mongo pipeline `Record<string, unknown>[]`).
+  - **Builders:** `update({ set, unset, setOnInsert, inc })` (root), `setFields`, `unsetFields(...f)`, `setOnInsertFields`, `incFields`, `combineUpdates(...specs)` (later-wins merge, `unset` de-duplicates).
+  - **Guards:** `isUpdateSpec` (routes portable IR to the compiler), `isUpdatePipeline` (lets SQL kits short-circuit with `UnsupportedOperationError`).
+  - **Compilers:** `compileUpdateSpecToMongo(spec)` emits `{ $set, $unset, $setOnInsert, $inc }`. `compileUpdateSpecToSql(spec)` emits a `SqlUpdatePlan` with `data` / `unset` / `inc` / `insertDefaults` buckets, leaving SQL generation (quoting, `ON CONFLICT`, parameter binding) to the kit.
+- **`StandardRepo.findOneAndUpdate` + `updateMany` widened to `UpdateInput`.** Accepts all three forms — portable `UpdateSpec`, kit-native record, Mongo aggregation pipeline. Kits dispatch with `isUpdateSpec`. The existing raw-record and pipeline paths remain unchanged; the IR is purely additive so consumers don't need to migrate. Arc's infrastructure stores (outbox, idempotency, audit) will switch to the IR over a subsequent release to close the "Mongo-shaped store" gap flagged in the April 2026 cross-surface review.
+
+**Motivation (Arc April 2026 review):** arc's `EventOutbox`, `IdempotencyStore`, and `AuditStore` adapters use Mongo operator records (`$set`, `$inc`, `$unset`, `$setOnInsert`, `$or`, `$lte`, ...) directly against `RepositoryLike.findOneAndUpdate`. That works on mongokit but fails on sqlitekit — whose `findOneAndUpdate` treats `data` as flat column overwrites and would literally set a column named `$set`. The Update IR closes the gap without forcing every kit to ship its own Mongo-operator compatibility layer.
+
+**Rationale for scope:** the IR covers the subset every backend supports (atomic set / unset / inc / insert-default). Kit-native features — Mongo `$push`/`$pull`/`$addToSet`, aggregation pipeline updates, Postgres `jsonb_set`, SQL `CASE` expressions — stay on the kit-native path via `UpdateInput`'s raw-record and pipeline forms. No lowest-common-denominator bloat; no feature loss for kits that already offer more.
+
+**Test delta**: 193 → 230 tests (37 new across `tests/unit/update/builders`, `/guard`, `/compile`).
+
+### Changed — breaking: `StandardRepo` write signatures
+
+`StandardRepo.findOneAndUpdate(filter, update, ...)` and `updateMany(filter, data, ...)` — the second parameter is now typed `UpdateInput` (was `Record<string, unknown> | Record<string, unknown>[]` and `Record<string, unknown>` respectively). Every call site that compiled against 0.1.0 keeps compiling: `Record<string, unknown>` and `Record<string, unknown>[]` are subtypes of `UpdateInput`. The break is on the **implementer** side — any kit that declared only the old parameter type no longer structurally satisfies `StandardRepo` under strict contravariance. mongokit 3.11.0 and sqlitekit 0.1.1 already ship with the widened signatures; third-party kits need to widen before bumping their `@classytic/repo-core` peer dep.
+
+### Changed — breaking: `updateMany` + `deleteMany` promoted to required members of `StandardRepo`
+
+Both methods were optional (`updateMany?` / `deleteMany?`) in 0.1.0; they're required in 0.2.0. Rationale: every real backend has a native bulk-update and bulk-delete primitive, and arc's infrastructure stores (outbox, idempotency, audit cleanup) assume both are callable without feature-detection. Leaving them optional invited the "forgot to wire `batchOperationsPlugin`" runtime `TypeError` footgun that earlier releases of mongokit shipped — with the promotion, the type system catches missing implementations at the kit boundary.
+
+**Impact**:
+- **Kits**: any kit declaring `class FooRepo<T> implements StandardRepo<T>` must provide `updateMany` and `deleteMany` or fail to compile. mongokit 3.11.0 and sqlitekit 0.1.1 both ship these as class primitives, so their conformance stays green.
+- **Consumers of `RepositoryLike<T> = MinimalRepo<T> & Partial<StandardRepo<T>>`** (arc's pattern) are unaffected — `Partial` reimposes optionality for feature detection at the arc adapter boundary. `if (repo.updateMany)` guards keep working.
+- `bulkWrite` stays optional — the mongoose-shaped `BulkWriteOperation` has no clean SQL analogue, and every kit would ship an uninteresting fan-out wrapper otherwise.
+
+### Naming — `UpdateInput` collision with mongokit
+
+`@classytic/repo-core/update` exports `UpdateInput` as the union `UpdateSpec | Record<string, unknown> | Record<string, unknown>[]`. `@classytic/mongokit` currently **also** exports a type named `UpdateInput<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>` — a completely different, document-typed shape used by `repo.update(id, data)`. If you write `import { UpdateInput } from '@classytic/mongokit'`, you get mongokit's generic; if you write `import type { UpdateInput } from '@classytic/repo-core/update'`, you get the union. Both names may appear in the same consumer file — import at least one with an alias (`import type { UpdateInput as UpdatePatch } from '@classytic/mongokit'`). mongokit will rename its local type in a follow-up release to close the collision permanently.
 
 ### Added
 - Phase 0 scaffold: package.json, tsconfig, tsdown, biome, vitest (4-tier), knip

package/dist/repository/index.d.mts

@@ -1,5 +1,6 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
+import { UpdateInput } from "../update/types.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
-import { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
-export { type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type BulkWriteOperation, type BulkWriteResult, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FindOneAndUpdateOptions, type InferDoc, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type StandardRepo, type UpdateManyResult, type WriteOptions, validatePluginOrder };
+import { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
+export { type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type BulkWriteOperation, type BulkWriteResult, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, type FindOneAndUpdateOptions, type InferDoc, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type StandardRepo, type UpdateInput, type UpdateManyResult, type WriteOptions, validatePluginOrder };

package/dist/repository/types.d.mts

@@ -1,6 +1,7 @@
 import { Filter } from "../filter/types.mjs";
 import { OffsetPaginationResult } from "../pagination/types.mjs";
 import { LookupPopulateOptions, LookupPopulateResult } from "../lookup/types.mjs";
+import { UpdateInput } from "../update/types.mjs";
 
 //#region src/repository/types.d.ts
 /**
@@ -286,7 +287,17 @@ interface AggResult<TRow extends AggRow = AggRow> {
  * - **Raw** — neither; kit returns all matching docs (may be large).
  */
 interface PaginationParams<TDoc = unknown> {
-  filters?: Partial<TDoc> & Record<string, unknown>;
+  /**
+   * Predicate narrowing the rows that feed into the list query. Accepts
+   * the portable Filter IR (`and(eq(...), gt(...))`) OR a flat kit-native
+   * record (`{ status: 'active', age: { $gt: 18 } }`). Every kit's
+   * `getAll` compiler handles both forms.
+   *
+   * The `Partial<TDoc>` intersection preserves the old "typed flat record"
+   * DX for callers that pass a POJO — they still get autocomplete on
+   * known document fields while the union branch allows the Filter IR.
+   */
+  filters?: (Partial<TDoc> & Record<string, unknown>) | Filter;
   sort?: string | Record<string, 1 | -1>;
   page?: number;
   limit?: number;
@@ -373,8 +384,26 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * Required for arc's outbox, distributed-lock, and workflow-semaphore
    * patterns. Kits without atomic CAS should simulate it inside a
    * transaction — arc's stores assume single-round-trip semantics.
+   *
+   * **Update argument forms** (see {@link UpdateInput}):
+   *
+   *   1. `UpdateSpec` — portable IR built via `update({ set, unset, inc,
+   *      setOnInsert })`. Every kit compiles this to its native shape.
+   *      **Prefer this for portable code** (arc's infrastructure stores,
+   *      plugins targeting multiple backends).
+   *   2. `Record<string, unknown>` — kit-native raw record. mongokit
+   *      treats this as a Mongo operator document (`$set`, `$inc`,
+   *      `$unset`, ...). SQL kits treat it as flat column overwrites. Use
+   *      for kit-specific fast paths.
+   *   3. `Record<string, unknown>[]` — Mongo aggregation pipeline. Only
+   *      mongokit executes this; SQL kits throw `UnsupportedOperationError`.
+   *      Use for the rare cases where you need `$ifNull` / `$cond` /
+   *      `$toLower` to preserve invariants atomically (e.g. outbox's
+   *      `firstFailedAt`).
+   *
+   * Kits dispatch via `isUpdateSpec(update)` from `@classytic/repo-core/update`.
    */
-  findOneAndUpdate?(filter: FilterInput, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
+  findOneAndUpdate?(filter: FilterInput, update: UpdateInput, options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
   /**
    * Classify an error from a write as a unique-constraint violation.
    * Arc's idempotency + outbox adapters need this to distinguish
@@ -397,14 +426,38 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   findAll?(filter?: FilterInput, options?: QueryOptions): Promise<TDoc[]>;
   getOrCreate?(filter: FilterInput, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
   createMany?(items: Partial<TDoc>[], options?: WriteOptions): Promise<TDoc[]>;
-  updateMany?(filter: FilterInput, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
-  deleteMany?(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
   /**
-   * Heterogeneous bulk write. Kits dispatch each op against the
-   * appropriate driver primitive inside a single transaction; see each
-   * kit's docs for the exact semantics of `upsert` and operator-shaped
-   * update values (mongokit honors `$set` etc., SQL kits treat `update`
-   * as a flat column overwrite).
+   * Apply the same update to every matching document. Required — every
+   * `StandardRepo` kit must implement bulk update; arc's outbox,
+   * idempotency, and cleanup stores depend on it. `data` accepts the
+   * same three forms as {@link findOneAndUpdate}: portable `UpdateSpec`,
+   * kit-native raw record, or Mongo aggregation pipeline (mongokit-only).
+   *
+   * **Promoted from optional to required in repo-core 0.2.0** — sqlitekit
+   * and mongokit both ship this as a class primitive. Third-party kits
+   * that previously omitted it now need to implement. Kits that lack a
+   * native bulk-update primitive should fan out in a transaction.
+   */
+  updateMany(filter: FilterInput, data: UpdateInput, options?: WriteOptions): Promise<UpdateManyResult>;
+  /**
+   * Delete every document matching the filter. Required — symmetrically
+   * with `updateMany`. Pass `{ mode: 'hard' }` to bypass soft-delete
+   * interception; kits without soft-delete accept and ignore the flag.
+   *
+   * **Promoted from optional to required in repo-core 0.2.0.**
+   */
+  deleteMany(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
+  /**
+   * Heterogeneous bulk write. Stays optional — kits dispatch each op
+   * against the appropriate driver primitive inside a single transaction;
+   * see each kit's docs for the exact semantics of `upsert` and
+   * operator-shaped update values (mongokit honors `$set` etc., SQL kits
+   * treat `update` as a flat column overwrite).
+   *
+   * Kept optional because the mongoose-shaped `BulkWriteOperation` has no
+   * clean SQL analogue beyond "loop and dispatch" — forcing every kit to
+   * implement it would push kits to ship a thin wrapper around updateMany
+   * / deleteMany that offers nothing over calling them directly.
    */
   bulkWrite?(operations: readonly BulkWriteOperation<TDoc>[]): Promise<BulkWriteResult>;
   /**
@@ -467,4 +520,4 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
 }
 //#endregion
-export { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };

package/dist/update/builders.d.mts

@@ -0,0 +1,52 @@
+import { UpdateSpec } from "./types.mjs";
+
+//#region src/update/builders.d.ts
+/**
+ * Compose an `UpdateSpec` from the four primitive mutations.
+ *
+ * ```ts
+ * update({
+ *   set:          { status: 'pending', visibleAt: new Date() },
+ *   unset:        ['leaseOwner'],
+ *   setOnInsert:  { createdAt: new Date() },
+ *   inc:          { attempts: 1 },
+ * });
+ * ```
+ *
+ * Keys with `undefined` values in `set` / `setOnInsert` are dropped — a
+ * common gotcha when spreading optional fields. To actually clear a field,
+ * use `unset` instead (matches mongokit's `$set: { x: undefined }` / `$unset`
+ * distinction).
+ *
+ * Throws if every mutation bucket is empty — an update with nothing to
+ * do is always a caller bug.
+ */
+declare function update(spec: {
+  set?: Record<string, unknown>;
+  unset?: readonly string[];
+  setOnInsert?: Record<string, unknown>;
+  inc?: Record<string, number>;
+}): UpdateSpec;
+/** Sugar: `update({ set: fields })`. Most updates are simple assignments. */
+declare function setFields(fields: Record<string, unknown>): UpdateSpec;
+/** Sugar: `update({ unset: fields })`. */
+declare function unsetFields(...fields: string[]): UpdateSpec;
+/** Sugar: `update({ inc: deltas })`. Each key's value is the delta (positive or negative). */
+declare function incFields(deltas: Record<string, number>): UpdateSpec;
+/** Sugar: `update({ setOnInsert: fields })`. Pairs with an upsert. */
+declare function setOnInsertFields(fields: Record<string, unknown>): UpdateSpec;
+/**
+ * Merge multiple `UpdateSpec` values into one.
+ *
+ *   - `set` / `setOnInsert` / `inc`: shallow-merged, later entries win per
+ *     key. For `inc`, later-wins is usually a bug — callers who want to
+ *     stack deltas should pass `inc({ x: a + b })` directly.
+ *   - `unset`: concatenated + de-duplicated.
+ *
+ * Empty input returns an identity-style spec with `set: {}`, which
+ * `update()` would reject — so we throw here too. An empty combine is
+ * always a caller bug.
+ */
+declare function combineUpdates(...specs: readonly UpdateSpec[]): UpdateSpec;
+//#endregion
+export { combineUpdates, incFields, setFields, setOnInsertFields, unsetFields, update };

package/dist/update/builders.mjs

@@ -0,0 +1,92 @@
+//#region src/update/builders.ts
+/**
+* Compose an `UpdateSpec` from the four primitive mutations.
+*
+* ```ts
+* update({
+*   set:          { status: 'pending', visibleAt: new Date() },
+*   unset:        ['leaseOwner'],
+*   setOnInsert:  { createdAt: new Date() },
+*   inc:          { attempts: 1 },
+* });
+* ```
+*
+* Keys with `undefined` values in `set` / `setOnInsert` are dropped — a
+* common gotcha when spreading optional fields. To actually clear a field,
+* use `unset` instead (matches mongokit's `$set: { x: undefined }` / `$unset`
+* distinction).
+*
+* Throws if every mutation bucket is empty — an update with nothing to
+* do is always a caller bug.
+*/
+function update(spec) {
+	const set = stripUndefined(spec.set);
+	const setOnInsert = stripUndefined(spec.setOnInsert);
+	const inc = spec.inc ? Object.freeze({ ...spec.inc }) : void 0;
+	const unset = spec.unset && spec.unset.length > 0 ? Object.freeze([...spec.unset]) : void 0;
+	if (!(set && Object.keys(set).length > 0 || setOnInsert && Object.keys(setOnInsert).length > 0 || inc && Object.keys(inc).length > 0 || unset && unset.length > 0)) throw new Error("update(): spec is empty. At least one of `set`, `unset`, `setOnInsert`, or `inc` must be populated.");
+	const node = {
+		op: "update",
+		...set && { set },
+		...unset && { unset },
+		...setOnInsert && { setOnInsert },
+		...inc && { inc }
+	};
+	return Object.freeze(node);
+}
+/** Sugar: `update({ set: fields })`. Most updates are simple assignments. */
+function setFields(fields) {
+	return update({ set: fields });
+}
+/** Sugar: `update({ unset: fields })`. */
+function unsetFields(...fields) {
+	return update({ unset: fields });
+}
+/** Sugar: `update({ inc: deltas })`. Each key's value is the delta (positive or negative). */
+function incFields(deltas) {
+	return update({ inc: deltas });
+}
+/** Sugar: `update({ setOnInsert: fields })`. Pairs with an upsert. */
+function setOnInsertFields(fields) {
+	return update({ setOnInsert: fields });
+}
+/**
+* Merge multiple `UpdateSpec` values into one.
+*
+*   - `set` / `setOnInsert` / `inc`: shallow-merged, later entries win per
+*     key. For `inc`, later-wins is usually a bug — callers who want to
+*     stack deltas should pass `inc({ x: a + b })` directly.
+*   - `unset`: concatenated + de-duplicated.
+*
+* Empty input returns an identity-style spec with `set: {}`, which
+* `update()` would reject — so we throw here too. An empty combine is
+* always a caller bug.
+*/
+function combineUpdates(...specs) {
+	if (specs.length === 0) throw new Error("combineUpdates(): at least one spec required.");
+	if (specs.length === 1) return specs[0];
+	const set = {};
+	const setOnInsert = {};
+	const inc = {};
+	const unsetSet = /* @__PURE__ */ new Set();
+	for (const s of specs) {
+		if (s.set) Object.assign(set, s.set);
+		if (s.setOnInsert) Object.assign(setOnInsert, s.setOnInsert);
+		if (s.inc) Object.assign(inc, s.inc);
+		if (s.unset) for (const f of s.unset) unsetSet.add(f);
+	}
+	return update({
+		...Object.keys(set).length > 0 && { set },
+		...Object.keys(setOnInsert).length > 0 && { setOnInsert },
+		...Object.keys(inc).length > 0 && { inc },
+		...unsetSet.size > 0 && { unset: Array.from(unsetSet) }
+	});
+}
+function stripUndefined(record) {
+	if (!record) return void 0;
+	const out = {};
+	for (const [k, v] of Object.entries(record)) if (v !== void 0) out[k] = v;
+	return Object.keys(out).length > 0 ? Object.freeze(out) : void 0;
+}
+//#endregion
+export { combineUpdates, incFields, setFields, setOnInsertFields, unsetFields, update };

package/dist/update/compile.d.mts

@@ -0,0 +1,46 @@
+import { UpdateSpec } from "./types.mjs";
+
+//#region src/update/compile.d.ts
+/**
+ * Compile an `UpdateSpec` to a Mongo operator record.
+ *
+ * Empty buckets are omitted — passing `{ $set: {} }` to Mongo is a no-op
+ * per-op but still round-trips through the driver as a valid update, so
+ * leaving them out keeps the wire format tidy.
+ *
+ * `$unset` values follow the Mongo convention (empty string) — the value
+ * is ignored by the server, only the key matters.
+ */
+declare function compileUpdateSpecToMongo(spec: UpdateSpec): Record<string, unknown>;
+/**
+ * Compile an `UpdateSpec` to a SQL-friendly breakdown.
+ *
+ * SQL kits can't express a single "update record" the way Mongo can — they
+ * need:
+ *
+ *   - `data` for plain `SET col = ?` assignments (both `set` and
+ *     `setOnInsert` feed here; the kit decides how to route `setOnInsert`
+ *     when the UPDATE path hits a matched row vs inserted row).
+ *   - `unset` for `SET col = NULL` clauses.
+ *   - `inc` for `SET col = coalesce(col, 0) + ?` clauses.
+ *   - `insertDefaults` for the INSERT branch of an upsert — fields that
+ *     should ONLY apply when no row matched.
+ *
+ * Callers build the final SQL from these pieces. This helper intentionally
+ * doesn't emit SQL strings — driver quoting, parameter binding, and
+ * `ON CONFLICT` grammar differ too much between SQLite, Postgres, and
+ * Prisma for a shared compiler to own it.
+ */
+interface SqlUpdatePlan {
+  /** Plain column assignments. Merge of `set` — applied on UPDATE and INSERT. */
+  readonly data: Readonly<Record<string, unknown>>;
+  /** Columns to set NULL. */
+  readonly unset: readonly string[];
+  /** Atomic numeric deltas — kit emits `col = coalesce(col, 0) + ?`. */
+  readonly inc: Readonly<Record<string, number>>;
+  /** Fields to set only when the upsert takes the INSERT branch. */
+  readonly insertDefaults: Readonly<Record<string, unknown>>;
+}
+declare function compileUpdateSpecToSql(spec: UpdateSpec): SqlUpdatePlan;
+//#endregion
+export { SqlUpdatePlan, compileUpdateSpecToMongo, compileUpdateSpecToSql };

package/dist/update/compile.mjs

@@ -0,0 +1,33 @@
+//#region src/update/compile.ts
+/**
+* Compile an `UpdateSpec` to a Mongo operator record.
+*
+* Empty buckets are omitted — passing `{ $set: {} }` to Mongo is a no-op
+* per-op but still round-trips through the driver as a valid update, so
+* leaving them out keeps the wire format tidy.
+*
+* `$unset` values follow the Mongo convention (empty string) — the value
+* is ignored by the server, only the key matters.
+*/
+function compileUpdateSpecToMongo(spec) {
+	const out = {};
+	if (spec.set && Object.keys(spec.set).length > 0) out["$set"] = { ...spec.set };
+	if (spec.unset && spec.unset.length > 0) {
+		const unsetRecord = {};
+		for (const field of spec.unset) unsetRecord[field] = "";
+		out["$unset"] = unsetRecord;
+	}
+	if (spec.setOnInsert && Object.keys(spec.setOnInsert).length > 0) out["$setOnInsert"] = { ...spec.setOnInsert };
+	if (spec.inc && Object.keys(spec.inc).length > 0) out["$inc"] = { ...spec.inc };
+	return out;
+}
+function compileUpdateSpecToSql(spec) {
+	return Object.freeze({
+		data: Object.freeze({ ...spec.set ?? {} }),
+		unset: Object.freeze([...spec.unset ?? []]),
+		inc: Object.freeze({ ...spec.inc ?? {} }),
+		insertDefaults: Object.freeze({ ...spec.setOnInsert ?? {} })
+	});
+}
+//#endregion
+export { compileUpdateSpecToMongo, compileUpdateSpecToSql };

package/dist/update/guard.d.mts

@@ -0,0 +1,20 @@
+import { UpdateSpec } from "./types.mjs";
+
+//#region src/update/guard.d.ts
+/**
+ * True when `value` is an `UpdateSpec` — i.e. the portable, compile-to-native
+ * form.
+ *
+ * Fast structural gate: checks the discriminant tag. Deeper validation (no
+ * `$`-prefixed keys inside `set`, `inc` values are numbers, ...) is left
+ * to the compiler; that's where kit-specific constraints live.
+ */
+declare function isUpdateSpec(value: unknown): value is UpdateSpec;
+/**
+ * True when `value` is a Mongo aggregation pipeline (`findOneAndUpdate`'s
+ * array form). Kits use this to short-circuit SQL paths that can't execute
+ * pipelines.
+ */
+declare function isUpdatePipeline(value: unknown): value is Record<string, unknown>[];
+//#endregion
+export { isUpdatePipeline, isUpdateSpec };

package/dist/update/guard.mjs

@@ -0,0 +1,24 @@
+//#region src/update/guard.ts
+/**
+* True when `value` is an `UpdateSpec` — i.e. the portable, compile-to-native
+* form.
+*
+* Fast structural gate: checks the discriminant tag. Deeper validation (no
+* `$`-prefixed keys inside `set`, `inc` values are numbers, ...) is left
+* to the compiler; that's where kit-specific constraints live.
+*/
+function isUpdateSpec(value) {
+	if (!value || typeof value !== "object") return false;
+	if (Array.isArray(value)) return false;
+	return value.op === "update";
+}
+/**
+* True when `value` is a Mongo aggregation pipeline (`findOneAndUpdate`'s
+* array form). Kits use this to short-circuit SQL paths that can't execute
+* pipelines.
+*/
+function isUpdatePipeline(value) {
+	return Array.isArray(value);
+}
+//#endregion
+export { isUpdatePipeline, isUpdateSpec };

package/dist/update/index.d.mts

@@ -0,0 +1,5 @@
+import { UpdateInput, UpdateSpec } from "./types.mjs";
+import { combineUpdates, incFields, setFields, setOnInsertFields, unsetFields, update } from "./builders.mjs";
+import { SqlUpdatePlan, compileUpdateSpecToMongo, compileUpdateSpecToSql } from "./compile.mjs";
+import { isUpdatePipeline, isUpdateSpec } from "./guard.mjs";
+export { type SqlUpdatePlan, type UpdateInput, type UpdateSpec, combineUpdates, compileUpdateSpecToMongo, compileUpdateSpecToSql, incFields, isUpdatePipeline, isUpdateSpec, setFields, setOnInsertFields, unsetFields, update };

package/dist/update/index.mjs

@@ -0,0 +1,4 @@
+import { combineUpdates, incFields, setFields, setOnInsertFields, unsetFields, update } from "./builders.mjs";
+import { compileUpdateSpecToMongo, compileUpdateSpecToSql } from "./compile.mjs";
+import { isUpdatePipeline, isUpdateSpec } from "./guard.mjs";
+export { combineUpdates, compileUpdateSpecToMongo, compileUpdateSpecToSql, incFields, isUpdatePipeline, isUpdateSpec, setFields, setOnInsertFields, unsetFields, update };

package/dist/update/types.d.mts

@@ -0,0 +1,62 @@
+//#region src/update/types.d.ts
+/**
+ * Update IR — driver-agnostic mutation spec.
+ *
+ * An `UpdateSpec` is a structured description of an atomic update that every
+ * kit compiles to its native shape — mongokit emits `$set`/`$unset`/`$inc`/
+ * `$setOnInsert` records, SQL kits emit column assignments + `NULL` columns
+ * + `column = coalesce(column, 0) + delta`, Prisma emits the equivalent
+ * `update` arg.
+ *
+ * The IR covers the subset every backend supports:
+ *
+ *   - **set**          — assign field values (mongokit `$set`, SQL column = ?)
+ *   - **unset**        — clear fields (mongokit `$unset`, SQL column = NULL)
+ *   - **setOnInsert**  — only on upsert insert (mongokit `$setOnInsert`, SQL INSERT default)
+ *   - **inc**          — atomic numeric delta (mongokit `$inc`, SQL col = col + ?)
+ *
+ * Kit-native update features (Mongo `$push`/`$pull`/`$addToSet`, aggregation
+ * pipeline updates, Postgres `jsonb_set`, SQL CASE expressions) stay
+ * kit-native. Pass a raw Mongo operator record or pipeline array when you
+ * need them — the `UpdateInput` union accepts both.
+ *
+ * **Compat invariant:** mongokit's existing Mongo-operator records (`$set`,
+ * `$unset`, ...) are NOT `UpdateSpec` values. Kits route by the `op:
+ * 'update'` tag via `isUpdateSpec`, treating raw records as pre-compiled
+ * and passing them to the driver unchanged.
+ */
+/**
+ * Portable update spec — the tagged-union root every kit compiles.
+ *
+ * At least one of `set` / `unset` / `setOnInsert` / `inc` must be populated.
+ * An empty spec is a wiring bug (nothing to update); kits MAY treat it as
+ * a no-op or throw.
+ */
+interface UpdateSpec {
+  readonly op: 'update';
+  /** Fields to assign. Overrides existing values. */
+  readonly set?: Readonly<Record<string, unknown>>;
+  /** Fields to clear. Mongo `$unset`, SQL `NULL`. */
+  readonly unset?: readonly string[];
+  /** Fields to set only when upsert creates a new row. Ignored otherwise. */
+  readonly setOnInsert?: Readonly<Record<string, unknown>>;
+  /** Atomic numeric deltas. Kits compile to `$inc` / `col = col + ?`. */
+  readonly inc?: Readonly<Record<string, number>>;
+}
+/**
+ * Accepted update argument across every write method. A kit's
+ * `findOneAndUpdate` / `updateMany` implementation accepts:
+ *
+ *   1. `UpdateSpec` — portable, kit-agnostic. Compiles to the native shape.
+ *   2. `Record<string, unknown>` — kit-native raw record (mongokit
+ *      `$`-operators, Prisma `update` input). Passed through unchanged.
+ *   3. `Record<string, unknown>[]` — Mongo aggregation pipeline. Mongo-only
+ *      kits execute it; SQL kits throw `UnsupportedOperationError`.
+ *
+ * Arc's stores (outbox, idempotency, audit) should prefer form (1). Forms
+ * (2) and (3) remain for kit-specific fast paths and the aggregation-update
+ * escape hatch (e.g. outbox's `$ifNull` to preserve `firstFailedAt`).
+ */
+type UpdateInput = UpdateSpec | Record<string, unknown> | Record<string, unknown>[];
+//#endregion
+export { UpdateInput, UpdateSpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.1.0",
+  "version": "0.2.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,
@@ -38,6 +38,10 @@
       "types": "./dist/filter/index.d.mts",
       "default": "./dist/filter/index.mjs"
     },
+    "./update": {
+      "types": "./dist/update/index.d.mts",
+      "default": "./dist/update/index.mjs"
+    },
     "./query-parser": {
       "types": "./dist/query-parser/index.d.mts",
       "default": "./dist/query-parser/index.mjs"