@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncConfig.md

@@ -0,0 +1,67 @@
+Configuration for local-first sync on a modelRouter, parallel to `realtime`.
+Requires the model schema to use `isDeletedPlugin` (soft delete) and `syncPlugin`
+(seq stamping) — validated at registration.
+
+## Properties
+
+### responseHandler?
+
+> `optional` **responseHandler?**: (`doc`, `method`) => `unknown`
+
+Custom serializer for sync payloads (snapshot entities and deltas).
+Falls back to the modelRouter responseHandler, then the document's toJSON.
+
+#### Parameters
+
+##### doc
+
+`Record`\<`string`, `unknown`\>
+
+##### method
+
+[`SyncMutationOperation`](../type-aliases/SyncMutationOperation.md)
+
+#### Returns
+
+`unknown`
+
+***
+
+### retentionDays?
+
+> `optional` **retentionDays?**: `number`
+
+C7: tombstone retention window in days (default 90). Tombstones older than this may
+be hard-deleted by the `compactTombstones` maintenance script; a client whose cursor
+predates the retained floor re-bootstraps (see `oldestRetainedSeq`).
+
+***
+
+### scope
+
+> **scope**: [`SyncScope`](../type-aliases/SyncScope.md)
+
+Which stream a document belongs to. Multi-tenant by default via the tenant scope.
+
+***
+
+### snapshotFilter?
+
+> `optional` **snapshotFilter?**: (`user`) => `Record`\<`string`, `unknown`\> \| `Promise`\<`Record`\<`string`, `unknown`\>\>
+
+Server-side query restricting snapshots to the caller's documents. Derived
+automatically for owner scopes ({field: user.id}) and tenant scopes
+({field: {$in: getUserScopes(...)}}); REQUIRED for custom resolver scopes, whose
+stream function cannot be inverted into a Mongo query.
+
+#### Parameters
+
+##### user
+
+###### id
+
+`string`
+
+#### Returns
+
+`Record`\<`string`, `unknown`\> \| `Promise`\<`Record`\<`string`, `unknown`\>\>

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncCounterDocument.md

@@ -0,0 +1,39 @@
+## Properties
+
+### \_id
+
+> **\_id**: `ObjectId`
+
+***
+
+### compactedThroughSeq
+
+> **compactedThroughSeq**: `number`
+
+C7 retention watermark: the highest seq on this stream whose row (tombstone or
+scope-move marker) has been hard-deleted by `compactTombstones`. A client whose
+cursor is below this may have missed a compacted deletion and must re-bootstrap;
+a client at or above it has already seen everything that was reaped. 0 until the
+first compaction pass touches the stream.
+
+***
+
+### pending
+
+> **pending**: [`SyncPendingClaim`](SyncPendingClaim.md)[]
+
+C1: seqs claimed but not yet confirmed committed. The stable frontier is
+`min(pending.seq) - 1`, or `seq` (the head) when empty, so a cursor never
+advances past a seq whose owning write has not yet landed.
+
+***
+
+### seq
+
+> **seq**: `number`
+
+***
+
+### stream
+
+> **stream**: `string`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncDelta.md

