anchordb 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to the `anchordb` packages.
+
+This project follows [semantic versioning](https://semver.org/). While the version is `0.x`, minor
+releases may contain breaking changes.
+
+## 0.1.0 — unreleased
+
+First release. Five packages, published together.
+
+### `anchordb`
+
+- **Local-first database** with a Mongoose-shaped API. No `sync` block means a purely local
+  database: no mutation queue, no network code, no sync metadata, hard deletes.
+- **Mongoose parity**: `Schema`, `model()`, documents with `.save()`/`.isModified()`, virtuals,
+  methods, statics, `pre`/`post` hooks, `ValidationError`/`CastError` shapes, and `code: 11000`.
+- **Decorators** (`anchordb/decorators`) matching `@nestjs/mongoose` — `@Schema`, `@Prop`,
+  `SchemaFactory`, `raw()` — so one decorated class can be shared with a NestJS backend.
+  Metadata is optional: explicit `@Prop(String)` works with `emitDecoratorMetadata` off.
+- **Real MongoDB ObjectId**, generated on-device, cross-validated byte-for-byte against `bson`.
+- **Indexes** — single, compound, multikey, `unique`, `sparse`, `partialFilterExpression`, TTL —
+  with unique violations enforced at the storage layer and reported as `E11000`.
+- **Lazy chainable query builder**: `.populate().sort().skip().limit().select().exec()`, thenable,
+  async-iterable, with `explain()`.
+- **Aggregation pipeline** with streaming execution, index pushdown, and a `mongoCompatible` strict
+  mode that rejects non-portable constructs at development time.
+- **UTC-canonical timestamps** with IANA timezone support, validated at construction.
+- **Extended JSON v2 interop** — `export()` feeds `mongoimport`; `mongoexport` output imports back.
+- **Offline mutation queue** and sync engine with five conflict strategies
+  (`last-write-wins`, `server-wins`, `client-wins`, `field-level`, `custom`).
+- **Inspector protocol v1** with pairing, sessions, and live change events.
+- **Five storage adapters**: Memory, Node SQLite, IndexedDB, Expo SQLite, Capacitor SQLite.
+
+### `anchordb-sync-server`
+
+- Framework-agnostic protocol engine over a pluggable `ServerStore`.
+- Express, NestJS and Next.js adapters, all held to one conformance suite.
+- `MemoryStore` (default) and `MongooseStore`.
+
+### `anchordb-react`
+
+- `useFind`, `useFindOne`, `useCount`, `useAggregate`, `useSyncStatus`, `useAnchorEvent`.
+
+### `anchordb-angular`
+
+- `AnchorModule.forRoot`/`forFeature`, `getModelToken`, `AnchorService` with RxJS-compatible
+  observables. Angular and RxJS are optional peers and are never imported.
+
+### `anchordb-relay`
+
+- Development-only WebSocket relay plus the `anchor-relay` CLI.
+
+### Known limitations
+
+- **Expo SQLite and Capacitor SQLite are unverified** — written and typechecked, never executed on
+  a device. Test before production use.
+- The REST sync transport and `MongooseStore` have no live-server tests.
+- Not supported in v1: discriminators, `refPath`, transactions, server-side change streams,
+  text/geo/hashed indexes, collation, and the `$graphLookup`/`$geoNear`/`$search`/`$merge`/`$out`/
+  `$unionWith` aggregation stages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnchorDB contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# anchordb
+
+**MongoDB + Mongoose, for mobile apps.** A local, persistent document database with a
+Mongoose-shaped API that works completely offline — and *optionally* synchronises with a backend.
+
+```bash
+npm install anchordb
+```
+
+## Quick start — no backend required
+
+```ts
+import { AnchorDB, Schema } from "anchordb";
+
+const db = new AnchorDB({ name: "my-app" });   // no sync block → purely local
+
+const userSchema = new Schema({
+  name:  { type: String, required: true, trim: true },
+  email: { type: String, required: true, unique: true, lowercase: true },
+  age:   { type: Number, min: 0, max: 150 },
+  role:  { type: String, enum: ["admin", "user"], default: "user" },
+}, { timestamps: true });
+
+const User = db.model("User", userSchema);
+
+await User.create({ name: "Nisala", age: 28, email: "n@example.com" });
+
+const adults = await User.find({ age: { $gte: 18 } })
+  .sort("-createdAt")
+  .limit(10);
+```
+
+That is Mongoose code. It runs on a phone, offline, with no server anywhere.
+
+## Two principles
+
+**1. Zero re-learning.** If you know MongoDB and Mongoose on the backend, you already know this:
+the same `Schema`, `model()`, query builder, `populate`, `ObjectId`, index options and error codes
+(`err.code === 11000`, `err.errors[path].kind`). Anything Mongoose does that AnchorDB does not is
+written down, never silently reinterpreted.
+
+**2. Sync is optional.** An app with no backend is the default case, not a degraded one. With no
+`sync` block there is no mutation queue, no network code, no sync metadata and no tombstones.
+Adding sync later requires no changes to your CRUD code.
+
+## Decorators (optional)
+
+Identical in shape to `@nestjs/mongoose`, so the same decorated class can be shared between an
+Ionic/Angular app and a NestJS backend:
+
+```ts
+import { Schema, Prop, SchemaFactory } from "anchordb/decorators";
+
+@Schema({ timestamps: true })
+export class User {
+  @Prop({ required: true }) name!: string;
+  @Prop(String) nickname!: string;
+  @Prop([String]) tags!: string[];
+}
+export const UserSchema = SchemaFactory.createForClass(User);
+```
+
+Requires `experimentalDecorators` + `emitDecoratorMetadata` for type inference — or pass the type
+explicitly (`@Prop(String)`) and no metadata is needed at all.
+
+## Storage adapters
+
+| Adapter | Import | Platform | Verified here |
+| --- | --- | --- | --- |
+| Memory | `MemoryAdapter` from `anchordb` | any | yes — conformance suite |
+| Node SQLite | `anchordb/storage/node-sqlite` | Node 22.5+ (built in, no native deps) | yes — conformance suite |
+| IndexedDB | `anchordb/storage/indexeddb` | browser, PWA, `ionic serve` | yes — conformance suite |
+| Expo SQLite | `anchordb/storage/expo-sqlite` | React Native, iOS/Android | **no — see below** |
+| Capacitor SQLite | `anchordb/storage/capacitor-sqlite` | Ionic native | **no — see below** |
+
+All adapters sit behind one `DatabaseAdapter` interface, and the three verified ones are held to a
+single 70-test conformance suite, so unique-index semantics, null handling and write atomicity
+cannot drift between them.
+
+## Interchange with MongoDB
+
+Export and import speak what `mongoexport` writes and `mongoimport` reads, in both directions and
+in both formats:
+
+```ts
+// Extended JSON — lossless. NDJSON by default, which mongoimport reads with no extra flag.
+const file = await Model.export({ mode: "canonical" });
+
+// Only what a filter matches, run as a real query so it is cast and indexed like any other.
+const page = await Model.export({ filter: { status: "active" } });
+
+// CSV — for spreadsheets, and for mongoimport --type=csv --headerline.
+const csv = await Model.export({ format: "csv" });
+
+// Import auto-detects a JSON array, NDJSON or CSV.
+await db.import(text, { mode: "upsert" });
+```
+
+`mongoimportCommand()` prints the exact command that ingests the result.
+
+CSV carries no types, so on import values are inferred conservatively and then **cast through the
+collection's schema** — a declared `Number` comes back a number rather than the text the file held.
+Two things CSV genuinely cannot round-trip, stated rather than hidden: `null` and a missing field
+are both an empty cell (read back as missing, matching `mongoimport --ignoreBlanks`), and nested
+fields travel as dotted paths.
+
+Extended JSON has three modes, matching the ones MongoDB Compass offers: `canonical` (lossless),
+`relaxed` (readable), and `default` (relaxed, except integers past 2^53 which are marked
+`$numberLong` so they do not silently become doubles).
+
+## Status
+
+**0.2.0 — early, and 0.x means breaking changes are expected.**
+
+**631 tests across 17 files.** Implemented and covered: the local database, Mongoose-shaped schema
+and validation, decorators, indexes with real `E11000` enforcement, the lazy query builder,
+`populate`, documents with `.save()`, aggregation, UTC timestamps and timezones, MongoDB Extended
+JSON and CSV interop, the offline mutation queue, the sync engine with all five conflict strategies,
+and the inspector protocol.
+
+### New in 0.2.0
+
+- **`updateMany` and `deleteMany` on the inspector protocol**, behind a new `documents:bulk`
+  capability. Both route through the ordinary Model API, so a bulk write from Anchor Lens validates,
+  stamps and queues exactly like an app write. An empty filter is refused unless explicitly
+  acknowledged — an inspector that can empty a collection on a mis-tap is worse than one that asks
+  twice. The capability is negotiated, so an older agent and a newer Lens still connect.
+- **CSV export and import**, and a `filter` on export.
+- **A MongoDB bridge protocol** (`MongoBridgeClient`), so Anchor Lens can pull collections from a
+  real MongoDB or push a device into one. The driver runs in `anchordb-relay` — React
+  Native has no TCP sockets — and both directions carry the same Extended JSON as the file export.
+- **`default` Extended JSON mode.**
+- **A no-op update is now matched but not modified**, as in MongoDB: `modifiedCount` excludes
+  documents the update did not change, and their `updatedAt` and version key are left alone. It
+  previously counted every match, because the timestamp was stamped before the comparison. Beyond
+  correctness this matters for bulk writes — setting a field over 10,000 documents no longer queues
+  10,000 mutations when only a few hundred needed changing.
+
+### What is NOT verified
+
+Stated plainly rather than left to be discovered:
+
+- **Expo SQLite and Capacitor SQLite have never been executed.** They are written against the
+  documented APIs and typechecked, but this package is developed on a machine with no simulator or
+  device. All of their query, index and unique-enforcement logic is inherited from a shared base
+  that *is* covered by the conformance suite; the unverified surface is roughly forty lines of
+  driver plumbing each. **Test on a device before relying on them in production.**
+- **The REST sync transport** is typechecked but has no live-HTTP test. The protocol it speaks is
+  covered end to end through an in-process transport.
+- **`MongooseStore`** in `anchordb-sync-server` has not run against a live MongoDB here.
+
+### Not supported in v1
+
+Documented rather than silently absent: discriminators, `refPath`, transactions/sessions,
+server-side change streams, text/`2dsphere`/hashed indexes, collation, and the
+`$graphLookup`/`$geoNear`/`$search`/`$merge`/`$out`/`$unionWith` aggregation stages.
+
+## License
+
+MIT

package/dist/cjs/conflict/strategies.d.ts

@@ -0,0 +1,110 @@
+import type { ConflictContext, ConflictResolutionConfig, ConflictStrategyName, Resolution } from "./types.js";
+/**
+ * The five conflict strategies, behind one interface.
+ *
+ * The sync engine knows only `resolve(context) -> Resolution`. No strategy-specific branching leaks
+ * into the engine, which is what makes switching strategy a pure configuration change (§19) and
+ * makes a sixth strategy a matter of registering one more object.
+ */
+export interface ConflictStrategyHandler<T extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: ConflictStrategyName | string;
+    resolve(context: ConflictContext<T>): Promise<Resolution<T>> | Resolution<T>;
+}
+/**
+ * Last write wins — the default.
+ *
+ * "Latest" is decided by the hybrid logical clock, never by raw device wall-clock strings. The
+ * comparison order is documented in SYNC_PROTOCOL.md:
+ *
+ *   1. HLC physical time (already skew-corrected against the server)
+ *   2. HLC logical counter, for writes inside the same millisecond
+ *   3. clientId, lexicographically
+ *
+ * Step 3 is what makes this a *total* order. Without it two devices could produce genuinely equal
+ * stamps and the winner would depend on evaluation order — different devices would converge to
+ * different documents, which is precisely the failure LWW is supposed to prevent.
+ *
+ * On an exact tie the server wins, because the server's copy is the one everyone else has already
+ * observed; preferring the client would make convergence depend on who pushed last.
+ */
+export declare class LastWriteWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "last-write-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+/**
+ * Server wins — the local change is discarded and the server's document adopted.
+ *
+ * `pushBack: false` matters: re-pushing a document the server just gave us would create an endless
+ * echo between the two.
+ */
+export declare class ServerWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "server-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+/**
+ * Client wins — the local change overwrites the server's.
+ *
+ * The loop hazard is real and is handled by the engine rather than here: the re-push carries
+ * `baseVersion = remoteVersion` (the version we just observed), so the server's optimistic check
+ * now passes instead of conflicting again forever. The engine also caps `conflictAttempts`.
+ */
+export declare class ClientWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "client-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+declare const DELETED: unique symbol;
+/**
+ * Field-level three-way merge.
+ *
+ * Compares local and remote against their common ancestor (`base`, the last server-confirmed
+ * document kept in the shadow table). Paths only one side touched merge silently; paths both sides
+ * touched are a genuine conflict and fall to `fieldPolicy`.
+ *
+ * Documented edge cases, each with a test:
+ *
+ *  - **No base.** Without an ancestor we cannot tell an edit from an insert, so a merge would be a
+ *    guess. Falls back to last-write-wins rather than inventing a result.
+ *  - **Arrays are atomic by default.** Element-wise merging of two concurrently reordered arrays
+ *    has no correct answer in general. `arrayStrategy: "union-by-id"` opts into merging arrays of
+ *    objects that carry `_id`/`id`.
+ *  - **Deleted fields.** "Deleted on one side" is distinguished from "absent on both" by diffing
+ *    against base — otherwise a deletion would be silently undone by the other side's copy.
+ *  - **Type changes** (string -> object) are treated as an ordinary same-path conflict.
+ *  - **Object replacement.** An edit at `a` conflicts with an edit at `a.b`: parent/child overlap is
+ *    detected explicitly, because treating them as unrelated paths would resurrect a replaced object.
+ */
+export declare class FieldLevelStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "field-level";
+    private readonly policy;
+    private readonly arrayStrategy;
+    private readonly fallback;
+    constructor(config?: ConflictResolutionConfig<T>);
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+    private decide;
+    /** Opt-in array merging for arrays of objects with a stable identity. */
+    private mergeArraysById;
+}
+/**
+ * Custom resolver.
+ *
+ * The developer's function may return either a bare document (treated as the resolved value) or a
+ * full `Resolution` when it needs to control `pushBack`. A throwing resolver is *not* caught here —
+ * the engine parks the mutation and keeps draining the queue, so one bad resolver cannot wedge sync
+ * for every other document.
+ */
+export declare class CustomStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "custom";
+    private readonly resolver;
+    constructor(config: ConflictResolutionConfig<T>);
+    resolve(ctx: ConflictContext<T>): Promise<Resolution<T>>;
+}
+/** Registry — open for user-defined strategies (§11). */
+export declare class ConflictStrategyRegistry<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly strategies;
+    constructor(config?: ConflictResolutionConfig<T>);
+    register(strategy: ConflictStrategyHandler<T>): void;
+    get(name: string): ConflictStrategyHandler<T>;
+    names(): string[];
+}
+export { DELETED as FIELD_DELETED };
+//# sourceMappingURL=strategies.d.ts.map

