@pylonsync/sdk 0.3.291 → 0.3.293

package/dist/index.d.ts

@@ -0,0 +1,949 @@
+export type RouteMode = "static" | "server" | "live" | "ssr";
+export type FieldType = "string" | "int" | "float" | "bool" | "datetime" | "richtext" | `id(${string})`;
+/**
+ * CRDT container override for a field. Wire format is the kebab-case
+ * string each variant maps to (`"text"`, `"counter"`, `"movable-list"`,
+ * etc.). Mirror of `pylon_kernel::CrdtAnnotation` on the Rust side.
+ *
+ * - `"text"` upgrades a `string` to LoroText (collaborative
+ *   character-level merge instead of LWW).
+ * - `"counter"` flips an `int` / `float` to LoroCounter so concurrent
+ *   increments add instead of stomping each other.
+ * - `"list"`, `"movable-list"`, `"tree"` are reserved for ordered /
+ *   reorderable / hierarchical collections — wire format locked in,
+ *   server-side projection still pending implementation.
+ * - `"lww"` is explicit (matches the default for most scalar types).
+ */
+export type CrdtAnnotation = "lww" | "text" | "counter" | "list" | "movable-list" | "tree";
+/**
+ * Insert-time default marker stored on a field definition. Apps never
+ * construct these directly — they come from `.default(v)` / `.defaultNow()`
+ * / `.owner()` on a field builder. The runtime + codegen read them.
+ */
+export type DefaultMarker = {
+    kind: "value";
+    value: unknown;
+} | {
+    kind: "now";
+} | {
+    kind: "owner";
+};
+export interface FieldDefinition {
+    type: FieldType;
+    optional: boolean;
+    unique: boolean;
+    /** CRDT container override. Omitted entirely for the default
+     *  (LWW for scalars, LoroText for richtext). */
+    crdt?: CrdtAnnotation;
+    /**
+     * When true, the field is **never serialized in HTTP responses**.
+     * Use for secrets / billing-side identity / hashes that the server
+     * needs to read internally but should never leak to clients.
+     *
+     * Stripped at every public read boundary:
+     * - `GET /api/entities/<entity>` (list)
+     * - `GET /api/entities/<entity>/<id>` (single row)
+     * - `GET /api/auth/session` (User row projection)
+     * - Sync push deltas
+     *
+     * Still readable from inside server functions via `ctx.db.*` —
+     * the framework trusts your handler logic to decide what to
+     * return. If you pass the row through unmodified to the client,
+     * the field IS still stripped at the function-response boundary,
+     * provided the value is a plain row from `ctx.db.get` (which
+     * tags it with the entity name so the boundary knows what to
+     * filter).
+     *
+     * `passwordHash` on every User entity is implicitly serverOnly
+     * even without this annotation, by the framework's hardcoded
+     * convention. New apps should still mark it explicitly so the
+     * intent shows up in the schema.
+     */
+    serverOnly?: boolean;
+    /**
+     * When true, the field is **set on insert but cannot be changed
+     * by client updates**. The framework rejects any `PATCH`/`PUT`
+     * payload that mentions the field with a `READONLY_FIELD` error,
+     * before policy evaluation. Admin contexts bypass this check (as
+     * with all other framework gates), so migrations + ops scripts
+     * can still rewrite owner-shaped fields.
+     *
+     * Use for identity-shaped columns that need to be settable at
+     * creation but immutable after — `authorId`, `orgId`,
+     * `createdBy`, `stripeCustomerId`. Closes the canonical IDOR
+     * shape where a policy gates on `data.authorId == auth.userId`
+     * but the attacker passes a different `authorId` in the update
+     * payload to flip the row's ownership.
+     *
+     * Server-side writes (via `ctx.db.update` inside a function)
+     * still go through — readonly only blocks the HTTP entity
+     * routes (`PATCH /api/entities/<entity>/<id>`) and `/api/transact`.
+     * Server code is trusted to enforce its own invariants.
+     */
+    readonly?: boolean;
+    /**
+     * When true, the field is AEAD-encrypted at rest. The framework
+     * encrypts the value before writing to SQLite/Postgres and
+     * decrypts on read. Cipher: ChaCha20-Poly1305. Key:
+     * `PYLON_ENCRYPTION_KEY` env (32 bytes, hex or base64).
+     *
+     * Use for PII / secrets that must survive a DB-file leak: API
+     * keys stored on rows, social security numbers, OAuth tokens.
+     * Plaintext only exists inside the Pylon process.
+     *
+     * Restrictions:
+     * - Encrypted fields are NOT queryable. `ctx.db.lookup` /
+     *   `WHERE encryptedField = 'x'` always returns nothing because
+     *   each write produces fresh ciphertext.
+     * - Cannot combine with `unique: true`.
+     * - Valid only on `string`, `richtext`, and JSON-shaped fields.
+     *
+     * Decryption pre-pass means rows written BEFORE the field was
+     * annotated `encrypted: true` continue to read fine (passes
+     * through as plaintext). Next write through the mutation
+     * pipeline upgrades them to ciphertext.
+     */
+    encrypted?: boolean;
+    /**
+     * Insert-time default. Set via `.default(value)` / `.defaultNow()` /
+     * `.owner()` on the field builder; recorded for the runtime + codegen.
+     */
+    default?: DefaultMarker;
+    /**
+     * Allowed values for `field.enum([...])` — recorded so codegen emits a
+     * precise literal-union type instead of a wide `string`.
+     */
+    enumValues?: readonly string[];
+}
+interface FieldBuilder {
+    readonly _def: FieldDefinition;
+    optional(): FieldBuilder;
+    unique(): FieldBuilder;
+    /**
+     * Override the CRDT container for this field. See [`CrdtAnnotation`]
+     * for the full list. Most apps never call this — the default mapping
+     * (string→LWW, richtext→LoroText, …) is the right answer.
+     *
+     * Example: `field.string().crdt("text")` upgrades a string to a
+     * collaborative LoroText so two browser tabs editing the field
+     * concurrently merge cleanly instead of last-write-wins.
+     */
+    crdt(annotation: CrdtAnnotation): FieldBuilder;
+    /**
+     * Mark the field as never-returned in HTTP responses. See
+     * [`FieldDefinition.serverOnly`] for the full semantics.
+     *
+     * Example: `stripeCustomerId: field.string().serverOnly()` keeps
+     * the Stripe customer id out of `/api/entities/Org/<id>` responses
+     * while staying readable from `ctx.db.get` inside the
+     * stripeWebhook action.
+     */
+    serverOnly(): FieldBuilder;
+    /**
+     * Mark the field as set-on-insert-only. See [`FieldDefinition.readonly`]
+     * for the full semantics.
+     *
+     * Example: `authorId: field.id("User").readonly()` lets the framework
+     * reject any `PATCH` payload trying to rewrite the row's author —
+     * closes the IDOR-via-update-payload class.
+     */
+    readonly(): FieldBuilder;
+    /**
+     * Mark the field as AEAD-encrypted at rest. See
+     * [`FieldDefinition.encrypted`] for the full semantics +
+     * restrictions.
+     *
+     * Example: `apiKey: field.string().serverOnly().encrypted()`
+     * keeps the key out of HTTP responses AND encrypts the bytes
+     * sitting in SQLite.
+     */
+    encrypted(): FieldBuilder;
+    /**
+     * Mark the field as the row's **owner** — the framework stamps it
+     * with `auth.userId` on every insert and refuses any client attempt
+     * to set it to a different user. This is what makes *optimistic,
+     * local-first writes the default* for owned data: the client can
+     * `db.insert("Offer", { buyerId, … })` directly (paints the row in
+     * the local store instantly, no server round-trip) and still be
+     * secure — the server overwrites/validates the owner from the
+     * session, so a forged `buyerId` is rejected before it ever lands.
+     *
+     * Concretely `.owner()`:
+     * - on **insert**, fills the field from `auth.userId` when omitted,
+     *   and rejects a non-admin caller who supplies a *different*
+     *   non-empty value (`OWNER_MISMATCH`, 403) — closing the IDOR
+     *   shape where a policy gates on `data.ownerId == auth.userId`
+     *   but the attacker just sends someone else's id;
+     * - on **update**, behaves like [`readonly`] — the owner can't be
+     *   reassigned through the HTTP entity routes.
+     *
+     * Reach for this instead of writing a server function whenever the
+     * only server-authoritative part of a create is "who made it":
+     * `authorId`, `buyerId`, `sellerId`, `createdBy`, `userId`. Guests
+     * count — their stable guest id is stamped. Admin contexts may set
+     * an explicit value (migrations, tooling).
+     *
+     * Example: `sellerId: field.string().owner()` lets a listing be
+     * created with a plain optimistic `db.insert` while the seller id
+     * stays unspoofable.
+     */
+    owner(): FieldBuilder;
+    /**
+     * Set a static insert-time default, recorded for the runtime +
+     * codegen. Example: `enabled: field.bool().default(true)`.
+     */
+    default(value: unknown): FieldBuilder;
+    /**
+     * Default a datetime field to insert-time `now()`. Example:
+     * `createdAt: field.datetime().defaultNow()`.
+     */
+    defaultNow(): FieldBuilder;
+}
+export declare const field: {
+    string: () => FieldBuilder;
+    int: () => FieldBuilder;
+    float: () => FieldBuilder;
+    /** Alias for `field.float()`. Lets either name work. */
+    number: () => FieldBuilder;
+    bool: () => FieldBuilder;
+    /** Alias for `field.bool()`. Lets either name work. */
+    boolean: () => FieldBuilder;
+    datetime: () => FieldBuilder;
+    richtext: () => FieldBuilder;
+    id: (target: string) => FieldBuilder;
+    /**
+     * `field.enum(["pending", "paid", "failed"])` — stored as a string with
+     * allowed-values metadata so codegen emits a precise literal union
+     * (`"pending" | "paid" | "failed"`) instead of a wide `string`.
+     */
+    enum: (values: readonly string[]) => FieldBuilder;
+};
+export interface IndexDefinition {
+    name: string;
+    fields: string[];
+    unique: boolean;
+    /**
+     * Optional SQL predicate. When set, the framework emits a *partial*
+     * index — `CREATE [UNIQUE] INDEX … WHERE <predicate>` — so the index
+     * (and any uniqueness constraint) only applies to rows matching the
+     * predicate.
+     *
+     * Use case: enforce "max 1 hobby-tier org per user" without breaking
+     * paid users who legitimately own many orgs:
+     *
+     * ```ts
+     * indexes: [{
+     *   name: "uniq_hobby_owner",
+     *   fields: ["createdBy"],
+     *   unique: true,
+     *   where: "plan = 'hobby'",
+     * }]
+     * ```
+     *
+     * The predicate is passed straight through to the database. Both
+     * SQLite and Postgres accept this syntax — write SQL the underlying
+     * engine understands. Pylon does NOT validate or escape this string,
+     * so DO NOT interpolate user input here.
+     */
+    where?: string;
+}
+export interface RelationDefinition {
+    name: string;
+    target: string;
+    field: string;
+    many?: boolean;
+}
+/**
+ * Per-entity search config. Presence of this object on an entity
+ * definition tells Pylon to create FTS5 + facet-bitmap shadow tables
+ * on the next schema push and maintain them on every write.
+ *
+ * - `text`     – fields that participate in free-text MATCH (BM25).
+ * - `facets`   – scalar fields (string / int / bool) that get live
+ *                per-value counts via `db.useSearch`.
+ * - `sortable` – fields the client may order results by. Any `sort`
+ *                on a field not in this list is silently ignored.
+ */
+export interface SearchConfig {
+    text?: string[];
+    facets?: string[];
+    sortable?: string[];
+}
+export interface EntityDefinition {
+    name: string;
+    fields: Record<string, FieldBuilder>;
+    indexes?: IndexDefinition[];
+    relations?: RelationDefinition[];
+    search?: SearchConfig;
+}
+export declare function entity(name: string, fields: Record<string, FieldBuilder>, options?: {
+    indexes?: IndexDefinition[];
+    relations?: RelationDefinition[];
+    search?: SearchConfig;
+}): EntityDefinition;
+export declare function relation(def: RelationDefinition): RelationDefinition;
+export type AuthMode = "public" | "user";
+export interface RouteDefinition {
+    path: string;
+    mode: RouteMode;
+    query?: string;
+    auth?: AuthMode;
+    /**
+     * Project-relative module path (e.g. `app/hello/page`) for SSR
+     * routes. Required when `mode === "ssr"`. Discovered automatically
+     * by `discoverAppRoutes()`; only specify manually for one-off
+     * SSR routes outside the `app/` tree.
+     */
+    component?: string;
+    /**
+     * Layout module path chain (root→leaf). Each layout wraps the next
+     * as `children`. Only relevant for `mode === "ssr"`.
+     */
+    layouts?: string[];
+    /**
+     * Route kind. Omitted (or `"page"`) is a normal navigable page.
+     * `"not-found"` / `"error"` are SSR boundary modules discovered from
+     * `app/.../not-found.tsx` and `app/.../error.tsx`. Boundary routes are
+     * NOT matched as navigable URLs — the host renders `not-found` for
+     * unmatched URLs (HTTP 404) and `error` on render failure (HTTP 500).
+     * `path` records the segment prefix the boundary covers (`/` for root).
+     * `"route"` is a form/method handler (`app/.../route.ts` exporting
+     * POST/PUT/PATCH/DELETE) — matched on its `path` for non-GET requests only,
+     * never rendered as a page.
+     */
+    kind?: "page" | "not-found" | "error" | "route" | "sitemap" | "robots";
+}
+export declare function defineRoute(route: RouteDefinition): RouteDefinition;
+export interface InputFieldDefinition {
+    name: string;
+    type: FieldType;
+    optional?: boolean;
+}
+export interface QueryDefinition {
+    name: string;
+    input?: InputFieldDefinition[];
+}
+export declare function query(name: string, options?: {
+    input?: InputFieldDefinition[];
+}): QueryDefinition;
+export interface ActionDefinition {
+    name: string;
+    input?: InputFieldDefinition[];
+}
+export declare function action(name: string, options?: {
+    input?: InputFieldDefinition[];
+}): ActionDefinition;
+export interface PolicyDefinition {
+    /** Optional — `buildManifest` auto-generates a name from the entity
+     *  + a counter when the fluent `.policies(policy({...}))` chain
+     *  omits one. Explicit names are still recommended for the
+     *  procedural API since they appear in policy-denied error
+     *  messages. */
+    name?: string;
+    entity?: string;
+    action?: string;
+    /**
+     * Fallback allow expression — evaluated when a more-specific
+     * allowRead/allowWrite/allowUpdate/allowDelete isn't set. Kept for
+     * backwards compatibility with single-gate policies.
+     */
+    allow?: string;
+    /** Overrides `allow` for reads (pull, list, get). */
+    allowRead?: string;
+    /** Overrides `allow` for inserts. Falls back to `allowWrite`. */
+    allowInsert?: string;
+    /** Overrides `allow`/`allowWrite` for updates. */
+    allowUpdate?: string;
+    /** Overrides `allow`/`allowWrite` for deletes. */
+    allowDelete?: string;
+    /** Shared fallback for any write when the specific rule is missing. */
+    allowWrite?: string;
+}
+export declare function policy(def: PolicyDefinition): PolicyDefinition;
+export interface PluginDefinition {
+    name: string;
+    entities?: EntityDefinition[];
+    hooks?: {
+        beforeInsert?: (entity: string, data: Record<string, unknown>) => Record<string, unknown> | null;
+        afterInsert?: (entity: string, id: string, data: Record<string, unknown>) => void;
+        beforeUpdate?: (entity: string, id: string, data: Record<string, unknown>) => Record<string, unknown> | null;
+        afterUpdate?: (entity: string, id: string, data: Record<string, unknown>) => void;
+        beforeDelete?: (entity: string, id: string) => boolean;
+        afterDelete?: (entity: string, id: string) => void;
+    };
+}
+export declare function definePlugin(def: PluginDefinition): PluginDefinition;
+/**
+ * Serialized form of `field.X().owner()`. Carried in a field's
+ * `default` slot as a *dynamic* default — the value isn't known until
+ * a request arrives, so the framework's auth-aware mutation pipeline
+ * (OwnerStampPlugin, Rust side) fills it from `auth.userId` on insert
+ * and rejects any client attempt to set it to a different user. The
+ * storage-layer default-filler (`apply_field_defaults`) deliberately
+ * skips this shape — it has no auth context, so it can't (and must
+ * not) stamp an owner.
+ *
+ * `$auth: "userId"` is the only kind today; the object shape leaves
+ * room for future auth-derived defaults (e.g. `{$auth:"tenantId"}`)
+ * without another manifest migration.
+ */
+export interface OwnerDefaultSentinel {
+    $auth: "userId";
+}
+export interface ManifestField {
+    name: string;
+    type: FieldType;
+    optional: boolean;
+    unique: boolean;
+    /** CRDT container override; matches `pylon_kernel::CrdtAnnotation` on
+     *  the Rust side. Omitted entirely when the field uses the default. */
+    crdt?: CrdtAnnotation;
+    /** Set when the field is `field.X().serverOnly()` — see
+     *  [`FieldDefinition.serverOnly`]. Omitted by default so JSON
+     *  manifests stay compact for unannotated apps. */
+    serverOnly?: boolean;
+    /** Set when the field is `field.X().readonly()` — see
+     *  [`FieldDefinition.readonly`]. Omitted by default. */
+    readonly?: boolean;
+    /** Default value to fill on insert when the row omits this field.
+     *  - `"now"`     → runtime stamps the current UTC time
+     *  - `{$auth:…}` → a *dynamic* default the auth-aware mutation
+     *                  pipeline fills (see [`OwnerDefaultSentinel`]).
+     *                  Never stamped at the storage layer — the
+     *                  OwnerStampPlugin fills + enforces it.
+     *  - any literal → runtime stamps that exact value
+     *  Maps to `field.X().defaultNow()` / `.default(value)` /
+     *  `field.X().owner()`. */
+    default?: "now" | string | number | boolean | null | OwnerDefaultSentinel;
+    /** Allowed values for `field.enum([...])` — recorded so codegen
+     *  can emit a literal-union type and runtime validation can
+     *  reject out-of-set inserts. Plain `field.string()` doesn't
+     *  carry this; only `field.enum()`. */
+    enumValues?: readonly string[];
+    /** Set when the field is `field.X().encrypted()` — AEAD-encrypted
+     *  at rest. See [`FieldDefinition.encrypted`]. */
+    encrypted?: boolean;
+}
+export interface ManifestIndex {
+    name: string;
+    fields: string[];
+    unique: boolean;
+    /** Optional partial-index predicate — see `IndexDefinition.where`. */
+    where?: string;
+}
+export interface ManifestRelation {
+    name: string;
+    target: string;
+    field: string;
+    many?: boolean;
+}
+export interface ManifestEntity {
+    name: string;
+    fields: ManifestField[];
+    indexes: ManifestIndex[];
+    relations?: ManifestRelation[];
+    /**
+     * Mirrors `pylon_kernel::ManifestSearchConfig`. When present, the
+     * runtime creates FTS5 + facet-bitmap shadow tables on schema push
+     * and maintains them on every write.
+     */
+    search?: {
+        text?: string[];
+        facets?: string[];
+        sortable?: string[];
+    };
+}
+export interface ManifestRoute {
+    path: string;
+    mode: string;
+    query?: string;
+    auth?: string;
+    component?: string;
+    layouts?: string[];
+    /** "not-found" / "error" boundaries, or "route" form handlers; omitted for normal pages. */
+    kind?: "page" | "not-found" | "error" | "route" | "sitemap" | "robots";
+}
+export interface ManifestInputField {
+    name: string;
+    type: FieldType;
+    optional: boolean;
+    unique: false;
+}
+export interface ManifestQuery {
+    name: string;
+    input?: ManifestInputField[];
+}
+export interface ManifestAction {
+    name: string;
+    input?: ManifestInputField[];
+}
+export interface ManifestPolicy {
+    name: string;
+    entity?: string;
+    action?: string;
+    allow?: string;
+    allowRead?: string;
+    allowInsert?: string;
+    allowUpdate?: string;
+    allowDelete?: string;
+    allowWrite?: string;
+}
+export declare const MANIFEST_VERSION = 1;
+/** A recurring job: run a function on a cron schedule. Declared in the
+ *  manifest via `cron(schedule, functionName)`; the runtime fires the named
+ *  function with anonymous auth every time the schedule matches. Server-side
+ *  `ctx.db.*` is trusted, so a maintenance handler reads/writes its entities
+ *  directly without elevating. */
+export interface ManifestCron {
+    /** Standard 5-field cron expression, e.g. `"0 * * * *"` (every hour). */
+    schedule: string;
+    /** Name of the function (query/mutation/action) to run. Should be an
+     *  `internal: true` function so it isn't also reachable over HTTP. */
+    function: string;
+    /** Optional human description, surfaced by `pylon status` / tooling. */
+    description?: string;
+}
+/** A self-hosted web font. Declared via `font({...})`; at build the runtime
+ *  fetches the family from Google Fonts, self-hosts the woff2 same-origin,
+ *  generates `@font-face` + a size-adjusted fallback face (zero layout shift),
+ *  and auto-injects the preload + faces into every SSR page's `<head>`. The app
+ *  references the font through the CSS `variable`. */
+export interface ManifestFont {
+    /** Google Fonts family name, e.g. "Geist" or "Inter". */
+    family: string;
+    /** CSS custom property the app uses to apply the font, e.g. "--font-geist".
+     *  Set `font-family: var(--font-geist)` (it resolves to the family + the
+     *  size-adjusted fallback + your `fallback` stack). */
+    variable: string;
+    /** Weights to load — specific (`["400","500","700"]`) or a CSS2 range
+     *  (`["300..700"]`). Defaults to `["400"]`. */
+    weights?: string[];
+    /** Styles to load. Defaults to `["normal"]`. */
+    styles?: ("normal" | "italic")[];
+    /** Unicode subsets, e.g. `["latin"]`. Defaults to `["latin"]`. */
+    subsets?: string[];
+    /** CSS `font-display`. Defaults to `"swap"`. */
+    display?: "auto" | "block" | "swap" | "fallback" | "optional";
+    /** Emit `<link rel="preload">` for the font files so the browser fetches
+     *  them early. Defaults to `true`. */
+    preload?: boolean;
+    /** Fallback stack appended after the family + the adjusted fallback face,
+     *  e.g. `["system-ui", "sans-serif"]`. Defaults to `["sans-serif"]`. */
+    fallback?: string[];
+    /** Generate a size-adjusted fallback `@font-face` (matching x-height +
+     *  metrics) so there's no layout shift when the web font swaps in. Defaults
+     *  to `true`. Serialized snake_case to match the kernel manifest wire shape. */
+    adjust_font_fallback?: boolean;
+}
+export interface AppManifest {
+    manifest_version: number;
+    name: string;
+    version: string;
+    entities: ManifestEntity[];
+    routes: ManifestRoute[];
+    queries: ManifestQuery[];
+    actions: ManifestAction[];
+    policies: ManifestPolicy[];
+    auth?: ManifestAuthConfig;
+    /** App-level LLM provider config. Optional — env wins when set. */
+    llm?: ManifestLlmConfig;
+    /** Declared OAuth integrations. Auto-creates the `_Connection`
+     *  entity at runtime boot. */
+    connections?: ManifestConnection[];
+    /** Recurring jobs — run a function on a cron schedule. */
+    crons?: ManifestCron[];
+    /** Self-hosted web fonts. Fetched + self-hosted at build; preload +
+     *  `@font-face` auto-injected into the SSR `<head>`. */
+    fonts?: ManifestFont[];
+}
+/**
+ * Declare a recurring job. Runs the named function every time the cron
+ * `schedule` matches (the runtime checks once a minute).
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   crons: [
+ *     cron("0 * * * *", "hourlyRollup"),     // every hour, on the hour
+ *     cron("15 3 * * *", "nightlyCleanup"),   // daily at 03:15
+ *   ],
+ * });
+ * ```
+ *
+ * `functionName` is a function in `functions/` — make it `internal: true`
+ * so it isn't also exposed over HTTP. It runs with anonymous auth, and a
+ * function's own `ctx.db.*` calls are server-side (not policy-gated), so a
+ * maintenance handler writes directly. Only call
+ * `ctx.auth.elevate({ admin: true, reason: "..." })` if it chains an
+ * `internal: true` function via `ctx.scheduler`, or you run with
+ * `PYLON_STRICT_FN_POLICIES=1`. The `reason` is mandatory (audited).
+ *
+ * Multiple replicas: each Pylon process runs its own scheduler. On a SHARED
+ * datastore (Postgres — the cloud default), the runtime takes a per-minute
+ * lease so each cron fires exactly ONCE per tick across all replicas. On
+ * per-replica SQLite there's no shared lease, so each replica fires — keep
+ * handlers idempotent there (most maintenance work naturally is). A
+ * single-machine app always fires exactly once.
+ */
+export declare function cron(schedule: string, functionName: string, opts?: {
+    description?: string;
+}): ManifestCron;
+/**
+ * Declare a self-hosted web font (Google Fonts). At build, Pylon fetches the
+ * family, self-hosts the woff2 same-origin, generates `@font-face` + a
+ * size-adjusted fallback face, and auto-injects the preload + faces into every
+ * SSR page's `<head>` — no render-blocking third-party request, no layout shift.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   fonts: [
+ *     font({ family: "Geist", variable: "--font-sans", weights: ["300..700"], subsets: ["latin"] }),
+ *     font({ family: "Geist Mono", variable: "--font-mono", weights: ["400..600"] }),
+ *   ],
+ * });
+ * ```
+ *
+ * Then use it in CSS: `font-family: var(--font-sans);` (resolves to the family,
+ * the zero-CLS fallback, then your `fallback` stack).
+ */
+export declare function font(opts: {
+    family: string;
+    variable: string;
+    weights?: string[];
+    styles?: ("normal" | "italic")[];
+    subsets?: string[];
+    display?: "auto" | "block" | "swap" | "fallback" | "optional";
+    preload?: boolean;
+    fallback?: string[];
+    adjustFontFallback?: boolean;
+}): ManifestFont;
+export declare function entitiesToManifest(entities: EntityDefinition[]): ManifestEntity[];
+export declare function routesToManifest(routes: RouteDefinition[]): ManifestRoute[];
+/**
+ * Walk the project's `app/` directory and discover file-based SSR
+ * routes. Returns `RouteDefinition[]` ready to slot into
+ * `buildManifest({ routes })`.
+ *
+ * Mapping (Next App Router-shaped):
+ *   - `app/page.tsx` → `/`
+ *   - `app/about/page.tsx` → `/about`
+ *   - `app/blog/[slug]/page.tsx` → `/blog/:slug`
+ *   - `app/layout.tsx` wraps every page below
+ *   - `app/(marketing)/about/page.tsx` → `/about` (group strip)
+ *
+ * Sorts deterministically — literal segments before parameterized
+ * ones at each depth — so the Rust matcher's first-match-wins
+ * lookup picks the right route.
+ *
+ * `not-found.tsx` / `error.tsx` boundaries are emitted as `kind`-tagged
+ * routes here; `loading.tsx` is resolved at render time by the SSR runtime
+ * (filesystem walk), so it needs no discovery entry.
+ */
+export declare function discoverAppRoutes(opts?: {
+    appDir?: string;
+}): Promise<RouteDefinition[]>;
+export declare function queriesToManifest(queries: QueryDefinition[]): ManifestQuery[];
+export declare function actionsToManifest(actions: ActionDefinition[]): ManifestAction[];
+export declare function policiesToManifest(policies: PolicyDefinition[]): ManifestPolicy[];
+/**
+ * Auth configuration block for the manifest. Mirrors better-auth's
+ * `betterAuth({ user, session, trustedOrigins })` shape.
+ *
+ * All fields optional with sensible defaults — apps that don't pass
+ * an `auth({...})` block to `buildManifest` get the framework defaults
+ * (User entity named "User", strip `passwordHash`, 30-day sessions,
+ * no cookie cache, trusted origins from `PYLON_TRUSTED_ORIGINS` env).
+ *
+ * `trustedOrigins` is the unified source for **all three gates** —
+ * CORS, CSRF, and OAuth-redirect. Loopback origins
+ * (`http://localhost`, `127.0.0.1`, `[::1]`, any port) are always
+ * auto-trusted across all three gates so `pylon dev` works without
+ * any allowlist config.
+ *
+ * @example
+ * auth({
+ *   user: {
+ *     entity: "User",
+ *     expose: ["id", "email", "displayName"],
+ *     hide: ["passwordHash", "internalNotes"],
+ *   },
+ *   session: { expiresIn: 60 * 60 * 24 * 7 }, // 7 days
+ *   trustedOrigins: ["https://app.example.com"],
+ * })
+ */
+export type AuthConfig = {
+    user?: {
+        /** Manifest entity name pylon treats as the User table. Default `"User"`. */
+        entity?: string;
+        /** Allowlist of fields exposed via `/api/auth/session`. Empty = all (minus hide list). */
+        expose?: string[];
+        /** Additional fields stripped (combined with default `passwordHash` + `_*`). */
+        hide?: string[];
+        /**
+         * Field on the User row that, when truthy, lifts the session's
+         * `auth.is_admin = true`. Examples: `"isAdmin"` (bool column),
+         * `"role"` (string equal to "admin"), `"roles"` (array containing
+         * "admin"). Default unset — only `PYLON_ADMIN_TOKEN` grants admin.
+         *
+         * Set this when you want platform admins to sign in with their
+         * regular account (Studio gates on `is_admin`, dashboards can
+         * branch on it, etc.). The env-token path keeps working as the
+         * bootstrap / CI escape hatch.
+         */
+        adminField?: string;
+    };
+    session?: {
+        /** New session lifetime in seconds. Default 30 days. */
+        expiresIn?: number;
+        /** Cookie cache config — bake claims into the cookie so reads avoid the DB. */
+        cookieCache?: {
+            enabled?: boolean;
+            /** Max staleness in seconds. Default 5 minutes. */
+            maxAge?: number;
+            /** Auth-context fields baked into the cookie envelope (always includes `user_id`). */
+            claims?: string[];
+        };
+    };
+    /**
+     * Org / OrgMember / OrgInvite entity configuration. Apps that use
+     * the framework's `/api/auth/orgs/*` surface declare these entities
+     * in their schema with the framework's required fields. Add custom
+     * fields freely (logo, industry, billingEmail, etc.) — the framework
+     * reads / writes only the fields it manages.
+     *
+     * Defaults to entities named `Org`, `OrgMember`, `OrgInvite`. Rename
+     * via the three string fields if your codebase uses different names
+     * (e.g. `Organization` / `Membership`). Set `disabled: true` to opt
+     * out of the framework's routes entirely — useful when the app has
+     * its own org flow in TS and doesn't want the framework's parallel
+     * write paths.
+     */
+    org?: {
+        /** Entity name for the org table. Default `"Org"`. */
+        entity?: string;
+        /** Entity name for membership rows. Default `"OrgMember"`. */
+        memberEntity?: string;
+        /** Entity name for invite rows. Default `"OrgInvite"`. */
+        inviteEntity?: string;
+        /**
+         * Disable the framework's `/api/auth/orgs/*` routes. Endpoints
+         * return `501 ORG_NOT_CONFIGURED`. Use when you implement org
+         * management entirely in your own TypeScript functions.
+         */
+        disabled?: boolean;
+    };
+    /**
+     * Per-app trusted origins. Single declarative source for the three
+     * browser-facing gates: CORS, CSRF, OAuth `?callback=` validation.
+     * Merged with `PYLON_TRUSTED_ORIGINS` (OAuth) / `PYLON_CORS_ORIGIN`
+     * (CORS) / `PYLON_CSRF_ORIGINS` (CSRF) env vars when ops need to
+     * split per-gate. Loopback (`http://localhost`, `127.0.0.1`, `[::1]`,
+     * any port) is always auto-trusted at every gate.
+     */
+    trustedOrigins?: string[];
+};
+/**
+ * Developer-facing camelCase config consumed by the `llm({...})`
+ * factory. All fields optional; environment variables
+ * (`PYLON_LLM_PROVIDER`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+ * `PYLON_LLM_MODEL`) take precedence so operators can override per
+ * deploy without redeploying the bundle.
+ */
+export type LlmConfig = {
+    /** Provider name. Default: env detection. */
+    provider?: "anthropic" | "openai";
+    /** Default model when the caller doesn't pass `model`. */
+    defaultModel?: string;
+    /**
+     * Allowlist of models callers may request via the `model` field.
+     * Empty = no extra allowance beyond what `PYLON_AI_MODELS_ALLOWED`
+     * env provides. Non-admin callers can't request models outside
+     * this list.
+     */
+    allowedModels?: string[];
+};
+export type ManifestLlmConfig = {
+    provider?: "anthropic" | "openai";
+    default_model?: string;
+    allowed_models?: string[];
+};
+/**
+ * Developer-facing config for `defineConnection({...})`. Each entry
+ * adds a `ctx.connections.<name>` surface to mutation + action ctx
+ * (server-side OAuth tokens, never visible to the browser).
+ *
+ * `provider` selects the OAuth client wire shape from pylon-auth's
+ * built-in list (`google`, `github`, `slack`, `microsoft`, etc.).
+ * `name` is the app-facing key — different connections can target
+ * the same provider with different scopes
+ * (e.g. `google-calendar` vs `google-drive`).
+ *
+ * Configuration: per-provider client id + secret come from env
+ * (`PYLON_OAUTH_<PROVIDER>_CLIENT_ID`, `PYLON_OAUTH_<PROVIDER>_CLIENT_SECRET`).
+ * Callback URL is derived from `PYLON_PUBLIC_URL` +
+ * `/api/connections/<name>/callback`.
+ *
+ * Storage: the framework auto-creates a `_Connection` entity at
+ * boot when any connection is declared; token fields are AEAD-
+ * encrypted at rest (`PYLON_ENCRYPTION_KEY` is REQUIRED — boot
+ * fails without it when connections are declared).
+ */
+export type ConnectionConfig = {
+    /** App-facing key. `ctx.connections.get(name)` matches on this. */
+    name: string;
+    /** Provider identifier matching pylon-auth's OAuth client. */
+    provider: string;
+    /** Whitespace-separated scopes. Empty = provider default. */
+    scopes?: string;
+};
+export type ManifestConnection = {
+    name: string;
+    provider: string;
+    scopes?: string;
+};
+/**
+ * Declare a server-side OAuth integration. Returns the manifest
+ * entry the runtime parses. Re-exported through `app.ts`:
+ *
+ * ```ts
+ * import { defineConnection } from "@pylonsync/sdk";
+ *
+ * export const googleConn = defineConnection({
+ *   name: "google",
+ *   provider: "google",
+ *   scopes: "email profile https://www.googleapis.com/auth/calendar.readonly",
+ * });
+ * ```
+ *
+ * `buildManifest({ connections: [googleConn] })` carries this into
+ * the manifest; the runtime auto-creates the `_Connection` entity
+ * and exposes `ctx.connections.get("google")` to actions.
+ */
+export declare function defineConnection(cfg: ConnectionConfig): ManifestConnection;
+/**
+ * Build the manifest's `llm` block from the user-facing camelCase
+ * config. Returns the snake_case shape the Rust runtime parses.
+ *
+ * ```ts
+ * export default {
+ *   llm: llm({
+ *     provider: "anthropic",
+ *     defaultModel: "claude-sonnet-4-5",
+ *     allowedModels: ["claude-sonnet-4-5", "claude-haiku-4-5"],
+ *   }),
+ * }
+ * ```
+ */
+export declare function llm(cfg?: LlmConfig): ManifestLlmConfig;
+export type ManifestAuthConfig = {
+    user: {
+        entity: string;
+        expose: string[];
+        hide: string[];
+        admin_field?: string;
+    };
+    session: {
+        expires_in: number;
+        cookie_cache: {
+            enabled: boolean;
+            max_age: number;
+            claims: string[];
+        };
+    };
+    org: {
+        entity: string;
+        member_entity: string;
+        invite_entity: string;
+        disabled: boolean;
+    };
+    trusted_origins: string[];
+};
+/**
+ * Build the manifest's `auth` block from the user-facing camelCase
+ * config. Translates to the snake_case shape the Rust runtime expects.
+ *
+ * Defaults match `pylon_kernel::ManifestAuthConfig::default()` so
+ * passing nothing is equivalent to omitting the `auth({...})` call.
+ */
+export declare function auth(cfg?: AuthConfig): ManifestAuthConfig;
+export declare function buildManifest(options: {
+    name: string;
+    version: string;
+    entities: EntityDefinition[];
+    routes: RouteDefinition[];
+    queries?: QueryDefinition[];
+    actions?: ActionDefinition[];
+    policies?: PolicyDefinition[];
+    auth?: ManifestAuthConfig;
+    llm?: ManifestLlmConfig;
+    connections?: ManifestConnection[];
+    crons?: ManifestCron[];
+    fonts?: ManifestFont[];
+}): AppManifest;
+export { defineStudioConfig, defineStudioExtensions, type BrandConfig, type ThemeConfig, type ThemeAccent, type ThemeAppearance, type IconName, type SidebarConfig, type SidebarSection, type SidebarItem, type SidebarPageItem, type SidebarResourceItem, type SidebarLinkItem, type SidebarHeadingItem, type SidebarFooter, type SidebarFooterCard, type SidebarFooterCustom, type ResourceConfig, type ResourceListConfig, type ColumnConfig, type ColumnRenderer, type RendererKind, type RendererText, type RendererAvatar, type RendererBadge, type RendererDate, type RendererLink, type RendererBoolean, type RendererNumber, type RendererJson, type RendererCustom, type BulkAction, type RowAction, type PageConfig, type StudioConfig, type StudioCellRendererProps, type StudioPageProps, type StudioExtensions, } from "./studio";
+/**
+ * Behavior — a function that mutates the entity definition before it's
+ * registered. Implementations should be idempotent (the user can list
+ * the same behavior twice without breaking the schema).
+ */
+export interface Behavior {
+    /** Stable identifier — surfaced in the manifest for tooling, lets a
+     *  pass-through inspector see which behaviors are active. */
+    readonly id: string;
+    apply(def: EntityDefinition): EntityDefinition;
+}
+/**
+ * `timestamps` — auto-add `createdAt` + `updatedAt` datetime fields.
+ * The `defaultNow()` marker on each tells the runtime to fill `now()`
+ * on insert (and on update for `updatedAt`). Wiring lands with the
+ * runtime patch — until then, app code can still set the values
+ * manually and the fields exist on the row.
+ */
+export declare const timestamps: Behavior;
+/**
+ * `softDelete` — auto-add a nullable `deletedAt` datetime field.
+ * Rows with `deletedAt != null` are filtered from default reads
+ * (TS-side filtering today; runtime filter lands in the follow-up).
+ */
+export declare const softDelete: Behavior;
+/**
+ * `audit` — marker behavior. Tags the entity for the framework's
+ * audit pipeline (writes an `AuditEvent` row per mutation, recording
+ * the actor + diff). Runtime hook lands in a follow-up patch — for
+ * now the marker is preserved on the manifest so apps can opt in
+ * early without breaking later.
+ */
+export declare const audit: Behavior;
+/** Variadic index helper — `e.idx("customer", "createdAt")` reads
+ *  better than the options-object form for the common case. */
+declare function idx(...fields: string[]): IndexDefinition;
+interface EntityBuilder {
+    readonly _def: EntityDefinition & {
+        behaviors?: string[];
+    };
+    indexes(...idxs: IndexDefinition[]): EntityBuilder;
+    policies(...policies: PolicyDefinition[]): EntityBuilder;
+    behaviors(list: readonly Behavior[]): EntityBuilder;
+    relations(...rels: RelationDefinition[]): EntityBuilder;
+    search(cfg: SearchConfig): EntityBuilder;
+}
+/**
+ * The fluent `e` namespace. Equivalent to the procedural `entity()`
+ * function — both produce manifest-compatible definitions, both can
+ * be mixed in the same app.
+ */
+export declare const e: {
+    entity(name: string, fields: Record<string, FieldBuilder>): EntityBuilder;
+    idx: typeof idx;
+};
+/**
+ * Extract attached policies from a fluent entity. The manifest
+ * builder calls this when assembling the top-level `policies` list,
+ * so apps using the fluent `.policies(...)` chain don't have to
+ * register policies separately at the manifest root.
+ *
+ * Returns an empty array for entities produced by the procedural
+ * `entity()` API — those apps register policies the old way.
+ */
+export declare function extractAttachedPolicies(e: EntityDefinition | EntityBuilder): PolicyDefinition[];