@@ -0,0 +1,76 @@
+A change event delivered to subscribed clients via `sync:delta`.
+
+## Per-entity ordering & the LWW-by-seq contract (C8)
+
+The server serializes delta dispatch PER entity (`{collection}:{id}`): two deltas for
+the same document are always emitted in change-stream (commit) order, so their `seq`
+values arrive monotonically for that entity. Deltas for DIFFERENT entities may arrive
+in any order (they dispatch concurrently). Clients therefore apply last-writer-wins
+BY SEQ within an entity: a delta whose `seq` is at or below the entity's applied seq is
+an idempotent no-op; only a strictly higher `seq` mutates local state. Combined with
+the C1 frontier (`frontierSeq`), a cursor never advances past an uncommitted seq, so no
+committed delta is ever permanently skipped.
+
+## Properties
+
+### collection
+
+> **collection**: `string`
+
+Collection tag (e.g. "todos").
+
+***
+
+### data?
+
+> `optional` **data?**: `unknown`
+
+Serialized document data (omitted for tombstone deltas emitted to a previous stream).
+
+***
+
+### deleted?
+
+> `optional` **deleted?**: `boolean`
+
+True when the entity is soft-deleted.
+
+***
+
+### frontierSeq?
+
+> `optional` **frontierSeq?**: `number`
+
+C1: the stream's stable frontier at emit time. The client advances its cursor to
+`min(seq, frontierSeq)` so a delta observed out of commit order never advances a
+cursor past an uncommitted hole.
+
+***
+
+### id
+
+> **id**: `string`
+
+Document id.
+
+***
+
+### method
+
+> **method**: [`SyncMutationOperation`](../type-aliases/SyncMutationOperation.md)
+
+***
+
+### seq
+
+> **seq**: `number`
+
+The document's `_syncSeq`.
+
+***
+
+### stream
+
+> **stream**: `string`
+
+Stream key this delta belongs to (e.g. "todos|owner:123").

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncEntitiesResponse.md

@@ -0,0 +1,7 @@
+Response shape for `GET /sync/entities` (point lookup for repair).
+
+## Properties
+
+### entities
+
+> **entities**: [`SyncEntityPayload`](SyncEntityPayload.md)[]

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncEntityPayload.md

@@ -0,0 +1,33 @@
+A single entity in a snapshot response.
+
+## Properties
+
+### data
+
+> **data**: `unknown`
+
+Serialized document data (present for tombstones too, so clients can render conflicts).
+
+***
+
+### deleted
+
+> **deleted**: `boolean`
+
+True when the entity is a soft-delete tombstone.
+
+***
+
+### id
+
+> **id**: `string`
+
+Document id.
+
+***
+
+### seq
+
+> **seq**: `number`
+
+The document's `_syncSeq` — the client's per-entity version and cursor source.

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncKeyDocument.md

@@ -0,0 +1,23 @@
+## Properties
+
+### \_id
+
+> **\_id**: `ObjectId`
+
+***
+
+### created
+
+> **created**: `Date`
+
+***
+
+### keyMaterial
+
+> **keyMaterial**: `string`
+
+***
+
+### userId
+
+> **userId**: `string`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncMutateBatchRequest.md

@@ -0,0 +1,24 @@
+A batch of client mutations delivered via `sync:mutateBatch` or
+`POST /sync/mutate/batch`. The server MUST apply strictly in array order and
+stop at the first non-ack outcome (see `applySyncMutationBatch`).
+
+## Properties
+
+### batchId?
+
+> `optional` **batchId?**: `string`
+
+Client-generated correlation id, socket transport only (ignored over
+HTTP). Echoed back immediately via `sync:batchReceived {batchId}` before
+processing begins, so the client can distinguish "the server has no
+sync:mutateBatch handler" (silence past the grace period, batching
+unsupported) from "the server is just slow to finish this batch" (a
+receipt arrived; keep waiting up to the full batch timeout).
+
+***
+
+### mutations
+
+> **mutations**: [`SyncMutateRequest`](SyncMutateRequest.md)[]
+
+Ordered mutations; each still carries its own mutationId.

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncMutateBatchResponse.md

@@ -0,0 +1,12 @@
+Response to a batch mutation request.
+
+`results.length < request.mutations.length` means the server halted at the
+first non-ack: `results[results.length - 1]` is that failing outcome, and
+every mutation after it was NOT attempted (not ledgered, not applied) —
+still safe to resend in a later batch (INV-3).
+
+## Properties
+
+### results
+
+> **results**: [`SyncMutateBatchResult`](../type-aliases/SyncMutateBatchResult.md)[]

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncMutateRequest.md