package/dist/cjs/conflict/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/conflict/strategies.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EAEpB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClG,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAAC;IAC7C,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;CAC9E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,uBAAuB,CAAC,CAAC,CAAC;IACzG,QAAQ,CAAC,IAAI,qBAAqB;IAElC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;CAKhD;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,uBAAuB,CAAC,CAAC,CAAC;IACtG,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;CAGhD;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,uBAAuB,CAAC,CAAC,CAAC;IACtG,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;CAGhD;AAED,QAAA,MAAM,OAAO,eAAiC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,uBAAuB,CAAC,CAAC,CAAC;IACtG,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,MAAM,GAAE,wBAAwB,CAAC,CAAC,CAAM;IAKpD,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAsD/C,OAAO,CAAC,MAAM;IAMd,yEAAyE;IACzE,OAAO,CAAC,eAAe;CA+BxB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,uBAAuB,CAAC,CAAC,CAAC;IAClG,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuD;gBAEpE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAUzC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CAc/D;AAED,yDAAyD;AACzD,qBAAa,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiD;gBAEhE,MAAM,GAAE,wBAAwB,CAAC,CAAC,CAAM;IAUpD,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIpD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,CAAC,CAAC,CAAC;IAU7C,KAAK,IAAI,MAAM,EAAE;CAGlB;AAmED,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,CAAC"}

