@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/store/postgres/migrations/001_initial.js

@@ -1,196 +0,0 @@
-/**
- * The first Postgres Tenant schema.
- *
- * - `tenant` holds the Tenant envelope (one row).
- * - Document tables keep `id text primary key, body json`. The fields typed
- *   queries filter on are stored generated columns with indexes. Ids and
- *   timestamps compared as text use `COLLATE "C"`, so ordering is by code
- *   point, like the in-memory fake, whatever the database collation.
- * - Bodies are `json`, not `jsonb`, so every string round-trips exactly as
- *   `JSON.stringify` wrote it. `jsonb` rejects the escapes `\u0000` (`22P05`)
- *   and unpaired surrogates (`\ud800`), which tool output can contain and
- *   which the in-memory store accepts. `json` stores the text
- *   verbatim and checks only its syntax. The generated columns read the body
- *   through `doc(body)`, which casts to `jsonb` after replacing those two
- *   escapes with `\ufffd`: the stored body is untouched, and only an indexed
- *   field that itself contained one (never an id, status or timestamp) would
- *   see U+FFFD. Bodies with no `\u` escape at all take the plain cast. Queries
- *   never apply `->`/`->>` to a `json` body (Postgres de-escapes the whole text
- *   and fails on the same escapes); they read generated columns.
- * - `sessions` carries the store-managed `next_event_seq` and ownership
- *   columns (`owner`, `epoch`, `owner_expires_at`), which are never in `body`.
- * - `outbox(session_id, seq, body)` holds committed, unrelayed events.
- * - Executors, principals, vault and settings keep typed columns. Vault
- *   ciphertext is `bytea` columns, never inside a JSON body.
- */
-export const initial = {
-    version: 1,
-    name: "initial",
-    up: (s) => `
-    CREATE FUNCTION ${s}.doc(body json) RETURNS jsonb
-    LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS $$
-      SELECT CASE WHEN strpos(body::text, '\\u') = 0 THEN body::jsonb
-        ELSE regexp_replace(
-          body::text,
-          '(?<!\\\\)((?:\\\\\\\\)*)\\\\u(0000|[dD][89a-fA-F][0-9a-fA-F]{2})',
-          '\\1\\\\ufffd',
-          'g'
-        )::jsonb
-      END
-    $$;
-
-    CREATE TABLE ${s}.tenant (
-      id text COLLATE "C" PRIMARY KEY,
-      name text NOT NULL,
-      created_at text NOT NULL,
-      updated_at text NOT NULL,
-      schema_version integer NOT NULL,
-      singleton boolean NOT NULL DEFAULT true UNIQUE CHECK (singleton)
-    );
-
-    CREATE TABLE ${s}.definitions (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL
-    );
-
-    CREATE TABLE ${s}.sessions (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL,
-      status text GENERATED ALWAYS AS (${s}.doc(body)->>'status') STORED,
-      agent_id text GENERATED ALWAYS AS (${s}.doc(body)->>'agentId') STORED,
-      stream_incarnation text GENERATED ALWAYS AS (${s}.doc(body)->>'streamIncarnation') STORED,
-      next_event_seq bigint NOT NULL DEFAULT 0,
-      owner text,
-      epoch bigint NOT NULL DEFAULT 0,
-      owner_expires_at timestamptz
-    );
-    CREATE INDEX sessions_status ON ${s}.sessions (status, owner_expires_at);
-    CREATE INDEX sessions_agent ON ${s}.sessions (agent_id);
-
-    CREATE TABLE ${s}.commands (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL
-    );
-
-    CREATE TABLE ${s}.checkpoints (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL
-    );
-
-    CREATE TABLE ${s}.effects (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL,
-      session_id text GENERATED ALWAYS AS (${s}.doc(body)->'request'->>'sessionId') STORED,
-      turn_id text GENERATED ALWAYS AS (${s}.doc(body)->'request'->>'turnId') STORED,
-      kind text GENERATED ALWAYS AS (${s}.doc(body)->'request'->>'kind') STORED,
-      status text GENERATED ALWAYS AS (${s}.doc(body)->>'status') STORED
-    );
-    CREATE INDEX effects_session ON ${s}.effects (session_id, turn_id, status);
-    CREATE INDEX effects_status ON ${s}.effects (status, kind);
-
-    CREATE TABLE ${s}.actions (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL,
-      session_id text GENERATED ALWAYS AS (${s}.doc(body)->>'sessionId') STORED,
-      turn_id text GENERATED ALWAYS AS (${s}.doc(body)->>'turnId') STORED,
-      agent_id text GENERATED ALWAYS AS (${s}.doc(body)->>'agentId') STORED,
-      status text GENERATED ALWAYS AS (${s}.doc(body)->>'status') STORED,
-      kind text GENERATED ALWAYS AS (${s}.doc(body)->>'kind') STORED,
-      lease_expires_at text GENERATED ALWAYS AS (${s}.doc(body)->>'leaseExpiresAt') STORED
-    );
-    CREATE INDEX actions_session ON ${s}.actions (session_id, turn_id, status);
-    CREATE INDEX actions_agent ON ${s}.actions (agent_id, status);
-    CREATE INDEX actions_status ON ${s}.actions (status, kind);
-    CREATE INDEX actions_lease ON ${s}.actions (status, lease_expires_at);
-
-    CREATE TABLE ${s}.sandboxes (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL
-    );
-
-    CREATE TABLE ${s}.links (
-      id text COLLATE "C" PRIMARY KEY,
-      body json NOT NULL,
-      workflow_session_id text GENERATED ALWAYS AS (${s}.doc(body)->>'workflowSessionId') STORED
-    );
-    CREATE INDEX links_workflow ON ${s}.links (workflow_session_id);
-
-    CREATE TABLE ${s}.outbox (
-      session_id text COLLATE "C" NOT NULL,
-      seq bigint NOT NULL,
-      body json NOT NULL,
-      created_at text COLLATE "C" GENERATED ALWAYS AS (${s}.doc(body)->>'createdAt') STORED,
-      PRIMARY KEY (session_id, seq)
-    );
-
-    CREATE TABLE ${s}.executors (
-      agent_id text COLLATE "C" PRIMARY KEY,
-      token_hash text NOT NULL UNIQUE,
-      implementation_version text NOT NULL,
-      manifest_hash text,
-      principal_id text,
-      created_at text NOT NULL,
-      updated_at text NOT NULL
-    );
-
-    CREATE TABLE ${s}.principals (
-      id text COLLATE "C" PRIMARY KEY,
-      role text NOT NULL,
-      token_hash text NOT NULL UNIQUE,
-      idempotency_key text,
-      created_at text NOT NULL
-    );
-
-    CREATE TABLE ${s}.vaults (
-      id text COLLATE "C" PRIMARY KEY,
-      name text NOT NULL,
-      owner_user_id text NOT NULL,
-      metadata_json text,
-      created_at text COLLATE "C" NOT NULL,
-      scope text NOT NULL DEFAULT 'user' CHECK (scope IN ('user', 'host'))
-    );
-    CREATE INDEX vaults_owner ON ${s}.vaults (owner_user_id, created_at, id);
-    CREATE UNIQUE INDEX vaults_one_host ON ${s}.vaults (scope) WHERE scope = 'host';
-
-    CREATE TABLE ${s}.vault_credentials (
-      id text COLLATE "C" PRIMARY KEY,
-      vault_id text NOT NULL REFERENCES ${s}.vaults (id) ON DELETE CASCADE,
-      name text NOT NULL,
-      type text NOT NULL,
-      binding_json text NOT NULL,
-      expires_at text,
-      created_at text COLLATE "C" NOT NULL,
-      rotated_at text,
-      kek_id text NOT NULL,
-      nonce bytea NOT NULL,
-      ciphertext bytea NOT NULL,
-      wrapped_dek bytea NOT NULL
-    );
-    CREATE INDEX vault_credentials_vault ON ${s}.vault_credentials (vault_id, created_at, id);
-
-    CREATE TABLE ${s}.vault_audit (
-      ord bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-      id text NOT NULL UNIQUE,
-      at text NOT NULL,
-      actor text NOT NULL,
-      action text NOT NULL,
-      vault_id text,
-      credential_id text,
-      session_id text,
-      target text,
-      outcome text NOT NULL
-    );
-    CREATE INDEX vault_audit_vault ON ${s}.vault_audit (vault_id, ord);
-
-    CREATE TABLE ${s}.vault_idempotency (
-      id text PRIMARY KEY,
-      body_hash text NOT NULL,
-      response text NOT NULL
-    );
-
-    CREATE TABLE ${s}.tenant_settings (
-      key text PRIMARY KEY,
-      value text NOT NULL
-    );
-  `,
-};

