@terreno/mcp 57.1.0 → 57.2.0

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/OrganizationQueryFilter.md

@@ -0,0 +1,15 @@
+> **OrganizationQueryFilter**(`user?`): \{ `organizationId`: \{ `$in`: `string`[]; \}; \} \| `null`
+
+Restricts list queries to documents belonging to one of the caller's organizations. This is the
+tenant-scoped analog of [OwnerQueryFilter](OwnerQueryFilter.md): it filters on the document's `organizationId`
+field using the user's `organizationIds`. Returns `null` for anonymous callers (no user).
+
+## Parameters
+
+### user?
+
+[`User`](../interfaces/User.md)
+
+## Returns
+
+\{ `organizationId`: \{ `$in`: `string`[]; \}; \} \| `null`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/OwnerScope.md

@@ -0,0 +1,11 @@
+> **OwnerScope**(`options?`): [`ResourceScope`](../interfaces/ResourceScope.md)
+
+## Parameters
+
+### options?
+
+`string` \| [`OwnerScopeOptions`](../interfaces/OwnerScopeOptions.md)
+
+## Returns
+
+[`ResourceScope`](../interfaces/ResourceScope.md)

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/addMeRoutes.md

@@ -0,0 +1,23 @@
+> **addMeRoutes**(`app`, `userModel`, `_authOptions?`, `accessControl?`): `void`
+
+## Parameters
+
+### app
+
+`Application`
+
+### userModel
+
+[`UserModel`](../interfaces/UserModel.md)
+
+### \_authOptions?
+
+[`AuthOptions`](../interfaces/AuthOptions.md)
+
+### accessControl?
+
+[`AnyTerrenoAccess`](../type-aliases/AnyTerrenoAccess.md)
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/addSyncRoutes.md

@@ -0,0 +1,21 @@
+> **addSyncRoutes**(`app`, `options?`): `void`
+
+Mount the SyncDB HTTP routes:
+- GET /sync/streams — the authoritative set of streams the caller belongs to (C2)
+- GET /sync/snapshot — per-stream bootstrap/catch-up with server-enforced scoping
+- POST /sync/mutate — HTTP fallback mutation channel over applySyncMutation
+- GET /sync/key — per-user key material for the default encryption KeyProvider
+
+## Parameters
+
+### app
+
+`Application`
+
+### options?
+
+[`SyncAppOptions`](../interfaces/SyncAppOptions.md) = `{}`
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/adminBodyFieldsToStrip.md

@@ -0,0 +1,13 @@
+> **adminBodyFieldsToStrip**(`admin`): `Set`\<`string`\>
+
+Keys stripped from POST/PATCH bodies when `admin` is set on modelRouter.
+
+## Parameters
+
+### admin
+
+[`AdminConfig`](../interfaces/AdminConfig.md)
+
+## Returns
+
+`Set`\<`string`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/apiUnauthorizedMiddleware.md

@@ -0,0 +1,30 @@
+> **apiUnauthorizedMiddleware**(`err`, `_req`, `res`, `next`): `void`
+
+Converts the bare `Error("Unauthorized")` that Passport throws into a quiet 401.
+
+Only the plain `Error` prototype is matched. An `APIError` carries its own status, code,
+detail, and meta, so one whose title happens to be "Unauthorized" falls through to
+`apiErrorMiddleware`. A domain-specific `Error` subclass with the same message also falls
+through so its own handler can respond.
+
+## Parameters
+
+### err
+
+`Error`
+
+### \_req
+
+`Request`
+
+### res
+
+`Response`
+
+### next
+
+`NextFunction`
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/applyReadMask.md

@@ -0,0 +1,15 @@
+> **applyReadMask**(`value`, `mask`): `unknown`
+
+## Parameters
+
+### value
+
+`unknown`
+
+### mask
+
+[`FieldMask`](../interfaces/FieldMask.md)
+
+## Returns
+
+`unknown`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/applySyncMutation.md