package/dist/cjs/conflict/strategies.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_DELETED = exports.ConflictStrategyRegistry = exports.CustomStrategy = exports.FieldLevelStrategy = exports.ClientWinsStrategy = exports.ServerWinsStrategy = exports.LastWriteWinsStrategy = void 0;
+const hlc_ts_1 = require("../core/hlc.js");
+const path_ts_1 = require("../query/path.js");
+/**
+ * Last write wins — the default.
+ *
+ * "Latest" is decided by the hybrid logical clock, never by raw device wall-clock strings. The
+ * comparison order is documented in SYNC_PROTOCOL.md:
+ *
+ *   1. HLC physical time (already skew-corrected against the server)
+ *   2. HLC logical counter, for writes inside the same millisecond
+ *   3. clientId, lexicographically
+ *
+ * Step 3 is what makes this a *total* order. Without it two devices could produce genuinely equal
+ * stamps and the winner would depend on evaluation order — different devices would converge to
+ * different documents, which is precisely the failure LWW is supposed to prevent.
+ *
+ * On an exact tie the server wins, because the server's copy is the one everyone else has already
+ * observed; preferring the client would make convergence depend on who pushed last.
+ */
+class LastWriteWinsStrategy {
+    constructor() {
+        this.name = "last-write-wins";
+    }
+    resolve(ctx) {
+        const cmp = (0, hlc_ts_1.compareHlcStamps)(ctx.localHlc, ctx.remoteHlc);
+        if (cmp > 0)
+            return { winner: "local", document: ctx.local, pushBack: true };
+        return { winner: "remote", document: ctx.remote, pushBack: false };
+    }
+}
+exports.LastWriteWinsStrategy = LastWriteWinsStrategy;
+/**
+ * Server wins — the local change is discarded and the server's document adopted.
+ *
+ * `pushBack: false` matters: re-pushing a document the server just gave us would create an endless
+ * echo between the two.
+ */
+class ServerWinsStrategy {
+    constructor() {
+        this.name = "server-wins";
+    }
+    resolve(ctx) {
+        return { winner: "remote", document: ctx.remote, pushBack: false };
+    }
+}
+exports.ServerWinsStrategy = ServerWinsStrategy;
+/**
+ * Client wins — the local change overwrites the server's.
+ *
+ * The loop hazard is real and is handled by the engine rather than here: the re-push carries
+ * `baseVersion = remoteVersion` (the version we just observed), so the server's optimistic check
+ * now passes instead of conflicting again forever. The engine also caps `conflictAttempts`.
+ */
+class ClientWinsStrategy {
+    constructor() {
+        this.name = "client-wins";
+    }
+    resolve(ctx) {
+        return { winner: "local", document: ctx.local, pushBack: true };
+    }
+}
+exports.ClientWinsStrategy = ClientWinsStrategy;
+const DELETED = Symbol("anchor.field.deleted");
+exports.FIELD_DELETED = DELETED;
+/**
+ * Field-level three-way merge.
+ *
+ * Compares local and remote against their common ancestor (`base`, the last server-confirmed
+ * document kept in the shadow table). Paths only one side touched merge silently; paths both sides
+ * touched are a genuine conflict and fall to `fieldPolicy`.
+ *
+ * Documented edge cases, each with a test:
+ *
+ *  - **No base.** Without an ancestor we cannot tell an edit from an insert, so a merge would be a
+ *    guess. Falls back to last-write-wins rather than inventing a result.
+ *  - **Arrays are atomic by default.** Element-wise merging of two concurrently reordered arrays
+ *    has no correct answer in general. `arrayStrategy: "union-by-id"` opts into merging arrays of
+ *    objects that carry `_id`/`id`.
+ *  - **Deleted fields.** "Deleted on one side" is distinguished from "absent on both" by diffing
+ *    against base — otherwise a deletion would be silently undone by the other side's copy.
+ *  - **Type changes** (string -> object) are treated as an ordinary same-path conflict.
+ *  - **Object replacement.** An edit at `a` conflicts with an edit at `a.b`: parent/child overlap is
+ *    detected explicitly, because treating them as unrelated paths would resurrect a replaced object.
+ */
+class FieldLevelStrategy {
+    constructor(config = {}) {
+        this.name = "field-level";
+        this.fallback = new LastWriteWinsStrategy();
+        this.policy = config.fieldPolicy ?? "lww";
+        this.arrayStrategy = config.arrayStrategy ?? "atomic";
+    }
+    resolve(ctx) {
+        if (!ctx.base) {
+            // Honest degradation: a "merge" without an ancestor is a guess dressed up as a decision.
+            return this.fallback.resolve(ctx);
+        }
+        const base = ctx.base;
+        const local = ctx.local;
+        const remote = ctx.remote;
+        const localChanges = diff(base, local);
+        const remoteChanges = diff(base, remote);
+        const merged = (0, path_ts_1.deepClone)(remote);
+        const conflicts = [];
+        let tookLocal = false;
+        for (const [path, localValue] of localChanges) {
+            const remoteValue = remoteChanges.get(path);
+            const overlaps = remoteChanges.has(path) || hasAncestorOrDescendant(path, remoteChanges);
+            if (!overlaps) {
+                // Only the client touched this path — apply it on top of the server document.
+                applyChange(merged, path, localValue);
+                tookLocal = true;
+                continue;
+            }
+            if (remoteChanges.has(path) && (0, path_ts_1.valuesEqual)(localValue, remoteValue)) {
+                continue; // both sides made the same edit; nothing to decide
+            }
+            conflicts.push(path);
+            const decision = this.decide(path, ctx);
+            if (decision === "client") {
+                applyChange(merged, path, localValue);
+                tookLocal = true;
+            }
+            // "server" needs no action: `merged` started as the remote document.
+        }
+        if (this.arrayStrategy === "union-by-id") {
+            this.mergeArraysById(base, local, remote, merged);
+        }
+        return {
+            winner: tookLocal ? "merged" : "remote",
+            document: merged,
+            // Only push back when the merge actually contains something the server has not seen.
+            pushBack: tookLocal,
+            ...(conflicts.length > 0 ? { conflictedPaths: conflicts } : {}),
+        };
+    }
+    decide(path, ctx) {
+        const policy = typeof this.policy === "function" ? this.policy(path, ctx) : (this.policy ?? "lww");
+        if (policy !== "lww")
+            return policy;
+        return (0, hlc_ts_1.compareHlcStamps)(ctx.localHlc, ctx.remoteHlc) > 0 ? "client" : "server";
+    }
+    /** Opt-in array merging for arrays of objects with a stable identity. */
+    mergeArraysById(base, local, remote, merged) {
+        for (const key of new Set([...Object.keys(local), ...Object.keys(remote)])) {
+            const l = local[key];
+            const r = remote[key];
+            if (!Array.isArray(l) || !Array.isArray(r))
+                continue;
+            if (!l.every(hasIdentity) || !r.every(hasIdentity))
+                continue;
+            const baseArr = Array.isArray(base[key]) ? base[key] : [];
+            const baseIds = new Set(baseArr.map(identityOf));
+            const byId = new Map();
+            for (const item of r)
+                byId.set(identityOf(item), item);
+            for (const item of l) {
+                const id = identityOf(item);
+                // Added locally, or edited locally — local wins for that element.
+                if (!baseIds.has(id) || !(0, path_ts_1.valuesEqual)(item, baseArr.find((b) => identityOf(b) === id))) {
+                    byId.set(id, item);
+                }
+            }
+            // Removed on either side stays removed.
+            const removedLocally = baseArr.filter((b) => !l.some((x) => identityOf(x) === identityOf(b)));
+            for (const gone of removedLocally)
+                byId.delete(identityOf(gone));
+            merged[key] = [...byId.values()];
+        }
+    }
+}
+exports.FieldLevelStrategy = FieldLevelStrategy;
+/**
+ * Custom resolver.
+ *
+ * The developer's function may return either a bare document (treated as the resolved value) or a
+ * full `Resolution` when it needs to control `pushBack`. A throwing resolver is *not* caught here —
+ * the engine parks the mutation and keeps draining the queue, so one bad resolver cannot wedge sync
+ * for every other document.
+ */
+class CustomStrategy {
+    constructor(config) {
+        this.name = "custom";
+        if (!config.resolver) {
+            throw new Error('conflictResolution.strategy is "custom" but no `resolver` was provided. ' +
+                "Pass resolver: async ({ local, remote, base }) => {...}");
+        }
+        this.resolver = config.resolver;
+    }
+    async resolve(ctx) {
+        const result = await this.resolver(ctx);
+        if (result && typeof result === "object" && "winner" in result && "document" in result) {
+            return result;
+        }
+        const document = result;
+        // Infer the winner so events and Lens can report something meaningful.
+        const winner = (0, path_ts_1.valuesEqual)(document, ctx.remote)
+            ? "remote"
+            : (0, path_ts_1.valuesEqual)(document, ctx.local)
+                ? "local"
+                : "merged";
+        return { winner, document, pushBack: winner !== "remote" };
+    }
+}
+exports.CustomStrategy = CustomStrategy;
+/** Registry — open for user-defined strategies (§11). */
+class ConflictStrategyRegistry {
+    constructor(config = {}) {
+        this.strategies = new Map();
+        this.register(new LastWriteWinsStrategy());
+        this.register(new ServerWinsStrategy());
+        this.register(new ClientWinsStrategy());
+        this.register(new FieldLevelStrategy(config));
+        if (config.strategy === "custom" || config.resolver) {
+            this.register(new CustomStrategy(config));
+        }
+    }
+    register(strategy) {
+        this.strategies.set(strategy.name, strategy);
+    }
+    get(name) {
+        const found = this.strategies.get(name);
+        if (!found) {
+            throw new Error(`Unknown conflict strategy "${name}". Available: ${[...this.strategies.keys()].join(", ")}.`);
+        }
+        return found;
+    }
+    names() {
+        return [...this.strategies.keys()];
+    }
+}
+exports.ConflictStrategyRegistry = ConflictStrategyRegistry;
+// ---- diffing helpers -------------------------------------------------------
+/**
+ * Leaf-path diff of `next` against `prev`.
+ *
+ * Deletions are recorded explicitly with a sentinel rather than omitted, because "absent from the
+ * diff" and "deleted by this side" must not be confused — conflating them silently undoes deletions.
+ */
+function diff(prev, next) {
+    const out = new Map();
+    const prevPaths = (0, path_ts_1.flattenPaths)(prev);
+    const nextPaths = (0, path_ts_1.flattenPaths)(next);
+    for (const [path, value] of nextPaths) {
+        if (isInternal(path))
+            continue;
+        if (!prevPaths.has(path) || !(0, path_ts_1.valuesEqual)(prevPaths.get(path), value))
+            out.set(path, value);
+    }
+    for (const [path] of prevPaths) {
+        if (isInternal(path))
+            continue;
+        if (!nextPaths.has(path))
+            out.set(path, DELETED);
+    }
+    return out;
+}
+/** `updatedAt` and the version key always differ; treating them as edits would conflict every time. */
+function isInternal(path) {
+    const head = path.split(".")[0];
+    return head === "_id" || head === "updatedAt" || head === "__v" || head === "_sync";
+}
+function applyChange(target, path, value) {
+    if (value === DELETED) {
+        const parts = path.split(".");
+        const last = parts.pop();
+        const parent = parts.length ? (0, path_ts_1.getPath)(target, parts.join(".")) : target;
+        if (parent && typeof parent === "object")
+            delete parent[last];
+        return;
+    }
+    (0, path_ts_1.setPath)(target, path, value);
+}
+/** `a` conflicts with `a.b`: replacing an object and editing inside it are not independent. */
+function hasAncestorOrDescendant(path, others) {
+    for (const other of others.keys()) {
+        if (other === path)
+            continue;
+        if (other.startsWith(`${path}.`) || path.startsWith(`${other}.`))
+            return true;
+    }
+    return false;
+}
+function hasIdentity(item) {
+    return (item !== null &&
+        typeof item === "object" &&
+        !Array.isArray(item) &&
+        (("_id" in item) || ("id" in item)));
+}
+function identityOf(item) {
+    if (item === null || typeof item !== "object")
+        return item;
+    const rec = item;
+    return String(rec._id ?? rec.id);
+}
+//# sourceMappingURL=strategies.js.map