package/dist/store/postgres/migrations/002_session_owner.d.ts

@@ -1,6 +0,0 @@
-import type { Migration } from "./index.js";
-/**
- * The session owner (`ownerUserId`) as a stored generated column with an index, so a request
- * acting for a subject lists only that subject's sessions. Not the lease column `owner`.
- */
-export declare const sessionOwner: Migration;

package/dist/store/postgres/migrations/002_session_owner.js

@@ -1,13 +0,0 @@
-/**
- * The session owner (`ownerUserId`) as a stored generated column with an index, so a request
- * acting for a subject lists only that subject's sessions. Not the lease column `owner`.
- */
-export const sessionOwner = {
-    version: 2,
-    name: "session_owner",
-    up: (s) => `
-    ALTER TABLE ${s}.sessions
-      ADD COLUMN owner_user_id text GENERATED ALWAYS AS (${s}.doc(body)->>'ownerUserId') STORED;
-    CREATE INDEX sessions_owner_user ON ${s}.sessions (owner_user_id);
-  `,
-};

package/dist/store/postgres/migrations/index.d.ts

@@ -1,49 +0,0 @@
-/**
- * Forward-only, numbered migrations of one Tenant schema (architecture §14.6).
- *
- * Each schema records what it has applied in `<schema>.schema_version`, one
- * row per migration; its version is the highest row. Migrating runs every
- * missing step in order, in the caller's transaction, under a transaction-level
- * advisory lock on the schema so two processes never migrate the same schema
- * at once. A schema newer than the Runtime is never touched: migrating it
- * throws a `schema-too-new` quarantine and the Tenant is quarantined.
- *
- * Adding a migration: append `NNN_name.ts` with the next version to
- * `MIGRATIONS`. Never edit or reorder an applied migration.
- */
-import type { Sql, TransactionSql } from "postgres";
-export interface Migration {
-    /** 1, 2, 3, … without gaps. */
-    version: number;
-    name: string;
-    /** DDL for the quoted schema name `s` (for example `"tenant_tn_…"`). */
-    up(s: string): string;
-}
-export declare const MIGRATIONS: readonly Migration[];
-/** The schema version this Runtime writes and expects. */
-export declare const POSTGRES_SCHEMA_VERSION: number;
-/** Checks that versions run 1, 2, 3, … Throws otherwise. */
-export declare function assertMigrations(migrations: readonly Migration[]): void;
-/** Takes the schema's migration lock until the transaction ends. */
-export declare function lockSchema(tx: TransactionSql, schema: string): Promise<void>;
-export declare function schemaExists(sql: Sql | TransactionSql, schema: string): Promise<boolean>;
-/**
- * The schema's version: 0 when it exists without a `schema_version` table,
- * undefined when the schema does not exist.
- */
-export declare function readSchemaVersion(sql: Sql | TransactionSql, schema: string): Promise<number | undefined>;
-/**
- * Creates the schema when missing and applies every missing migration, inside
- * `tx`. Call `lockSchema` first when other processes may migrate concurrently
- * (`migrateSchema` does). Throws a `schema-too-new` `QuarantineError` when the
- * schema is ahead of `migrations`.
- */
-export declare function migrateSchemaInTx(tx: TransactionSql, schema: string, migrations?: readonly Migration[]): Promise<{
-    from: number;
-    to: number;
-}>;
-/** `migrateSchemaInTx` in its own transaction, under the schema's migration lock. */
-export declare function migrateSchema(sql: Sql, schema: string, migrations?: readonly Migration[]): Promise<{
-    from: number;
-    to: number;
-}>;

