lecodes-sdk 0.19.0

package/dist/types/server/auth/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared shapes of the auth layer (docs/backend-plan.md §3.4). Two sides meet through them:
+ *  - the BUNDLE side (`auth` global, ./global.ts) — what `*.server.ts` code calls;
+ *  - the HOST side (./host.ts) — sessions, email codes and OAuth binding, run by the runner with the
+ *    project's db handle and the platform's secrets. Installed on `globalThis.__lecodesAuth`.
+ */
+import type { RequestContext } from "../context";
+import type { AuthProvider } from "./models";
+/** The built-in user row — what `auth.user` is typed with (custom fields exist at runtime; select them via `db.user`). */
+export type AuthUser = {
+    id: number;
+    email: string | null;
+    name: string | null;
+    avatar: string | null;
+    role: string;
+    createdAt: number;
+};
+/** Per-request auth state, resolved by the host before the endpoint runs (`RequestContext.auth`). */
+export type AuthState = {
+    sessionId: number;
+    userId: number | null;
+    user: AuthUser | null;
+    /** A token to hand back to the client in this response (a new guest session, or a rotation). */
+    issuedToken?: string;
+};
+/** What an OAuth provider hands the runner after a successful web sign-in. */
+export type OAuthProfile = {
+    sub: string;
+    email?: string | null;
+    emailVerified?: boolean;
+    name?: string | null;
+    avatar?: string | null;
+};
+/** A credential a NATIVE provider SDK produced in the app (client plugin `OAuth.signIn`): an access token
+ *  (Yandex, VK ID) or an OpenID identity token (Google, Apple). Verified server-side, never trusted as-is. */
+export type OAuthCredential = {
+    accessToken?: string;
+    idToken?: string;
+    name?: string | null;
+    email?: string | null;
+};
+/** Host operations the bundle's `auth` global forwards to (all request-scoped through `ctx`). */
+export type AuthOps = {
+    email: {
+        sendCode(ctx: RequestContext, email: string): Promise<void>;
+        verify(ctx: RequestContext, email: string, code: string): Promise<AuthUser>;
+    };
+    oauth: {
+        url(ctx: RequestContext, provider: Exclude<AuthProvider, "email">): Promise<string>;
+        signIn(ctx: RequestContext, provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser>;
+    };
+    signIn(ctx: RequestContext, userId: number): Promise<AuthUser>;
+    signOut(ctx: RequestContext): Promise<void>;
+    /** `db.session` filtered to the current user's sessions (or just this device's, when signed out). */
+    sessions(ctx: RequestContext): any;
+};

package/dist/types/server/channel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Server side of channels (docs/backend-plan.md §3.3): typed pub/sub, server → client only.
+ *
+ *   type ChatEvents = { message: { from: string; text: string }; typing: { from: string } }
+ *   export const chat = channel<ChatEvents>({ onJoin: room => { auth.requireUser() } })
+ *   chat.publish(room, "message", { from, text })
+ *
+ * A channel's identity is its export (`<path>#<name>`), assigned by the runtime when the bundle is
+ * loaded (`loadServerModules`); `publish` before that is an error. Delivery goes through the
+ * `globalThis.__lecodesPublish` seam the runner installs (same reason as ./context.ts: the bundle
+ * carries its own SDK copy).
+ */
+export type ChannelEvents = Record<string, unknown>;
+export type ChannelOptions = {
+    /** Called when a client subscribes to `topic`; throw (e.g. `ApiError(403)`) to refuse. */
+    onJoin?: (topic: string) => void | Promise<void>;
+};
+export interface Channel<E extends ChannelEvents> {
+    readonly options: ChannelOptions;
+    /** Deliver `event` with `payload` to every subscriber of `topic` (at-most-once). */
+    publish<K extends keyof E & string>(topic: string, event: K, payload: E[K]): void;
+}
+type Publisher = (channelId: string, topic: string, event: string, payload: unknown) => void;
+/** Host hook (runner / test harness): where `publish` delivers to. */
+export declare const setChannelPublisher: (publisher: Publisher | null) => void;
+export declare const channel: <E extends ChannelEvents>(options?: ChannelOptions) => Channel<E>;
+export declare const isChannel: (v: unknown) => v is Channel<any>;
+export {};

package/dist/types/server/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Request context for server code. The runner keeps the current request in an AsyncLocalStorage
+ * and exposes it through `globalThis.__lecodesRequest` — a *global* seam on purpose: the compiled
+ * server bundle carries its own copy of this module (chisel bundles the SDK in), so the host can't
+ * hand it a value by import. `request` reads through that seam; outside a request (module load,
+ * timers after the response) every member is undefined.
+ */
+export type RequestContext = {
+    /** Endpoint id `<path>#<export>` (or the channel id for `onJoin`). */
+    id: string;
+    headers: Record<string, string>;
+    ip?: string;
+    /** Bearer session token as sent by the client transport (raw; auth resolves it). */
+    sessionToken?: string;
+    /** Set by the auth runtime after resolving the token — read via `auth.*`, not here. */
+    auth?: unknown;
+};
+type Provider = () => RequestContext | undefined;
+/** Host hook (runner / test harness): install the current-request provider. */
+export declare const setRequestProvider: (provider: Provider | null) => void;
+/** The current request (server global). Undefined members outside a request. */
+export declare const request: {
+    readonly id: string | undefined;
+    readonly headers: Record<string, string>;
+    readonly ip: string | undefined;
+};
+export {};

package/dist/types/server/db/defineDb.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `model({...})` + `defineDb({ User, Post })` — the schema registry and the typed db handle.
+ *
+ * Runtime responsibilities: validate relation names, resolve `t.many()` back-fields, emit the `.marci`
+ * schema text (`db.$schema`), and turn collection calls into lazy `Op`s over a `MarciTransport`
+ * (`marcidb-embedded` handle, HTTP client, or a test fake). The transport is either passed to
+ * `defineDb(models, { transport })` or provided by the host through `setDbTransport()` — user code
+ * never sees a connection string.
+ */
+import type { FieldDef } from "./fields";
+import { type MarciTransport } from "./marci/query";
+import type { Db, Fields, Model, Schema, ValidateRefs } from "./types";
+export declare const model: <F extends Fields>(fields: F) => Model<F>;
+/** Host hook: the runner/dev-server installs the project's transport before loading user code. */
+export declare const setDbTransport: (transport: MarciTransport | null) => void;
+/**
+ * Every `defineDb` call registers its handle here so the host finds the schema whether or not the
+ * project exports `db` (`const db = defineDb(...)` used only inside endpoints is the common case).
+ * The host reads and clears the list after evaluating a bundle (`loadServerModules`).
+ */
+export declare const takeRegisteredDbs: () => Db<any>[];
+/** A reference to a previous operation's result inside `$transaction` (resolved server-side): `ref("0.id")`. */
+export declare const ref: (path: string) => any;
+type ModelMeta = {
+    name: string;
+    fields: Record<string, FieldDef>;
+    idKeys: string[];
+    /** id is a single uuid key we generate on insert. */
+    uuidId: boolean;
+};
+export declare const toMarci: (metas: Record<string, ModelMeta>) => string;
+export type DefineDbOptions = {
+    transport?: MarciTransport;
+};
+export declare const defineDb: <const S extends Schema>(declared: S & ValidateRefs<S>, options?: DefineDbOptions) => Db<S>;
+export {};

package/dist/types/server/db/fields.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `t` — field builders for `model({...})`. Each builder returns an immutable `Field` carrying a runtime
+ * `FieldDef` (what `.marci` is emitted from) and two phantom type parameters: the TS value type and a
+ * `FieldMeta` record (kind / optional / default / …) that `defineDb`'s type layer projects into row,
+ * insert, update, select and where types. Chained modifiers return a NEW field (builders are never
+ * mutated), so `const s = t.string(); { a: s, b: s.optional() }` behaves as expected.
+ */
+import type { JsonValue } from "./marci/query";
+export type ScalarKind = "string" | "int" | "float" | "bool" | "date" | "uuid" | "";
+export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list";
+export type OnDelete = "cascade" | "setNull" | "restrict";
+/** Phantom metadata — the type-level twin of `FieldDef`. */
+export type FieldMeta = {
+    kind: FieldKind;
+    scalar: ScalarKind;
+    optional: boolean;
+    hasDefault: boolean;
+    array: boolean;
+    isId: boolean;
+    /** Related model name for one/many/list; "" otherwise. */
+    model: string;
+};
+type DefaultMeta = {
+    kind: "scalar";
+    scalar: "";
+    optional: false;
+    hasDefault: false;
+    array: false;
+    isId: false;
+    model: "";
+};
+export type Meta<O extends Partial<FieldMeta>> = {
+    [P in keyof FieldMeta]: P extends keyof O ? O[P] : DefaultMeta[P];
+};
+type SetMeta<M extends FieldMeta, K extends keyof FieldMeta, V> = {
+    [P in keyof FieldMeta]: P extends K ? V : M[P];
+};
+/** Runtime field definition — everything the `.marci` emitter and the runtime need. */
+export type FieldDef = {
+    kind: FieldKind;
+    scalar?: ScalarKind;
+    optional: boolean;
+    unique: boolean;
+    index: boolean;
+    hasDefault: boolean;
+    default?: unknown;
+    array: boolean;
+    isId: boolean;
+    onDelete?: OnDelete;
+    fulltext?: "multi" | "english" | "russian";
+    vector?: {
+        size: number;
+        metric: "cosine" | "euclidean";
+    };
+    /** enum */
+    values?: readonly string[];
+    /** struct */
+    fields?: Record<string, Field<any, any>>;
+    /** one / many / list */
+    model?: string;
+    /** many: the field on the related model that holds the reference (`@bind`); resolved by defineDb when omitted. */
+    back?: string;
+};
+type DefaultOf<T, M extends FieldMeta> = M["scalar"] extends "date" ? "now" | number : M["array"] extends true ? T[] : T;
+export interface Field<T, M extends FieldMeta = FieldMeta> {
+    /** phantom (type-level only — never set at runtime) */ readonly __t?: T;
+    /** phantom (type-level only — never set at runtime) */ readonly __m?: M;
+    readonly def: FieldDef;
+    /** Nullable column (`String?`). */
+    optional(): Field<T, SetMeta<M, "optional", true>>;
+    /** `@unique` (on a relation: one-to-one). */
+    unique(): Field<T, M>;
+    /** `@index` — used by `$where`, `$order`, aggregations. */
+    index(): Field<T, M>;
+    /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */
+    default(value: DefaultOf<T, M>): Field<T, SetMeta<M, "hasDefault", true>>;
+    /** Primitive list (`String[]`). */
+    array(): Field<T, SetMeta<M, "array", true>>;
+    /** `@id` — primary key (several → composite). A field literally named `id` is the key implicitly. */
+    id(): Field<T, SetMeta<M, "isId", true>>;
+    /** Referential policy for `t.one()` (defaults: required → restrict, optional → setNull). */
+    onDelete(policy: OnDelete): Field<T, M>;
+    /** `@fulltext(...)` module index on a string field; query with `$search`. */
+    fulltext(lang?: "multi" | "english" | "russian"): Field<T, M>;
+    /** `Float[n] @vector(metric)` — nearest-neighbour index; query with `$near`. */
+    vector(size: number, metric?: "cosine" | "euclidean"): Field<T, M>;
+}
+export declare const t: {
+    string: () => Field<string, Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** 64-bit signed integer. */
+    int: () => Field<number, Meta<{
+        kind: "scalar";
+        scalar: "int";
+    }>>;
+    /** 64-bit float. */
+    float: () => Field<number, Meta<{
+        kind: "scalar";
+        scalar: "float";
+    }>>;
+    bool: () => Field<boolean, Meta<{
+        kind: "scalar";
+        scalar: "bool";
+    }>>;
+    /** Epoch milliseconds — reads and writes as `number`. */
+    date: () => Field<number, Meta<{
+        kind: "scalar";
+        scalar: "date";
+    }>>;
+    /** UUID string (16 bytes in storage). On an `id` field the runtime generates it on insert. */
+    uuid: () => Field<string, Meta<{
+        kind: "scalar";
+        scalar: "uuid";
+    }>>;
+    /** Any JSON value; `J` is TS-only (marcidb stores it schemaless). Filter by dot-path in `$where`. */
+    json: <J = JsonValue>() => Field<J, Meta<{
+        kind: "json";
+    }>>;
+    /** String enum: `t.enum("draft", "published")`. */
+    enum: <const V extends readonly [string, ...string[]]>(...values: V) => Field<V[number], Meta<{
+        kind: "enum";
+    }>>;
+    /** Owned nested object (marcidb `struct`): created/updated with the parent, no id of its own. */
+    struct: <F extends Record<string, Field<any, any>>>(fields: F) => Field<F, Meta<{
+        kind: "struct";
+    }>>;
+    /** Reference to one row of `model` (by id). Required unless `.optional()`. */
+    one: <N extends string>(model: N) => Field<never, Meta<{
+        kind: "one";
+        model: N;
+    }>>;
+    /** Reverse side of a `t.one()` on `model` (the field is inferred when unambiguous). Read-only list. */
+    many: <N extends string>(model: N, backField?: string) => Field<never, Meta<{
+        kind: "many";
+        model: N;
+    }>>;
+    /** Ordered relation list stored inline (`@list`) — hand-arranged collections, duplicates allowed. */
+    list: <N extends string>(model: N) => Field<never, Meta<{
+        kind: "list";
+        model: N;
+    }>>;
+};
+export type T = typeof t;
+export {};

package/dist/types/server/db/index.d.ts

@@ -0,0 +1,6 @@
+export { t } from "./fields";
+export type { Field, FieldDef, FieldMeta } from "./fields";
+export { model, defineDb, ref, setDbTransport, toMarci } from "./defineDb";
+export type { DefineDbOptions } from "./defineDb";
+export type { Db, Model, Schema, Row, Id, Insert, Update, Select, Where, Query, QueryObject, Result, Collection, ScalarSelect, Types } from "./types";
+export type { Op, MarciOp, MarciTransport, JsonValue, Sub } from "./marci/query";

package/dist/types/server/db/marci/query.d.ts

@@ -0,0 +1,326 @@
+export type ServiceKeys = "$where" | "$order" | "$limit" | "$skip" | "$cursor";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type AggregateKeys = {
+    $count: true;
+} | {
+    $sum: string;
+} | {
+    $avg: string;
+} | {
+    $min: string;
+} | {
+    $max: string;
+};
+export type GetResult<TModel, TSelect> = TModel extends any ? {
+    -readonly [K in keyof Omit<TSelect, ServiceKeys> as TSelect[K] extends false | undefined ? never : K extends keyof TModel ? K : never]: K extends keyof TModel ? TSelect[K] extends true ? TModel[K] : TSelect[K] extends Record<string, any> ? TModel[K] extends readonly object[] ? TSelect[K] extends AggregateKeys ? AggregateResult<NonNullable<TModel[K][number]>, TSelect[K]> : GetResult<NonNullable<TModel[K][number]>, TSelect[K]>[] : GetResult<NonNullable<TModel[K]>, TSelect[K]> | Extract<TModel[K], null> : TModel[K] : never;
+} : never;
+export type RefUpdate<I> = {
+    "$connect"?: I;
+};
+export type RefUpdateStruct<I, U> = {
+    "$update"?: U;
+    "$ensure"?: I;
+    "$set"?: I;
+};
+/** Relation to independent rows — link operations only, the rows themselves are never created
+ * or deleted. `$set` replaces link membership with exactly the given set (missing links are
+ * disconnected, new ones connected); `$connect` links (idempotent); `$remove` unlinks. */
+export type RefListUpdate<I> = {
+    "$set"?: I[];
+    "$connect"?: I | I[];
+    "$remove"?: I | I[];
+};
+/** `@list` relation: an ordered inline id array — a sequence, so the same id may appear several
+ * times. `$set` replaces the whole array (also the reorder operation); `$connect` appends at the
+ * end (an already-present id gains another occurrence); `$connectUnique` appends only ids not
+ * already present; `$remove` removes every occurrence. */
+export type RefListUpdateOrdered<I> = {
+    "$set"?: I[];
+    "$connect"?: I | I[];
+    "$connectUnique"?: I | I[];
+    "$remove"?: I | I[];
+};
+/** Owned (struct) list: the children live and die with the parent. `$push` creates children,
+ * `$update` edits single children in place (each item is the child's id fields — the shape
+ * query results return — plus the changes under `data`), `$remove` deletes children by id,
+ * `$set` replaces all children (deletes the current ones, creates the new). */
+export type RefListUpdateStruct<I, U, Id> = {
+    "$push"?: I | I[];
+    "$update"?: (Id & {
+        data: U;
+    }) | (Id & {
+        data: U;
+    })[];
+    "$remove"?: Id | Id[];
+    "$set"?: I[];
+};
+/** Variable-length primitive array — a sequence, so the same value may appear several times.
+ * `$push` appends at the end (duplicates kept); `$pushUnique` appends only values not already
+ * present; `$remove` removes every occurrence; `$set` replaces the whole array (also the
+ * positional-edit path — send the full new array). One operator per update. */
+export type PrimitiveListUpdate<T> = {
+    "$set"?: T[];
+    "$push"?: T | T[];
+    "$pushUnique"?: T | T[];
+    "$remove"?: T | T[];
+};
+export type Never<T> = {
+    [K in keyof T]?: never;
+};
+export type FieldOps = {
+    "$eq": unknown;
+    "$ne": unknown;
+    "$not": unknown;
+    "$in": unknown;
+    "$notIn": unknown;
+    "$gt": unknown;
+    "$gte": unknown;
+    "$lt": unknown;
+    "$lte": unknown;
+    "$startsWith": unknown;
+    "$includes": unknown;
+    "$every": unknown;
+    "$some": unknown;
+    "$none": unknown;
+    "$near": unknown;
+    "$search": unknown;
+};
+export type Only<K extends keyof FieldOps, V> = {
+    [P in K]: V;
+} & Never<Omit<FieldOps, K>>;
+export type WhereValue<T> = (T & Never<{
+    "$and": unknown;
+    "$or": unknown;
+    "$not": unknown;
+}>) | ({
+    "$and": WhereValue<T>[];
+} & Never<T> & Never<{
+    "$or": unknown;
+    "$not": unknown;
+}>) | ({
+    "$or": WhereValue<T>[];
+} & Never<T> & Never<{
+    "$and": unknown;
+    "$not": unknown;
+}>) | ({
+    "$not": WhereValue<T>;
+} & Never<T> & Never<{
+    "$and": unknown;
+    "$or": unknown;
+}>);
+export type ValueOps<T> = {
+    "$eq"?: T;
+    "$ne"?: T;
+    "$not"?: T;
+    "$in"?: T[];
+    "$notIn"?: T[];
+};
+export type NumOps<T> = {
+    "$gt"?: T;
+    "$gte"?: T;
+    "$lt"?: T;
+    "$lte"?: T;
+};
+export type StrOps = {
+    "$includes"?: string;
+    "$startsWith"?: string;
+};
+export type CompareValue<T> = T | (ValueOps<T> & Never<Omit<FieldOps, keyof ValueOps<T>>>);
+export type CompareNumValue<T> = ValueOps<T> & NumOps<T> & Never<Omit<FieldOps, keyof ValueOps<T> | keyof NumOps<T>>>;
+export type CompareStrValue<T> = ValueOps<T> & StrOps & Never<Omit<FieldOps, keyof ValueOps<T> | keyof StrOps>>;
+export type UpdateNumValue = {
+    "$increment": number;
+};
+export type JsonType = "string" | "number" | "boolean" | "object" | "array" | "null";
+export type JsonCondition = JsonValue | {
+    "$eq"?: JsonValue;
+    "$ne"?: JsonValue;
+    "$not"?: JsonValue;
+    "$gt"?: number | string;
+    "$gte"?: number | string;
+    "$lt"?: number | string;
+    "$lte"?: number | string;
+    "$in"?: JsonValue[];
+    "$notIn"?: JsonValue[];
+    "$startsWith"?: string;
+    "$includes"?: string;
+    "$contains"?: JsonValue;
+    "$exists"?: boolean;
+    "$type"?: JsonType;
+};
+export type JsonPathWhere = {
+    [path: string]: JsonCondition;
+};
+export type CompareRefValue<T> = T | Only<"$not", T>;
+export type CompareRefListValue<T> = Only<"$every", T> | Only<"$some", T> | Only<"$none", T>;
+export type VectorSearch = {
+    vector: number[];
+    k?: number;
+    threshold?: number;
+};
+export type FullTextSearch = string | {
+    query: string;
+    limit?: number;
+};
+export type CustomSearch = Record<string, any>;
+export type CustomSearchValue<P> = Only<"$near", P> | Only<"$search", P>;
+export type AggregateResult<TModel, T> = (T extends {
+    $count: true;
+} ? {
+    count: number;
+} : {}) & (T extends {
+    $sum: string;
+} ? {
+    sum: number | null;
+} : {}) & (T extends {
+    $avg: string;
+} ? {
+    avg: number | null;
+} : {}) & (T extends {
+    $min: infer F;
+} ? {
+    min: (F extends keyof TModel ? TModel[F] : never) | null;
+} : {}) & (T extends {
+    $max: infer F;
+} ? {
+    max: (F extends keyof TModel ? TModel[F] : never) | null;
+} : {});
+declare const __op: unique symbol;
+export type Op<T> = PromiseLike<T> & {
+    readonly [__op]: T;
+};
+export type MarciOp = {
+    model: string;
+    action: string;
+    query?: any;
+    data?: any;
+    id?: any;
+};
+export type MarciTransport = {
+    exec(op: MarciOp): Promise<any>;
+    batch(ops: MarciOp[]): Promise<any[]>;
+};
+export type ModelTypes = {
+    name: string;
+    model: any;
+    id: Record<string, any>;
+    /** What an empty select returns: id + every scalar field, as a `{ field: true }` shape. */
+    scalars: Record<string, true>;
+    select: Record<string, any>;
+    query: Record<string, any>;
+    where: any;
+    order: Record<string, any>;
+    insert: any;
+    update: any;
+    aggregate: Record<string, any>;
+    reindex: boolean;
+};
+declare const __sub: unique symbol;
+declare const __sel: unique symbol;
+export type Sub<Name extends string, Shape = any> = {
+    readonly [__sub]: Name;
+    readonly [__sel]: Shape;
+};
+export type Effective<T extends ModelTypes, S> = [Exclude<keyof S, ServiceKeys>] extends [never] ? T["scalars"] : S;
+export type Resolve<S> = S extends {
+    readonly [__sel]: infer X;
+} ? Resolve<X> : S extends object ? {
+    [K in keyof S]: K extends `$${string}` ? S[K] : Resolve<S[K]>;
+} : S;
+export type Rows<T extends ModelTypes, Sel> = GetResult<T["model"], Resolve<Effective<T, Sel>>>;
+export type BareId<I> = I extends {
+    id: infer V;
+} ? V : never;
+export type IdArg<I> = I | BareId<I>;
+/**
+ * A lazy, immutable query over one model — `db.user` itself is one. Every clause returns a new query, so
+ * queries compose (`const active = db.user.where({ active: true })`). `await` runs it as `findMany`; passing
+ * it to `$transaction` batches it; placing it in another query's select makes it a sub-select. `Sel` is the
+ * projection: id + scalars until `select(...)` sets a shape.
+ */
+export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends PromiseLike<Rows<T, Sel>[]> {
+    readonly [__op]: Rows<T, Sel>[];
+    readonly [__sub]: T["name"];
+    readonly [__sel]: Effective<T, Sel>;
+    /** Filter (marcidb `$where`). Repeated calls are ANDed. */
+    where(where: T["where"]): Query<T, Sel>;
+    /** Sort by one field: `order("age", "desc")` or `order({ age: "desc" })`. */
+    order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>;
+    order(order: T["order"]): Query<T, Sel>;
+    limit(n: number): Query<T, Sel>;
+    skip(n: number): Query<T, Sel>;
+    /** Keyset cursor: rows strictly after this id in the current order (`$cursor`). */
+    after(id: IdArg<T["id"]>): Query<T, Sel>;
+    /**
+     * The projection. Values are `true`, a nested shape, or a sub-query of the relation's model
+     * (`posts: db.post.limit(5)`, `posts: db.post.where({ published: true }).count()`). No argument, or no
+     * field keys, selects id + every scalar. `$`-clauses are accepted here too (the object form).
+     */
+    select<S extends T["query"] = T["scalars"]>(shape?: S): Query<T, S>;
+    /** The first matching row or `null`. */
+    first(): Op<Rows<T, Sel> | null>;
+    /** Row count; inside a select it becomes `{ count }` for the relation. */
+    count(): Op<number> & Sub<T["name"], {
+        $count: true;
+    }>;
+    /** @deprecated pass the filter through the chain: `db.user.where(w).count()` (removed in the next minor). */
+    count(query: {
+        $where?: T["where"];
+    }): Op<number> & Sub<T["name"], {
+        $count: true;
+    }>;
+    aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>;
+    insert(data: T["insert"]): Op<T["id"]>;
+    update(id: IdArg<T["id"]>, data: T["update"]): Op<void>;
+    /** Applies `data` to every row the chain's `where` matches (all rows without one); resolves to the number of rows. */
+    updateMany(data: T["update"]): Op<number>;
+    /** @deprecated pass the filter through the chain: `db.user.where(w).updateMany(data)` (removed in the next minor). */
+    updateMany(query: {
+        $where?: T["where"];
+    }, data: T["update"]): Op<number>;
+    delete(id: IdArg<T["id"]>): Op<void>;
+    /**
+     * Deletes every row the chain's `where` matches (cascades apply, as for `delete`); resolves to the number
+     * deleted. Refuses to run without a `where` — write `.where({})` to mean "every row".
+     */
+    deleteMany(): Op<number>;
+    /** @deprecated use `.select(query)` — it takes the same object, merged with the chain (removed in the next minor). */
+    findMany<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q>[]>;
+    /** @deprecated use `.select(query).first()` (removed in the next minor). */
+    findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>;
+}
+/** `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index. */
+export type Collection<T extends ModelTypes> = Query<T> & (T["reindex"] extends true ? {
+    reindex(): Op<{
+        ok: boolean;
+        indexed: number;
+    }>;
+} : {});
+/** One field of a model, in slot order: `n` name, `k` key | body | one | many, `m` the relation's target model. */
+export type FieldDesc = {
+    n: string;
+    k: "key" | "body" | "one" | "many";
+    t?: string | null;
+    m?: string;
+};
+/** Model name → its field descriptors (structs included, as relation targets). */
+export type ModelsMeta = Record<string, readonly FieldDesc[]>;
+export type QueryLayerOptions = {
+    models: ModelsMeta;
+    /** Runs one operation (a query, or a write) and resolves its result. */
+    run(op: MarciOp): Promise<any>;
+    /** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
+    prepareInsert?(model: string, data: any): any;
+};
+/**
+ * The query builder over a set of models and a `run` function. Returns `op(descriptor)` — a lazy operation
+ * (`await` runs it, `$transaction` takes its `__op`) — and `collection(model)`, the immutable `db.<model>`
+ * root query. Transport-agnostic: the generated client and the embedded/HTTP transports supply `run`.
+ */
+export declare function createQueryLayer(options: QueryLayerOptions): {
+    op: (descriptor: MarciOp) => any;
+    collection: (model: string) => any;
+};
+export {};