@@ -0,0 +1,47 @@
+A client mutation delivered via `sync:mutate` or `POST /sync/mutate`.
+
+## Properties
+
+### baseVersion?
+
+> `optional` **baseVersion?**: `number`
+
+The `_syncSeq` the client last saw for this document; enables LWW conflict detection.
+
+***
+
+### collection
+
+> **collection**: `string`
+
+Collection tag (e.g. "todos").
+
+***
+
+### data?
+
+> `optional` **data?**: `Record`\<`string`, `unknown`\>
+
+Fields to write (create/update).
+
+***
+
+### id?
+
+> `optional` **id?**: `string`
+
+Target document id (required for update/delete; client-generated allowed for create).
+
+***
+
+### mutationId
+
+> **mutationId**: `string`
+
+Client-generated stable id; the idempotency key.
+
+***
+
+### operation
+
+> **operation**: [`SyncMutationOperation`](../type-aliases/SyncMutationOperation.md)

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncMutationDocument.md

@@ -0,0 +1,59 @@
+## Properties
+
+### \_id
+
+> **\_id**: `ObjectId`
+
+***
+
+### claimedAt
+
+> **claimedAt**: `Date`
+
+***
+
+### created
+
+> **created**: `Date`
+
+***
+
+### error?
+
+> `optional` **error?**: `string`
+
+***
+
+### mutationId
+
+> **mutationId**: `string`
+
+***
+
+### nackCode?
+
+> `optional` **nackCode?**: `string`
+
+***
+
+### resultId?
+
+> `optional` **resultId?**: `string`
+
+***
+
+### resultSeq?
+
+> `optional` **resultSeq?**: `number`
+
+***
+
+### status
+
+> **status**: [`SyncMutationStatus`](../type-aliases/SyncMutationStatus.md)
+
+***
+
+### userId
+
+> **userId**: `string`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncMutationRunResult.md

@@ -0,0 +1,11 @@
+## Properties
+
+### outcome
+
+> **outcome**: [`SyncMutationOutcome`](../type-aliases/SyncMutationOutcome.md)
+
+***
+
+### stage
+
+> **stage**: `"rate_limited"` \| `"applied"`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncNack.md

@@ -0,0 +1,44 @@
+Rejected mutation. Conflict nacks carry the canonical server document.
+
+## Properties
+
+### code
+
+> **code**: [`SyncNackCode`](../type-aliases/SyncNackCode.md)
+
+***
+
+### message?
+
+> `optional` **message?**: `string`
+
+***
+
+### mutationId
+
+> **mutationId**: `string`
+
+***
+
+### retryAfterMs?
+
+> `optional` **retryAfterMs?**: `number`
+
+Minimum time (ms) the client should wait before retrying, filled by the
+server with the remaining rate-limit window (`rate_limited` nacks only).
+
+***
+
+### serverDoc?
+
+> `optional` **serverDoc?**: `unknown`
+
+Canonical serialized server document (conflict nacks).
+
+***
+
+### serverSeq?
+
+> `optional` **serverSeq?**: `number`
+
+The server document's current `_syncSeq` (conflict nacks).

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncPendingClaim.md

@@ -0,0 +1,17 @@
+An uncommitted seq claim recorded on the counter's in-flight registry (C1).
+
+## Properties
+
+### claimedAt
+
+> **claimedAt**: `Date`
+
+When the claim was registered; a claim older than the lease is reclaimable.
+
+***
+
+### seq
+
+> **seq**: `number`
+
+The claimed seq (or, for a batch, one entry per claimed seq).

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncRegistryEntry.md

@@ -0,0 +1,49 @@
+A registered model with SyncDB local-first sync configuration.
+
+## Properties
+
+### collectionName
+
+> **collectionName**: `string`
+
+MongoDB collection name (e.g. "todos")
+
+***
+
+### collectionTag
+
+> **collectionTag**: `string`
+
+Collection tag used in the sync protocol (route path without the leading slash)
+
+***
+
+### config
+
+> **config**: [`SyncConfig`](SyncConfig.md)
+
+Sync configuration from modelRouter options
+
+***
+
+### modelName
+
+> **modelName**: `string`
+
+Mongoose model name (e.g. "Todo")
+
+***
+
+### options
+
+> **options**: [`ModelRouterOptions`](ModelRouterOptions.md)\<`unknown`\>
+
+Full modelRouter options (for responseHandler, permissions, etc.)
+
+***
+
+### routePath
+
+> **routePath**: `string`
+
+Route path (e.g. "/todos")

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncResyncHint.md