package/dist/store/postgres/migrations/index.js

@@ -1,76 +0,0 @@
-import { quarantine } from "../../../tenant/quarantine.js";
-import { quoteIdentifier, tenantIdFromSchema } from "../names.js";
-import { initial } from "./001_initial.js";
-import { sessionOwner } from "./002_session_owner.js";
-export const MIGRATIONS = [initial, sessionOwner];
-/** The schema version this Runtime writes and expects. */
-export const POSTGRES_SCHEMA_VERSION = MIGRATIONS.at(-1).version;
-/** Checks that versions run 1, 2, 3, … Throws otherwise. */
-export function assertMigrations(migrations) {
-    migrations.forEach((migration, index) => {
-        if (migration.version !== index + 1)
-            throw new Error(`Migration ${migration.name} has version ${migration.version}, expected ${index + 1}`);
-    });
-}
-/** Takes the schema's migration lock until the transaction ends. */
-export async function lockSchema(tx, schema) {
-    await tx `SELECT pg_advisory_xact_lock(hashtextextended(${`nylorun.schema:${schema}`}, 0))`;
-}
-export async function schemaExists(sql, schema) {
-    const rows = await sql `SELECT 1 FROM pg_namespace WHERE nspname = ${schema}`;
-    return rows.length > 0;
-}
-/**
- * The schema's version: 0 when it exists without a `schema_version` table,
- * undefined when the schema does not exist.
- */
-export async function readSchemaVersion(sql, schema) {
-    const [row] = await sql `
-    SELECT
-      EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = ${schema}) AS has_schema,
-      to_regclass(${`${quoteIdentifier(schema)}.schema_version`}) IS NOT NULL AS has_table`;
-    if (!row.has_schema)
-        return undefined;
-    if (!row.has_table)
-        return 0;
-    const [version] = await sql `
-    SELECT max(version)::int AS version FROM ${sql(`${schema}.schema_version`)}`;
-    return version?.version ?? 0;
-}
-/**
- * Creates the schema when missing and applies every missing migration, inside
- * `tx`. Call `lockSchema` first when other processes may migrate concurrently
- * (`migrateSchema` does). Throws a `schema-too-new` `QuarantineError` when the
- * schema is ahead of `migrations`.
- */
-export async function migrateSchemaInTx(tx, schema, migrations = MIGRATIONS) {
-    assertMigrations(migrations);
-    const s = quoteIdentifier(schema);
-    const latest = migrations.length;
-    await tx.unsafe(`
-    CREATE SCHEMA IF NOT EXISTS ${s};
-    CREATE TABLE IF NOT EXISTS ${s}.schema_version (
-      version integer PRIMARY KEY,
-      name text NOT NULL,
-      applied_at timestamptz NOT NULL DEFAULT now()
-    );`);
-    const from = (await readSchemaVersion(tx, schema)) ?? 0;
-    if (from > latest)
-        throw quarantine("schema-too-new", `Tenant schema version ${from} is newer than this Runtime's ${latest}`, { tenantId: tenantIdFromSchema(schema) ?? schema });
-    for (const migration of migrations.slice(from)) {
-        await tx.unsafe(migration.up(s));
-        await tx `INSERT INTO ${tx(`${schema}.schema_version`)} (version, name)
-             VALUES (${migration.version}, ${migration.name})`;
-    }
-    if (from < latest)
-        await tx `UPDATE ${tx(`${schema}.tenant`)} SET schema_version = ${latest}`;
-    return { from, to: latest };
-}
-/** `migrateSchemaInTx` in its own transaction, under the schema's migration lock. */
-export async function migrateSchema(sql, schema, migrations = MIGRATIONS) {
-    const result = await sql.begin(async (tx) => {
-        await lockSchema(tx, schema);
-        return { result: await migrateSchemaInTx(tx, schema, migrations) };
-    });
-    return result.result;
-}