@@ -0,0 +1,31 @@
+> **applySyncMutation**(`__namedParameters`): `Promise`\<[`SyncMutationOutcome`](../type-aliases/SyncMutationOutcome.md)\>
+
+Apply a client mutation through the transport-agnostic executors (permissions,
+pre/post hooks, validation) with an atomic idempotency claim. Always finalizes the
+claimed ledger row before returning so duplicate deliveries can read the outcome back.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### mutation
+
+[`SyncMutateRequest`](../interfaces/SyncMutateRequest.md)
+
+#### req?
+
+`Request`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>
+
+The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise.
+
+#### scopeResolver?
+
+[`SyncMutationScopeResolver`](../type-aliases/SyncMutationScopeResolver.md)
+
+#### user
+
+[`User`](../interfaces/User.md)
+
+## Returns
+
+`Promise`\<[`SyncMutationOutcome`](../type-aliases/SyncMutationOutcome.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/applySyncMutationBatch.md

@@ -0,0 +1,37 @@
+> **applySyncMutationBatch**(`__namedParameters`): `Promise`\<[`SyncMutateBatchResponse`](../interfaces/SyncMutateBatchResponse.md)\>
+
+Apply a batch of mutations strictly serially, in array order, reusing
+`applySyncMutation` per item — full reuse of the idempotency ledger, executors,
+permissions, and delta emission. Stops immediately at the first non-ack outcome
+(the user's hard requirement, INV-1): mutations after it are neither attempted nor
+ledgered, and are safe for the client to resend later (INV-3).
+
+Callers MUST run [validateSyncMutationBatch](validateSyncMutationBatch.md) first (oversized/duplicate
+rejection happens before any mutation is attempted); this function assumes the
+batch already passed that check.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### mutations
+
+[`SyncMutateRequest`](../interfaces/SyncMutateRequest.md)[]
+
+#### req?
+
+`Request`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\>
+
+The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise.
+
+#### scopeResolver?
+
+[`SyncMutationScopeResolver`](../type-aliases/SyncMutationScopeResolver.md)
+
+#### user
+
+[`User`](../interfaces/User.md)
+
+## Returns
+
+`Promise`\<[`SyncMutateBatchResponse`](../interfaces/SyncMutateBatchResponse.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/assertWritableStream.md

@@ -0,0 +1,35 @@
+> **assertWritableStream**(`__namedParameters`): `void`
+
+Write-path guard: refuse to file a tenant-scoped document under `tenant:undefined`, a
+stream no client can ever subscribe to, which would leave the document written,
+invisible, and never synced (Task 9.21).
+
+Called from the `_syncSeq` plugin's write hooks, so it sees the EFFECTIVE scope value —
+after any `preCreate` has injected it and before the write commits — on every write
+path, sync mutations and plain REST/model writes alike. That is why the sync mutation
+handler does not try to infer the same thing from the raw request body: a create may
+legitimately omit the field for `preCreate` to supply.
+
+Owner scopes are intentionally not guarded: `ownerId` is conventionally stamped by
+`preCreate`/`IsOwner` plumbing, and an unowned document is still admin-reachable, so
+tightening that is a separate behavioral change.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### collectionTag
+
+`string`
+
+#### doc
+
+`Record`\<`string`, `unknown`\>
+
+#### scope
+
+[`SyncScope`](../type-aliases/SyncScope.md)
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/backfillAdmins.md

@@ -0,0 +1,14 @@
+> **backfillAdmins**(`__namedParameters`): `Promise`\<[`BackfillAdminsResult`](../interfaces/BackfillAdminsResult.md)\>
+
+Assigns a superadmin (or custom) role to users with `admin: true`.
+Dry-run by default — pass `wetRun: true` to persist changes.
+
+## Parameters
+
+### \_\_namedParameters
+
+[`BackfillAdminsOptions`](../interfaces/BackfillAdminsOptions.md)
+
+## Returns
+
+`Promise`\<[`BackfillAdminsResult`](../interfaces/BackfillAdminsResult.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/buildSnapshotScopeFilter.md

@@ -0,0 +1,33 @@
+> **buildSnapshotScopeFilter**(`__namedParameters`): `Record`\<`string`, `unknown`\>
+
+C2: build the server-enforced scope filter for a SINGLE stream. The stream's scope
+value has already been verified against the user's membership set by the caller, so
+this filters to exactly that one value (`{field: value}`), never an `$in`.
+
+Custom-resolver scopes cannot be inverted into a query field, so they still route
+through the required `snapshotFilter` (parameterized by the user, as before).
+
+Task 9.19: for owner/tenant/broadcast scopes a consumer-supplied `snapshotFilter` used
+to be computed and then discarded — silently widening the snapshot past what the
+consumer asked for. It is now composed with the scope clause via `$and` (never
+spread-merged, which would let one clobber the other).
+
+## Parameters
+
+### \_\_namedParameters
+
+#### entry
+
+[`SyncRegistryEntry`](../interfaces/SyncRegistryEntry.md)
+
+#### scopeValue
+
+`string` \| `null`
+
+#### snapshotFilterResult?
+
+`Record`\<`string`, `unknown`\>
+
+## Returns
+
+`Record`\<`string`, `unknown`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/claimSyncSeqs.md

@@ -0,0 +1,36 @@
+> **claimSyncSeqs**(`__namedParameters`): `Promise`\<[`SyncSeqClaim`](../interfaces/SyncSeqClaim.md)\>
+
+C1: atomically claim `count` sequence numbers for a stream AND register them on
+the in-flight registry so the stable frontier can exclude them until committed.
+
+Two modes:
+- **No caller session (the hot path):** one `findOneAndUpdate` does `$inc: {seq}`
+  plus `$push` of a `pending` entry per claimed seq. The write commits separately,
+  so `confirmSyncSeqs` must `$pull` the entries once it lands. Until then the
+  frontier holds below the lowest pending seq.
+- **Caller session present:** the `$inc` and the document write commit atomically
+  in the caller's transaction, so there is no window where a claimed seq is
+  uncommitted — the pending registry is skipped (`registered: false`, nothing to
+  confirm). Frontier logic treats a session-backed claim as already committed.
+
+Retries once on the upsert race (two concurrent first claims for a new stream).
+
+## Parameters
+
+### \_\_namedParameters
+
+#### count?
+
+`number` = `1`
+
+#### session?
+
+`ClientSession` \| `null`
+
+#### stream
+
+`string`
+
+## Returns
+
+`Promise`\<[`SyncSeqClaim`](../interfaces/SyncSeqClaim.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/clearMCPRegistry.md

@@ -0,0 +1,5 @@
+> **clearMCPRegistry**(): `void`
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/clearSyncRegistry.md

@@ -0,0 +1,7 @@
+> **clearSyncRegistry**(): `void`
+
+Clear the registry (for testing).
+
+## Returns
+
+`void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/compactEntryTombstones.md

@@ -0,0 +1,23 @@
+> **compactEntryTombstones**(`entry`): `Promise`\<\{ `markers`: `number`; `tombstones`: `number`; \}\>
+
+Compact tombstones and scope-move markers for one registry entry: hard-delete
+soft-deleted documents whose `updated` (falling back to `created`) predates the
+retention window, plus scope-move markers older than the window.
+
+Task 9.15: the rows are READ before they are deleted so the highest reaped seq per
+stream can be recorded as that stream's `compactedThroughSeq` watermark. That watermark
+is the snapshot's `oldestRetainedSeq`, and it is the only signal a client has that its
+cursor sits below a deletion it can no longer be told about. Deleting without raising it
+silently strands the client on stale data. This is also why `SyncScopeMove` no longer
+carries a TTL index: an expiry that fires outside this function reaps rows with no
+watermark update and ignores the model's `retentionDays`.
+
+## Parameters
+
+### entry
+
+[`SyncRegistryEntry`](../interfaces/SyncRegistryEntry.md)
+
+## Returns
+
+`Promise`\<\{ `markers`: `number`; `tombstones`: `number`; \}\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/compactTombstones.md

@@ -0,0 +1,7 @@
+> **compactTombstones**(): `Promise`\<[`CompactTombstonesResult`](../interfaces/CompactTombstonesResult.md)\>
+
+Compact tombstones across every registered sync model.
+
+## Returns
+
+`Promise`\<[`CompactTombstonesResult`](../interfaces/CompactTombstonesResult.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/computeStableFrontier.md

@@ -0,0 +1,22 @@
+> **computeStableFrontier**(`__namedParameters`): `Promise`\<`number`\>
+
+C1: the stable frontier for a stream — the highest seq below which no claim is
+uncommitted. A cursor (snapshot or delta) may advance to seq N only when N is at
+or below this value, so no committed document is ever permanently skipped.
+
+frontier = `min(live pending.seq) - 1`, or the head `seq` when no live pending
+entries remain. A pending entry older than [PENDING\_CLAIM\_LEASE\_MS](../variables/PENDING_CLAIM_LEASE_MS.md) is
+considered abandoned (crashed writer): it is excluded from the min AND `$pull`ed
+opportunistically so a crash cannot freeze the frontier forever.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### stream
+
+`string`
+
+## Returns
+
+`Promise`\<`number`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/confirmSyncSeqs.md

@@ -0,0 +1,30 @@
+> **confirmSyncSeqs**(`__namedParameters`): `Promise`\<[`SyncSeqConfirmResult`](../interfaces/SyncSeqConfirmResult.md)\>
+
+C1: confirm that the writes owning `seqs` on `stream` have committed, clearing
+their pending registry entries so the stable frontier can advance past them.
+A no-op when `seqs` is empty (a session-backed claim registered nothing). Runs
+after the document write commits (`post("save")` / query-write post hook); a
+`$pull` failure is logged by the caller and left to age out via the lease.
+
+Returns whether anything was actually cleared so callers can detect a reaped
+lease — see [SyncSeqConfirmResult](../interfaces/SyncSeqConfirmResult.md).
+
+## Parameters
+
+### \_\_namedParameters
+
+#### seqs
+
+`number`[]
+
+#### session?
+
+`ClientSession` \| `null`
+
+#### stream
+
+`string`
+
+## Returns
+
+`Promise`\<[`SyncSeqConfirmResult`](../interfaces/SyncSeqConfirmResult.md)\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createAccess.md

@@ -0,0 +1,17 @@
+> **createAccess**\<`S`\>(`options`): [`TerrenoAccess`](../interfaces/TerrenoAccess.md)\<`S`\>
+
+## Type Parameters
+
+### S
+
+`S` *extends* [`Statements`](../type-aliases/Statements.md)
+
+## Parameters
+
+### options
+
+[`AccessOptions`](../interfaces/AccessOptions.md)\<`S`\>
+
+## Returns
+
+[`TerrenoAccess`](../interfaces/TerrenoAccess.md)\<`S`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createBetterAuthValidator.md

@@ -0,0 +1,16 @@
+> **createBetterAuthValidator**(`options`): [`SocketAuthValidator`](../type-aliases/SocketAuthValidator.md)
+
+Better Auth session validator: treats the handshake token as a Better Auth session token
+and validates it via `auth.api.getSession` (the same lookup the HTTP session middleware
+uses). The token is presented both as a bearer Authorization header (for the Better Auth
+bearer plugin) and as the session cookie, so either transport configuration works.
+
+## Parameters
+
+### options
+
+[`BetterAuthSocketOptions`](../interfaces/BetterAuthSocketOptions.md)
+
+## Returns
+
+[`SocketAuthValidator`](../type-aliases/SocketAuthValidator.md)

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createIsPermitted.md

@@ -0,0 +1,19 @@
+> **createIsPermitted**\<`S`\>(`__namedParameters`): (`permissions`) => [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>
+
+## Type Parameters
+
+### S
+
+`S` *extends* [`Statements`](../type-aliases/Statements.md)
+
+## Parameters
+
+### \_\_namedParameters
+
+#### can
+
+(`args`) => `Promise`\<[`AccessResult`](../interfaces/AccessResult.md)\>
+
+## Returns
+
+(`permissions`) => [`PermissionMethod`](../type-aliases/PermissionMethod.md)\<`unknown`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createLegacyJwtValidator.md

@@ -0,0 +1,37 @@
+> **createLegacyJwtValidator**(`tokenSecret`, `issuer?`): [`SocketAuthValidator`](../type-aliases/SocketAuthValidator.md)
+
+Legacy JWT validator: wraps the `@thream/socketio-jwt` middleware so its observable
+behavior (token format requirements, secret verification, `decodedToken` payload,
+`UnauthorizedError` shapes) is identical to the previous direct `io.use(authorize(...))`.
+
+D1: `@thream/socketio-jwt`'s `authorize()` has no `issuer` option — it only verifies
+the signature/algorithm — so without this the socket path silently accepted a
+validly-signed token issued for a DIFFERENT `TOKEN_ISSUER` (e.g. a token from another
+environment sharing the same `TOKEN_SECRET`), unlike the HTTP path's
+`jwt.verify(token, secret, {issuer})`. When `issuer` is provided, the post-verify
+`onAuthentication` hook checks `decodedToken.iss` and rejects a mismatch with the
+same `UnauthorizedError` shape the signature-verification failure path uses, so
+callers cannot distinguish "bad signature" from "wrong issuer" from the error alone
+(matching the non-disclosure posture the HTTP path also has).
+
+`issuer` may be a plain string or a thunk (`() => string | undefined`) resolved on
+EVERY handshake — the HTTP path's `jwt.verify` reads `process.env.TOKEN_ISSUER` fresh
+per request rather than once at server startup, and a static string captured once at
+`RealtimeApp.onServerCreated()` time would go stale if `TOKEN_ISSUER` changes later
+(e.g. test suites that mutate it between fixtures). Pass a thunk to preserve that
+per-request freshness; a plain string is still supported for callers who intentionally
+want a fixed value.
+
+## Parameters
+
+### tokenSecret
+
+`string`
+
+### issuer?
+
+`string` \| (() => `string` \| `undefined`)
+
+## Returns
+
+[`SocketAuthValidator`](../type-aliases/SocketAuthValidator.md)

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createRbacAuditModel.md

@@ -0,0 +1,11 @@
+> **createRbacAuditModel**(`connection`): `RbacAuditModel`
+
+## Parameters
+
+### connection
+
+`Connection`
+
+## Returns
+
+`RbacAuditModel`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createRbacRoleModel.md

@@ -0,0 +1,11 @@
+> **createRbacRoleModel**(`connection`): [`RbacRoleModel`](../type-aliases/RbacRoleModel.md)
+
+## Parameters
+
+### connection
+
+`Connection`
+
+## Returns
+
+[`RbacRoleModel`](../type-aliases/RbacRoleModel.md)

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createRequireAccess.md

@@ -0,0 +1,19 @@
+> **createRequireAccess**\<`S`\>(`__namedParameters`): (`permissions`, `options?`) => (`req`, `_res`, `next`) => `Promise`\<`void`\>
+
+## Type Parameters
+
+### S
+
+`S` *extends* [`Statements`](../type-aliases/Statements.md)
+
+## Parameters
+
+### \_\_namedParameters
+
+#### can
+
+(`args`) => `Promise`\<[`AccessResult`](../interfaces/AccessResult.md)\>
+
+## Returns
+
+(`permissions`, `options?`) => (`req`, `_res`, `next`) => `Promise`\<`void`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/createSocketAuthMiddleware.md

@@ -0,0 +1,38 @@
+> **createSocketAuthMiddleware**(`__namedParameters`): (`socket`, `next`) => `void`
+
+Build the Socket.io auth middleware from a validator chain: validators run in order and
+the first success wins; when all fail the connection is rejected with the last error.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### betterAuth?
+
+[`BetterAuthSocketOptions`](../interfaces/BetterAuthSocketOptions.md)
+
+Enables the Better Auth session validator after the legacy JWT validator.
+
+#### extraValidators?
+
+[`SocketAuthValidator`](../type-aliases/SocketAuthValidator.md)[] = `[]`
+
+Additional validators appended to the chain (after JWT and Better Auth).
+
+#### issuer?
+
+`string` \| (() => `string` \| `undefined`)
+
+JWT issuer to require (D1 parity with the HTTP path's `jwt.verify(token, secret,
+{issuer})`). Omitted means no issuer check, matching pre-D1 behavior. A thunk is
+resolved fresh on every handshake (see [createLegacyJwtValidator](createLegacyJwtValidator.md)).
+
+#### tokenSecret
+
+`string`
+
+Secret for the legacy JWT validator (same handling as before the refactor).
+
+## Returns
+
+(`socket`, `next`) => `void`

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/defaultResponseHandler.md

@@ -0,0 +1,32 @@
+> **defaultResponseHandler**\<`T`\>(`doc`, `method`, `request`, `options`): `Promise`\<`Partial`\<`T`\> \| (`Partial`\<`T`\> \| `undefined`)[] \| `null` \| `undefined`\>
+
+Default response handler for modelRouter. Calls toObject on each doc and returns the result,
+using transformers.serializer if provided.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### doc
+
+`Document`\<`unknown`, `unknown`, `unknown`, `Record`\<`string`, `any`\>, \{ \}\> & `T` \| `Document`\<`unknown`, `unknown`, `unknown`, `Record`\<`string`, `any`\>, \{ \}\> & `T`[] \| `null`
+
+### method
+
+`"read"` \| `"create"` \| `"list"` \| `"update"`
+
+### request
+
+`Request`
+
+### options
+
+[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`T`\>
+
+## Returns
+
+`Promise`\<`Partial`\<`T`\> \| (`Partial`\<`T`\> \| `undefined`)[] \| `null` \| `undefined`\>

package/dist/docs/versioned/57.1.0/reference/generated/api/functions/defineScope.md

@@ -0,0 +1,17 @@
+> **defineScope**\<`TDoc`\>(`def`): [`ResourceScope`](../interfaces/ResourceScope.md)\<`TDoc`\>
+
+## Type Parameters
+
+### TDoc
+
+`TDoc`
+
+## Parameters
+
+### def
+
+[`ScopeDefinition`](../interfaces/ScopeDefinition.md)\<`TDoc`\>
+
+## Returns
+
+[`ResourceScope`](../interfaces/ResourceScope.md)\<`TDoc`\>