@@ -0,0 +1,15 @@
+Payload of the `sync:resync-required` socket event (Task 9.16).
+
+Emitted server-wide when the change stream could not be resumed — the oplog no longer
+contains the resume point, so the events in the gap can never be delivered. Any cursor a
+client holds may now sit below changes (including deletions) it will never be told about,
+so the only safe response is to re-bootstrap every stream. Clients that do not handle the
+event still converge on their next full bootstrap; handling it just makes that immediate.
+
+## Properties
+
+### reason
+
+> **reason**: `"history_lost"`
+
+Why the resync is needed. Only `history_lost` exists today.

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncScopeBroadcast.md

@@ -0,0 +1,7 @@
+A single shared stream for the whole collection (all authenticated users).
+
+## Properties
+
+### type
+
+> **type**: `"broadcast"`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncScopeMoveDocument.md

@@ -0,0 +1,41 @@
+## Properties
+
+### \_id
+
+> **\_id**: `ObjectId`
+
+***
+
+### collectionTag
+
+> **collectionTag**: `string`
+
+***
+
+### created
+
+> **created**: `Date`
+
+***
+
+### entityId
+
+> **entityId**: `string`
+
+***
+
+### fromStream
+
+> **fromStream**: `string`
+
+***
+
+### seq
+
+> **seq**: `number`
+
+***
+
+### toStream
+
+> **toStream**: `string`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncScopeOwner.md

@@ -0,0 +1,15 @@
+Scope a collection's streams by document owner (default field: `ownerId`).
+
+## Properties
+
+### field?
+
+> `optional` **field?**: `string`
+
+Field holding the owning user's id. Defaults to "ownerId".
+
+***
+
+### type
+
+> **type**: `"owner"`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncScopeTenant.md

@@ -0,0 +1,15 @@
+Scope a collection's streams by a tenant/workspace field (e.g. `organizationId`).
+
+## Properties
+
+### field
+
+> **field**: `string`
+
+Field holding the tenant/workspace id.
+
+***
+
+### type
+
+> **type**: `"tenant"`

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncSeqClaim.md

@@ -0,0 +1,28 @@
+Result of a seq claim: the last seq claimed (range [lastSeq - count + 1, lastSeq])
+and whether the claim registered a pending entry that a later `confirmSyncSeqs`
+must clear. A session-backed claim skips the pending registry entirely (the write
+and the `$inc` commit atomically), so `registered` is false and no confirm is due.
+
+## Properties
+
+### lastSeq
+
+> **lastSeq**: `number`
+
+The last (highest) seq claimed; the range is [lastSeq - count + 1, lastSeq].
+
+***
+
+### registered
+
+> **registered**: `boolean`
+
+True when a pending registry entry was recorded and `confirmSyncSeqs` must clear it.
+
+***
+
+### seqs
+
+> **seqs**: `number`[]
+
+Every seq claimed, in ascending order (the range materialized).

package/src/docs/versioned/57.1.0/reference/generated/api/interfaces/SyncSeqConfirmResult.md

@@ -0,0 +1,14 @@
+Outcome of clearing pending claims from a stream's in-flight registry.
+
+## Properties
+
+### cleared
+
+> **cleared**: `boolean`
+
+True when at least one pending entry was actually removed. False means the claim
+was already gone — for a `registered` claim that is the reaped-lease signature
+(Task 9.17): the writer stalled past [PENDING\_CLAIM\_LEASE\_MS](../variables/PENDING_CLAIM_LEASE_MS.md),
+`computeStableFrontier` reclaimed its seq, and the frontier has already advanced
+past a seq whose write only just landed. Callers must re-stamp the document (see
+`restampReapedSeq`) or log loudly rather than silently stranding it.