package/dist/store/postgres/names.d.ts

@@ -1,11 +0,0 @@
-export declare const TENANT_SCHEMA_PREFIX = "tenant_";
-/** Postgres truncates identifiers longer than NAMEDATALEN - 1 bytes. */
-export declare const MAX_IDENTIFIER_BYTES = 63;
-/** The schema holding `tenantId`'s Session Store. Throws on an invalid id. */
-export declare function tenantSchemaName(tenantId: string): string;
-/** The Tenant id a schema name encodes, or undefined when it is not a Tenant schema. */
-export declare function tenantIdFromSchema(schema: string): string | undefined;
-/** Rejects names Postgres would truncate or that could not be quoted safely. */
-export declare function assertIdentifier(name: string): void;
-/** `"name"`, for SQL text built outside a tagged template (migrations). */
-export declare function quoteIdentifier(name: string): string;

package/dist/store/postgres/names.js

@@ -1,42 +0,0 @@
-/**
- * Tenant id ↔ Postgres schema name (architecture §8.1, §12.2).
- *
- * A Tenant's Session Store is the schema `"tenant_<id>"`, for example
- * `tn_01k8z3…` ↦ `"tenant_tn_01k8z3…"`. Tenant ids match
- * `^tn_[0-9a-hjkmnp-tv-z]{26}$` (lowercase ASCII), so the name is 36 bytes,
- * under Postgres' 63-byte identifier limit, and needs no case folding. It is
- * always written quoted. The mapping is total and reversible: a schema that
- * starts with `tenant_` but does not decode to a valid Tenant id is not a
- * Tenant.
- */
-import { isTenantId } from "@nylorun/core/compatibility";
-export const TENANT_SCHEMA_PREFIX = "tenant_";
-/** Postgres truncates identifiers longer than NAMEDATALEN - 1 bytes. */
-export const MAX_IDENTIFIER_BYTES = 63;
-/** The schema holding `tenantId`'s Session Store. Throws on an invalid id. */
-export function tenantSchemaName(tenantId) {
-    if (!isTenantId(tenantId))
-        throw new Error(`Invalid tenant id: ${tenantId}`);
-    const schema = `${TENANT_SCHEMA_PREFIX}${tenantId}`;
-    assertIdentifier(schema);
-    return schema;
-}
-/** The Tenant id a schema name encodes, or undefined when it is not a Tenant schema. */
-export function tenantIdFromSchema(schema) {
-    if (!schema.startsWith(TENANT_SCHEMA_PREFIX))
-        return undefined;
-    const id = schema.slice(TENANT_SCHEMA_PREFIX.length);
-    return isTenantId(id) ? id : undefined;
-}
-/** Rejects names Postgres would truncate or that could not be quoted safely. */
-export function assertIdentifier(name) {
-    if (name.length === 0 ||
-        Buffer.byteLength(name, "utf8") > MAX_IDENTIFIER_BYTES ||
-        !/^[a-z_][a-z0-9_]*$/.test(name))
-        throw new Error(`Invalid Postgres identifier: ${name}`);
-}
-/** `"name"`, for SQL text built outside a tagged template (migrations). */
-export function quoteIdentifier(name) {
-    assertIdentifier(name);
-    return `"${name}"`;
-}

