@trylight/app 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @trylight/app
+
+The platform half of a v2 org app (`infra/provisioning/org-app-template-v2`):
+its tables and their typed client, its door, its contracts and its chat.
+Sign-in, contracts and chat are `@shubh90/app-runtime`'s, re-exported
+unchanged; entities and the schema sync are new here.
+
+| Import | What |
+|---|---|
+| `@trylight/app/schema` | `entity(name, columns, access)`: a Drizzle table plus `id`, `created_at`, `updated_at`, `created_by`, `field_sources`; `lightChanges` (the audit table); `fieldSource` (the `{url, evidence}` schema) |
+| `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed) and `app.contracts` (`useInvocation`) |
+| `@trylight/app/server` | `createLightServer({ schema, contracts })` → `light.db` (Drizzle), `light.session(request)`, `light.signIn(email, password)`, and the route handlers `light.entities`, `light.invoke.handler`, `light.chat` |
+| `@trylight/app/platform` | the door for server functions, framing, analytics/error policies, the pane bridge |
+| `@trylight/app/vite` | `lightDb()`: the dev server syncs `db/schema` into the database on every change |
+| `light-db` (bin) | `sync`, `migrate`, `check`: the app's `pnpm db:*` scripts |
+
+## Entities
+
+One route, `/api/light/entities/:table[/:id]`, serves every table exported
+through `entity()`. Each request is parsed with the table's own Zod schema
+(drizzle-zod; unknown or platform columns are refused, `field_sources` must be
+`{url, evidence}` per real column), goes through the app's door (members-only:
+a member; public: anyone reads, people signed in write; `write: "agents"`
+tables refuse the app), must come from the app's own pages, and each change is
+written with a `light_changes` row naming the person, in one transaction. An
+edited value loses its source; sources sent are merged by column. Lists sort
+by the asked column, then id. With no sign-in configured only a non-production
+server asked on loopback answers (as "Local developer"); anything else gets 503.
+
+Pages read and write through TanStack Query hooks: `useUpdate` patches every
+cached list and row at once and stays pending until the table's refetch lands
+(no snap-back); a failed save is corrected by that same refetch.
+
+Joins and aggregates stay typed server functions over `light.db`.
+
+## Schema sync
+
+`plan()` diffs `db/schema` against the newest migration snapshot with
+drizzle-kit's API, removals first and additions second, so drizzle-kit never
+has to ask whether a column was renamed (it can't without a terminal).
+The change is written as a drizzle migration (`db/migrations`,
+drizzle-kit's own layout) and applied, whatever it does to the rows there (a
+removed column's values go with it); one the rows refuse is taken back out,
+so the change stays pending rather than blocking every later migrate. Changed
+indexes and constraints are dropped before the columns they cover and enums
+only after, so the two halves apply in order. Syncs and migrates each hold a Postgres advisory lock (with a
+lock_timeout), so the dev server's watcher and an agent's own sync never
+overlap, and a process that dies releases it. `migrate` applies the journal; in an app's sandbox the agent's shell
+asks the platform's migrate socket to run it. `check` (in `pnpm build`)
+fails while `db/schema` has changes no migration holds.
+
+## Develop
+
+```bash
+pnpm install
+pnpm run check                                              # typecheck, lint, tests
+TEST_DATABASE_URL=postgres://you@127.0.0.1:5432/postgres pnpm test   # with the database tests
+pnpm run build                                              # dist/, what the template installs
+```
+
+Not published yet: the template depends on this directory (`file:`).

package/bin/light-db.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The app's schema files are TypeScript; tsx lets the CLI import them.
+import { register } from "tsx/esm/api";
+
+register();
+await import("../dist/db/cli.js");

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import type { Contracts } from "@shubh90/app-runtime/invoke/server";
+import { EntityError, type ListOptions, type NewRow, type Patch, type Row } from "./entities.js";
+import type { Entity } from "./schema.js";
+export { EntityError, LIST_LIMIT, type ListOptions, type NewRow, type Sort, type Patch, type Row, type Where } from "./entities.js";
+export type { FieldSource, FieldSources } from "./schema.js";
+export { siteOf } from "./schema.js";
+export { InvocationError, type InvocationStatus } from "@shubh90/app-runtime/invoke";
+export declare function createApp<C extends Contracts = Record<never, never>>(): {
+    table: typeof tableClient;
+    contracts: import("@shubh90/app-runtime/invoke").Invoker<C>;
+};
+/** One entity table's rows: plain calls, and TanStack Query hooks over them. */
+declare function tableClient<T extends Entity>(entity: T): {
+    /**
+     * The query key everything this table caches sits under. A page's own
+     * query over the table (a server function's totals) keyed under it is
+     * refetched after every write too.
+     */
+    key: string[];
+    list: (options?: ListOptions<Row<T>>) => Promise<Row<T>[]>;
+    get: (id: string) => Promise<Row<T>>;
+    create: (data: NewRow<T>) => Promise<Row<T>>;
+    update: (id: string, patch: Patch<T>) => Promise<Row<T>>;
+    delete: (id: string) => Promise<void>;
+    /** The rows, cached per options; refetched after any write to this table. */
+    useList: (options?: ListOptions<Row<T>>) => import("@tanstack/react-query").UseQueryResult<(T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never)[], EntityError>;
+    /** One row; `null` waits (nothing open yet). */
+    useGet: (id: string | null) => import("@tanstack/react-query").UseQueryResult<T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never, EntityError>;
+    useCreate: () => import("@tanstack/react-query").UseMutationResult<T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never, EntityError, NewRow<T>, unknown>;
+    /** Shows the patch at once in every cached list and row. */
+    useUpdate: () => import("@tanstack/react-query").UseMutationResult<T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never, EntityError, {
+        id: string;
+        patch: Patch<T>;
+    }, unknown>;
+    /** Takes the row out of every cached list at once. */
+    useDelete: () => import("@tanstack/react-query").UseMutationResult<void, EntityError, string, unknown>;
+};
+export type TableClient<T extends Entity> = ReturnType<typeof tableClient<T>>;
+/** To the login page, and back here after. */
+export declare function redirectToLogin(): void;

package/dist/client.js

@@ -0,0 +1,135 @@
+// The browser half, bound once in `src/lib/app.ts`:
+//
+//   export const app = createApp<typeof contracts>();
+//
+// `app.table(companies)` reads and writes that table's rows through the
+// entities route; its hooks keep TanStack Query's cache in step, so an edit
+// shows at once and never snaps back. `app.contracts` asks the org's agents.
+import { keepPreviousData, skipToken, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createInvoker } from "@shubh90/app-runtime/invoke";
+import { getTableName } from "drizzle-orm";
+import { z } from "zod/v4";
+import { ENTITIES_PATH, EntityError } from "./entities.js";
+export { EntityError, LIST_LIMIT } from "./entities.js";
+export { siteOf } from "./schema.js";
+export { InvocationError } from "@shubh90/app-runtime/invoke";
+export function createApp() {
+    return { table: tableClient, contracts: createInvoker() };
+}
+/** One entity table's rows: plain calls, and TanStack Query hooks over them. */
+function tableClient(entity) {
+    const base = `${ENTITIES_PATH}/${getTableName(entity)}`;
+    const keys = {
+        all: ["light", base],
+        list: (options) => ["light", base, "list", options],
+        get: (id) => ["light", base, "get", id],
+        write: ["light", base, "write"]
+    };
+    const list = (options = {}) => call("GET", `${base}?q=${encodeURIComponent(JSON.stringify(options))}`);
+    const get = (id) => call("GET", `${base}/${id}`);
+    const create = (data) => call("POST", base, json(data));
+    const update = (id, patch) => call("PATCH", `${base}/${id}`, json(patch));
+    const remove = async (id) => {
+        await call("DELETE", `${base}/${id}`);
+    };
+    /**
+     * After a write, refetch the table once the last write in flight settles.
+     * Returning the refetch keeps the mutation pending until it lands, so an
+     * edit never flickers back to its old value; a failed write is corrected
+     * by the same refetch.
+     */
+    const useSettle = () => {
+        const client = useQueryClient();
+        return async () => {
+            if (client.isMutating({ mutationKey: keys.write }) === 1)
+                await client.invalidateQueries({ queryKey: keys.all });
+        };
+    };
+    return {
+        /**
+         * The query key everything this table caches sits under. A page's own
+         * query over the table (a server function's totals) keyed under it is
+         * refetched after every write too.
+         */
+        key: keys.all,
+        list,
+        get,
+        create,
+        update,
+        delete: remove,
+        /** The rows, cached per options; refetched after any write to this table. */
+        useList: (options = {}) => useQuery({ queryKey: keys.list(options), queryFn: () => list(options) }),
+        /** One row; `null` waits (nothing open yet). */
+        useGet: (id) => useQuery({
+            queryKey: keys.get(id),
+            queryFn: id === null ? skipToken : () => get(id),
+            // A panel closing (id → null) keeps its row while it slides out.
+            placeholderData: keepPreviousData
+        }),
+        useCreate: () => {
+            const settle = useSettle();
+            return useMutation({
+                mutationKey: keys.write,
+                mutationFn: create,
+                onSettled: settle
+            });
+        },
+        /** Shows the patch at once in every cached list and row. */
+        useUpdate: () => {
+            const client = useQueryClient();
+            const settle = useSettle();
+            return useMutation({
+                mutationKey: keys.write,
+                mutationFn: ({ id, patch }) => update(id, patch),
+                onMutate: async ({ id, patch }) => {
+                    await client.cancelQueries({ queryKey: keys.all });
+                    // As the server does: a value set here loses its old source; sources sent merge in.
+                    const patched = (row) => row.id === id
+                        ? {
+                            ...row,
+                            ...patch,
+                            field_sources: Object.assign(Object.fromEntries(Object.entries(row.field_sources).filter(([column]) => !(column in patch))), patch.field_sources)
+                        }
+                        : row;
+                    client.setQueriesData({ queryKey: [...keys.all, "list"] }, (rows) => rows && rows.map(patched));
+                    client.setQueryData(keys.get(id), (row) => row && patched(row));
+                },
+                onSettled: settle
+            });
+        },
+        /** Takes the row out of every cached list at once. */
+        useDelete: () => {
+            const client = useQueryClient();
+            const settle = useSettle();
+            return useMutation({
+                mutationKey: keys.write,
+                mutationFn: remove,
+                onMutate: async (id) => {
+                    await client.cancelQueries({ queryKey: keys.all });
+                    client.setQueriesData({ queryKey: [...keys.all, "list"] }, (rows) => rows && rows.filter((row) => row.id !== id));
+                },
+                onSettled: settle
+            });
+        }
+    };
+}
+function json(body) {
+    return { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) };
+}
+const refusal = z.object({ error: z.string(), code: z.string() });
+async function call(method, path, init = {}) {
+    const response = await fetch(path, { ...init, method, credentials: "same-origin" });
+    if (response.ok)
+        return response.json();
+    const read = refusal.safeParse(await response.json().catch(() => null));
+    if (!read.success)
+        throw new EntityError(`${method} ${path} failed (${response.status}).`, response.status);
+    // A session that ended while the tab was open: the login page, not an error.
+    if (read.data.code === "not_signed_in")
+        redirectToLogin();
+    throw new EntityError(read.data.error, response.status);
+}
+/** To the login page, and back here after. */
+export function redirectToLogin() {
+    window.location.assign(`/login?next=${encodeURIComponent(window.location.pathname + window.location.search)}`);
+}

package/dist/db/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/cli.js

@@ -0,0 +1,112 @@
+// `light-db sync`, `light-db migrate`, `light-db check`: the
+// app's `pnpm db:*` scripts. Run from the app's root.
+import { existsSync } from "node:fs";
+import { request } from "node:http";
+import { userInfo } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { drizzle } from "drizzle-orm/postgres-js";
+import { migrate } from "drizzle-orm/postgres-js/migrator";
+import postgres from "postgres";
+import { z } from "zod/v4";
+import { MIGRATIONS_DIR, SCHEMA_ENTRY, plan, unwriteMigration, writeMigration } from "./migrations.js";
+import { env } from "../server/env.js";
+/**
+ * In an app's sandbox the agent's shell can read the database, not change
+ * it: the platform runs `pnpm db:migrate` for it, as root with the app's own
+ * credential, behind this socket.
+ */
+const PLATFORM_MIGRATE = "/run/mii/migrate.sock";
+/** Postgres advisory locks: one migrate, and one sync, of a database at a time. */
+const MIGRATE_LOCK_KEY = 4_815_162_342;
+const SYNC_LOCK_KEY = 4_815_162_343;
+// pg_advisory_lock waits for the one before it; a process that dies releases it.
+const connect = () => postgres(databaseUrl(), { max: 1, onnotice: () => undefined });
+const root = process.cwd();
+const envFile = join(root, ".env.local");
+if (existsSync(envFile))
+    process.loadEnvFile(envFile);
+const [command] = process.argv.slice(2);
+async function loadSchema() {
+    return import(pathToFileURL(join(root, SCHEMA_ENTRY)).href);
+}
+function databaseUrl() {
+    const { databaseUrl } = env();
+    if (databaseUrl === undefined)
+        throw new Error("DATABASE_URL is not set: there is no database to sync db/schema into.");
+    return databaseUrl;
+}
+/**
+ * Makes the database match `db/schema`, whatever the change does to the rows
+ * there. One sync at a time (the dev server's watcher and an agent's own)
+ * through a Postgres advisory lock, which a sync that dies releases.
+ */
+async function sync() {
+    const client = connect();
+    try {
+        await client `select pg_advisory_lock(${SYNC_LOCK_KEY})`;
+        const planned = await plan(root, await loadSchema());
+        if (planned.statements.length === 0)
+            return await applyMigrations();
+        const tag = writeMigration(root, planned);
+        console.log(`Wrote ${MIGRATIONS_DIR}/${tag}.sql:\n${planned.statements.join("\n")}`);
+        // A migration that doesn't apply comes back out, so the change stays pending
+        // (and the build's check keeps failing) instead of blocking every migrate.
+        const applied = await applyMigrations().catch((error) => {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        });
+        if (applied !== 0) {
+            unwriteMigration(root, tag);
+            console.error(`${MIGRATIONS_DIR}/${tag}.sql didn't apply, so it was taken back; change db/schema and save again.`);
+        }
+        return applied;
+    }
+    finally {
+        await client.end();
+    }
+}
+/** Fails when db/schema has changes no migration holds yet (a build's check). */
+async function check() {
+    const planned = await plan(root, await loadSchema());
+    if (planned.statements.length === 0)
+        return 0;
+    console.error(`db/schema has changes with no migration yet; run \`pnpm db:sync\`:\n${planned.statements.join("\n")}`);
+    return 1;
+}
+/** Applies every migration in db/migrations the database doesn't have. */
+async function applyMigrations() {
+    // The agent (not root) in an app's sandbox: the platform migrates for it.
+    if (userInfo().uid !== 0 && existsSync(PLATFORM_MIGRATE))
+        return migrateThroughPlatform();
+    const client = connect();
+    try {
+        await client `select pg_advisory_lock(${MIGRATE_LOCK_KEY})`;
+        await migrate(drizzle(client), { migrationsFolder: join(root, MIGRATIONS_DIR) });
+        console.log("Database is up to date with db/migrations.");
+        return 0;
+    }
+    finally {
+        await client.end();
+    }
+}
+const platformReply = z.object({ output: z.string(), code: z.number() });
+async function migrateThroughPlatform() {
+    const body = await new Promise((resolve, reject) => {
+        const req = request({ socketPath: PLATFORM_MIGRATE, method: "POST", path: "/migrate" }, (res) => {
+            let text = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => (text += chunk));
+            res.on("end", () => resolve(text));
+        });
+        req.on("error", reject);
+        req.end();
+    });
+    const reply = platformReply.parse(JSON.parse(body));
+    process.stdout.write(reply.output);
+    return reply.code;
+}
+// Last, so every const above is initialized before a command reads it.
+const commands = { sync, migrate: applyMigrations, check };
+const usage = z.enum(["sync", "migrate", "check"], { error: "Usage: light-db sync | migrate | check" });
+process.exit(await commands[usage.parse(command)]());