package/dist/store/postgres/tenants.d.ts

@@ -1,90 +0,0 @@
-/**
- * The Tenant catalog on one Postgres database (architecture §8.2).
- *
- * A Tenant exists when its schema `"tenant_<id>"` exists (see `names.ts`); the
- * Host keeps no other registry. The envelope is the one row of the schema's
- * `tenant` table, and its `schemaVersion` is the schema's migrated version.
- *
- * - `createTenant` runs in one transaction: create the schema, migrate it,
- *   write the envelope and the bootstrap principals. A crash leaves nothing.
- *   Creating an existing Tenant with the same bootstrap principals returns
- *   `exists`; with different ones it throws `TenantConflictError`.
- * - `openTenant` migrates an older schema forward and returns its store. A
- *   schema newer than this Runtime, a failed migration or an unreadable
- *   envelope quarantines that Tenant only. A lost connection or an unavailable
- *   server says nothing about the Tenant, so it is thrown, never a quarantine.
- * - `deleteTenant` drops the schema with everything in it.
- *
- * Create, migrate and delete of one schema are serialized by a
- * transaction-level advisory lock on the schema name.
- */
-import type { Sql } from "postgres";
-import { type TenantEnvelope } from "@nylorun/core/contracts";
-import type { BootstrapPrincipal, Quarantine } from "../../tenant/types.js";
-import type { SessionStore } from "../types.js";
-import { type Migration } from "./migrations/index.js";
-export interface PostgresTenantCatalogOptions {
-    /** The shared pool. The catalog and its stores never end it. */
-    sql: Sql;
-    /** Clock for principal `createdAt`. Defaults to `() => new Date()`. */
-    now?: () => Date;
-    /** Passed to every opened store. */
-    onError?: (error: unknown) => void;
-    /** Tests only: the migrations this Runtime knows. */
-    migrations?: readonly Migration[];
-}
-export interface TenantListing {
-    id: string;
-    /** Null when the envelope cannot be read; `quarantine` says why. */
-    envelope: TenantEnvelope | null;
-    quarantine?: Quarantine;
-}
-export type CreateTenantResult = {
-    status: "created";
-    envelope: TenantEnvelope;
-} | {
-    status: "exists";
-    envelope: TenantEnvelope;
-};
-export type OpenTenantResult = {
-    status: "ok";
-    store: SessionStore;
-    envelope: TenantEnvelope;
-    migrated: {
-        from: number;
-        to: number;
-    };
-} | {
-    status: "quarantined";
-    reason: Quarantine;
-} | {
-    status: "not-found";
-};
-export interface PostgresTenantCatalog {
-    /** Every `tenant_*` schema that encodes a Tenant id, ordered by id. */
-    listTenants(): Promise<TenantListing[]>;
-    /** The ids of `listTenants`, without reading any envelope. */
-    listTenantIds(): Promise<string[]>;
-    /** Whether the Tenant's schema exists. */
-    tenantExists(id: string): Promise<boolean>;
-    /** Throws a `QuarantineError` (`envelope-invalid`) when unreadable. */
-    readEnvelope(id: string): Promise<TenantEnvelope>;
-    createTenant(input: {
-        envelope: TenantEnvelope;
-        principals: BootstrapPrincipal;
-    }): Promise<CreateTenantResult>;
-    /** Whether the stored bootstrap (and Studio) principals equal `bootstrap`. */
-    bootstrapMatches(id: string, bootstrap: BootstrapPrincipal): Promise<boolean>;
-    openTenant(id: string, options?: {
-        now?: () => Date;
-        onError?: (error: unknown) => void;
-    }): Promise<OpenTenantResult>;
-    /** Migrates an existing Tenant schema. Throws `schema-too-new` or the migration error. */
-    migrateTenant(id: string): Promise<{
-        from: number;
-        to: number;
-    }>;
-    /** Drops the schema and everything in it. Returns false when it did not exist. */
-    deleteTenant(id: string): Promise<boolean>;
-}
-export declare function createPostgresTenantCatalog(options: PostgresTenantCatalogOptions): PostgresTenantCatalog;