package/dist/db/migrations.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod/v4";
+export declare const SCHEMA_ENTRY = "db/schema/index.ts";
+export declare const MIGRATIONS_DIR = "db/migrations";
+export type Plan = {
+    /** The new migration's statements, in order; empty when nothing changed. */
+    statements: string[];
+    snapshot: Snapshot;
+};
+/** The parts of a drizzle-kit snapshot a removal touches; the rest passes through. */
+declare const snapshotSchema: z.ZodObject<{
+    id: z.ZodString;
+    tables: z.ZodRecord<z.ZodString, z.ZodObject<{
+        columns: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        indexes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        foreignKeys: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        compositePrimaryKeys: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        uniqueConstraints: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        checkConstraints: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        policies: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>>;
+    enums: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    schemas: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sequences: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    roles: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    policies: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    views: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+type Snapshot = z.infer<typeof snapshotSchema>;
+/**
+ * What `db/schema` needs beyond the last migration, in three diffs that each
+ * only remove or only add, so drizzle-kit never has to ask whether something
+ * removed was renamed (it can't ask here: there is no terminal). A rename is
+ * therefore a drop and an add: the old column's values go. Removed enums go last,
+ * after the columns that used them have changed.
+ */
+export declare function plan(root: string, schema: Record<string, unknown>): Promise<Plan>;
+/**
+ * Writes the plan as the next migration, in drizzle-kit's own layout (the
+ * SQL, its snapshot, the journal entry), so drizzle's migrator applies it.
+ */
+export declare function writeMigration(root: string, planned: Plan): string;
+/** Takes back the newest migration, one that didn't apply, so the schema's change is pending again. */
+export declare function unwriteMigration(root: string, tag: string): void;
+export {};

package/dist/db/migrations.js

@@ -0,0 +1,158 @@
+// Writing a schema file is the migration: the change from the last
+// migration's snapshot to `db/schema` becomes a new drizzle migration,
+// written and applied at once, whatever it does to the rows there (a removed
+// column's values go with it).
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { join } from "node:path";
+import { generateDrizzleJson, generateMigration } from "drizzle-kit/api";
+import { z } from "zod/v4";
+export const SCHEMA_ENTRY = "db/schema/index.ts";
+export const MIGRATIONS_DIR = "db/migrations";
+const entries = z.record(z.string(), z.unknown());
+/** The parts of a drizzle-kit snapshot a removal touches; the rest passes through. */
+const snapshotSchema = z.looseObject({
+    id: z.string(),
+    tables: z.record(z.string(), z.looseObject({
+        columns: entries,
+        indexes: entries,
+        foreignKeys: entries,
+        compositePrimaryKeys: entries,
+        uniqueConstraints: entries,
+        checkConstraints: entries,
+        policies: entries
+    })),
+    enums: entries,
+    schemas: entries,
+    sequences: entries,
+    roles: entries,
+    policies: entries,
+    views: entries
+});
+/**
+ * What `db/schema` needs beyond the last migration, in three diffs that each
+ * only remove or only add, so drizzle-kit never has to ask whether something
+ * removed was renamed (it can't ask here: there is no terminal). A rename is
+ * therefore a drop and an add: the old column's values go. Removed enums go last,
+ * after the columns that used them have changed.
+ */
+export async function plan(root, schema) {
+    const previous = latestSnapshot(root);
+    // As JSON, the way it is written: undefined fields drop, so it compares equal to what was read back.
+    const snapshot = snapshotSchema.parse(JSON.parse(JSON.stringify(generateDrizzleJson(schema, previous.id))));
+    const kept = withoutRemovals(previous, snapshot);
+    const withOldEnums = { ...snapshot, enums: { ...previous.enums, ...snapshot.enums } };
+    const statements = [
+        ...(await generateMigration(previous, kept)),
+        ...(await generateMigration(kept, withOldEnums)),
+        ...(await generateMigration(withOldEnums, snapshot))
+    ];
+    return { statements, snapshot };
+}
+function only(from, keep) {
+    return Object.fromEntries(Object.entries(from).filter(([key]) => key in keep));
+}
+/** Entries of `from` that `now` still has exactly as they were. */
+function unchanged(from, now) {
+    return Object.fromEntries(Object.entries(from).filter(([key, value]) => isDeepStrictEqual(value, now[key])));
+}
+/**
+ * The previous snapshot less whatever the current one no longer has. Tables
+ * and columns go by name (a changed column is altered in the second step);
+ * indexes and constraints go unless unchanged, so a changed one is dropped
+ * before the columns it covers and made again after. Enums all stay: a type
+ * is dropped only in the third step, after the columns that use it change.
+ */
+function withoutRemovals(previous, current) {
+    const tables = {};
+    for (const [key, table] of Object.entries(previous.tables)) {
+        const now = current.tables[key];
+        if (now === undefined)
+            continue;
+        tables[key] = {
+            ...table,
+            columns: only(table.columns, now.columns),
+            indexes: unchanged(table.indexes, now.indexes),
+            foreignKeys: unchanged(table.foreignKeys, now.foreignKeys),
+            compositePrimaryKeys: unchanged(table.compositePrimaryKeys, now.compositePrimaryKeys),
+            uniqueConstraints: unchanged(table.uniqueConstraints, now.uniqueConstraints),
+            checkConstraints: unchanged(table.checkConstraints, now.checkConstraints),
+            policies: unchanged(table.policies, now.policies)
+        };
+    }
+    return {
+        ...previous,
+        tables,
+        schemas: only(previous.schemas, current.schemas),
+        sequences: only(previous.sequences, current.sequences),
+        roles: only(previous.roles, current.roles),
+        policies: only(previous.policies, current.policies),
+        views: only(previous.views, current.views)
+    };
+}
+const journalSchema = z.object({
+    version: z.string(),
+    dialect: z.literal("postgresql"),
+    entries: z.array(z.object({
+        idx: z.number(),
+        version: z.string(),
+        when: z.number(),
+        tag: z.string(),
+        breakpoints: z.boolean()
+    }))
+});
+const EMPTY_SNAPSHOT = {
+    version: "7",
+    dialect: "postgresql",
+    id: "00000000-0000-0000-0000-000000000000",
+    prevId: "",
+    tables: {},
+    enums: {},
+    schemas: {},
+    policies: {},
+    roles: {},
+    sequences: {},
+    views: {},
+    _meta: { schemas: {}, tables: {}, columns: {} }
+};
+function readJournal(root) {
+    const path = join(root, MIGRATIONS_DIR, "meta", "_journal.json");
+    if (!existsSync(path))
+        return { version: "7", dialect: "postgresql", entries: [] };
+    return journalSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+function snapshotFile(root, idx) {
+    return join(root, MIGRATIONS_DIR, "meta", `${String(idx).padStart(4, "0")}_snapshot.json`);
+}
+function latestSnapshot(root) {
+    const last = readJournal(root).entries.at(-1);
+    if (last === undefined)
+        return EMPTY_SNAPSHOT;
+    return snapshotSchema.parse(JSON.parse(readFileSync(snapshotFile(root, last.idx), "utf8")));
+}
+/**
+ * Writes the plan as the next migration, in drizzle-kit's own layout (the
+ * SQL, its snapshot, the journal entry), so drizzle's migrator applies it.
+ */
+export function writeMigration(root, planned) {
+    const journal = readJournal(root);
+    const idx = journal.entries.length;
+    const tag = `${String(idx).padStart(4, "0")}_schema`;
+    mkdirSync(join(root, MIGRATIONS_DIR, "meta"), { recursive: true });
+    writeFileSync(join(root, MIGRATIONS_DIR, `${tag}.sql`), planned.statements.join("\n--> statement-breakpoint\n") + "\n");
+    writeFileSync(snapshotFile(root, idx), JSON.stringify(planned.snapshot, null, 2) + "\n");
+    journal.entries.push({ idx, version: "7", when: Date.now(), tag, breakpoints: true });
+    writeFileSync(join(root, MIGRATIONS_DIR, "meta", "_journal.json"), JSON.stringify(journal, null, 2) + "\n");
+    return tag;
+}
+/** Takes back the newest migration, one that didn't apply, so the schema's change is pending again. */
+export function unwriteMigration(root, tag) {
+    const journal = readJournal(root);
+    const last = journal.entries.at(-1);
+    if (last === undefined || last.tag !== tag)
+        throw new Error(`${tag} is not the newest migration.`);
+    rmSync(join(root, MIGRATIONS_DIR, `${tag}.sql`));
+    rmSync(snapshotFile(root, last.idx));
+    journal.entries.pop();
+    writeFileSync(join(root, MIGRATIONS_DIR, "meta", "_journal.json"), JSON.stringify(journal, null, 2) + "\n");
+}

package/dist/entities.d.ts

@@ -0,0 +1,32 @@
+import type { Entity, PlatformColumn } from "./schema.js";
+export declare const ENTITIES_PATH = "/api/light/entities";
+/** The most rows one list returns; page past it with `offset`. */
+export declare const LIST_LIMIT = 1000;
+/** A value as JSON carries it: a Date column arrives as its ISO string. */
+type Wire<T> = {
+    [K in keyof T]: Date extends T[K] ? Exclude<T[K], Date> | string : T[K];
+};
+export type Row<T extends Entity> = Wire<T["$inferSelect"]>;
+/** What a create takes: every column but the ones the platform sets. */
+export type NewRow<T extends Entity> = Omit<Wire<T["$inferInsert"]>, PlatformColumn>;
+/** What an update takes: any of those columns. */
+export type Patch<T extends Entity> = Partial<NewRow<T>>;
+/** Equal to a value, or (an array) to any of several; null matches empty. */
+export type Where<R> = {
+    [K in keyof R]?: R[K] | readonly R[K][];
+};
+/** A column, ascending, or `-column`, descending. */
+export type Sort<R> = (keyof R & string) | `-${keyof R & string}`;
+export type ListOptions<R> = {
+    where?: Where<R>;
+    sort?: Sort<R>;
+    /** At most LIST_LIMIT, which is also the default. */
+    limit?: number;
+    offset?: number;
+};
+/** A refused or failed entities call, with the route's own reason. */
+export declare class EntityError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export {};

package/dist/entities.js

@@ -0,0 +1,12 @@
+export const ENTITIES_PATH = "/api/light/entities";
+/** The most rows one list returns; page past it with `offset`. */
+export const LIST_LIMIT = 1000;
+/** A refused or failed entities call, with the route's own reason. */
+export class EntityError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "EntityError";
+    }
+}

package/dist/platform.d.ts

@@ -0,0 +1,2 @@
+export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS, type ServerFnName } from "@shubh90/app-runtime/platform";
+export { MiiPaneBridge } from "@shubh90/app-runtime/react";

package/dist/platform.js

@@ -0,0 +1,5 @@
+// The platform contract a page and the global middleware need: framing by
+// Plaza's App pane, the server-function door, analytics and error policies,
+// and the pane bridge. Behaviour lives in @shubh90/app-runtime.
+export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS } from "@shubh90/app-runtime/platform";
+export { MiiPaneBridge } from "@shubh90/app-runtime/react";