@sequenceholdings/orm 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,830 @@
+import { z } from 'zod';
+import { generateDrizzleJson } from 'drizzle-kit/api';
+import { PgTableWithColumns } from 'drizzle-orm/pg-core';
+
+/**
+ * Custom Roles & Capabilities manifest grammar — the `capabilities.roles`
+ * block and the `capabilities.uses` pin set. This is a VERBATIM mirror of the
+ * platform's canonical grammar so an ORM namespace declares roles/capabilities
+ * the exact same way an artifact or managed function does; apply feeds it to
+ * the shared `reconcileHostRegistryOnActivation` reconciler untouched.
+ *
+ * Canonical sources — keep the grammar in sync by hand (schema shape, key
+ * regexes, limits, and superRefine rules). The behavioral guards in
+ * definitions.test.ts exercise this copy (inherit cycle, unknown grant,
+ * pin-names-role, key collision) so a drifted rule fails there:
+ *   atlas/src/server/services/custom-roles/manifest-block.ts        (server)
+ *   shared/services/artifact-studio/src/manifest-custom-roles.ts    (CLI)
+ */
+
+/**
+ * Manifest-declared custom roles & capabilities. Roles and capabilities are
+ * both `custom_role` FGA objects; deploy reconciliation turns this block into
+ * the structural waterfall edges (role→capability / senior→junior `assignee`
+ * userset tuples) — nothing else. The host floor is enforced app-layer at the
+ * resolution points, never in the model. Runtime grants (user/group/org →
+ * role) are NEVER declared here — they are written through host-admin-gated
+ * endpoints.
+ */
+declare const customRolesBlockSchema: z.ZodObject<{
+    definitions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodDefault<z.ZodBoolean>;
+        inherits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    capabilities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type CustomRolesBlock = z.infer<typeof customRolesBlockSchema>;
+/** True when the block declares at least one role or capability. */
+declare function customRolesDeclared(block: CustomRolesBlock | null | undefined): boolean;
+declare const capabilityPinsSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
+interface ParsedCapabilityPin {
+    scope: 'org' | 'host';
+    key: string;
+}
+/** Split a pin into its scope and key. Assumes the pin grammar validated. */
+declare function parseCapabilityPin(pin: string): ParsedCapabilityPin;
+/**
+ * Cross-field pin validation (the `uses` array and the roles block are
+ * siblings under `capabilities`). Purely structural — registry existence
+ * checks are server-side, at activation, where atomicity lives.
+ */
+declare function validateCapabilityPins({ uses, roles, }: {
+    uses: readonly string[];
+    roles: CustomRolesBlock | null | undefined;
+}): string[];
+
+/**
+ * The reserved `namespace.yaml` — namespace-level settings beside the table
+ * files. `capabilities` is the platform's Custom Roles manifest block, authored
+ * exactly as an artifact or managed function authors it:
+ *   - `capabilities.roles.capabilities` declares namespace-scoped capabilities
+ *     (published on the namespace's registry scope + pinned at apply),
+ *   - `capabilities.roles.definitions` declares roles (grants + inherits) that
+ *     bundle those capabilities,
+ *   - `capabilities.uses` attaches EXISTING capabilities — `org/<key>` for an
+ *     org capability (namespaces never create org entities), or a bare `<key>`
+ *     already published on the namespace scope.
+ * Apply feeds this block straight to the shared attachment reconciler, so the
+ * capabilities are grantable in Custom Roles and enter claim resolution.
+ */
+declare const namespaceConfigSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        roles: z.ZodOptional<z.ZodObject<{
+            definitions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+                default: z.ZodDefault<z.ZodBoolean>;
+                inherits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            capabilities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        uses: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type NamespaceConfig = z.output<typeof namespaceConfigSchema>;
+
+declare const actionParamSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        bigint: "bigint";
+        boolean: "boolean";
+        uuid: "uuid";
+        text: "text";
+        integer: "integer";
+        numeric: "numeric";
+        double: "double";
+        timestamptz: "timestamptz";
+        date: "date";
+        jsonb: "jsonb";
+    }>;
+    optional: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+interface ValidatesEntry {
+    readonly source: string;
+    readonly table: string;
+    readonly param: string;
+}
+declare const AUDIT_ACTIONS: readonly ["create", "update", "delete"];
+declare const actionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ParsedPredicate, string>>>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            bigint: "bigint";
+            boolean: "boolean";
+            uuid: "uuid";
+            text: "text";
+            integer: "integer";
+            numeric: "numeric";
+            double: "double";
+            timestamptz: "timestamptz";
+            date: "date";
+            jsonb: "jsonb";
+        }>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    validates: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ValidatesEntry, string>>>>;
+    executes: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    returns: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        bigint: "bigint";
+        boolean: "boolean";
+        uuid: "uuid";
+        text: "text";
+        integer: "integer";
+        numeric: "numeric";
+        double: "double";
+        timestamptz: "timestamptz";
+        date: "date";
+        jsonb: "jsonb";
+    }>>>;
+    audit: z.ZodOptional<z.ZodObject<{
+        action: z.ZodEnum<{
+            create: "create";
+            update: "update";
+            delete: "delete";
+        }>;
+        resource: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ActionDefinition = z.output<typeof actionSchema>;
+declare function extractNamedParams(sql: string): string[];
+
+declare const COLUMN_TYPES: readonly ["uuid", "text", "integer", "bigint", "numeric", "double", "boolean", "timestamptz", "date", "jsonb"];
+type ColumnType = (typeof COLUMN_TYPES)[number];
+declare const columnTypeSchema: z.ZodEnum<{
+    bigint: "bigint";
+    boolean: "boolean";
+    uuid: "uuid";
+    text: "text";
+    integer: "integer";
+    numeric: "numeric";
+    double: "double";
+    timestamptz: "timestamptz";
+    date: "date";
+    jsonb: "jsonb";
+}>;
+/**
+ * True when the default is one of the allowlisted SQL function calls for its
+ * type — the ONLY defaults the engine may emit as raw SQL. Everything else
+ * is a literal value; in particular a text default that happens to end in
+ * `()` is data, never code.
+ */
+declare const isFunctionDefault: (value: ColumnDefault, type: ColumnType) => boolean;
+type ColumnDefault = string | number | boolean;
+interface ColumnDefinition {
+    readonly type: ColumnType;
+    readonly primary_key?: boolean;
+    readonly nullable?: boolean;
+    readonly unique?: boolean;
+    readonly default?: ColumnDefault;
+    readonly description?: string;
+    readonly renamed_from?: string;
+    readonly cast?: string;
+    readonly deprecated?: boolean;
+}
+declare const columnSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        bigint: "bigint";
+        boolean: "boolean";
+        uuid: "uuid";
+        text: "text";
+        integer: "integer";
+        numeric: "numeric";
+        double: "double";
+        timestamptz: "timestamptz";
+        date: "date";
+        jsonb: "jsonb";
+    }>;
+    primary_key: z.ZodOptional<z.ZodBoolean>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    unique: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    description: z.ZodOptional<z.ZodString>;
+    renamed_from: z.ZodOptional<z.ZodString>;
+    cast: z.ZodOptional<z.ZodString>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare function castParts(cast: string): {
+    column: string;
+    type: string;
+} | null;
+
+declare const linkSchema: z.ZodObject<{
+    to: z.ZodString;
+    on: z.ZodString;
+    enforce: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const indexSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    unique: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>, z.ZodTransform<{
+    columns: string[];
+    unique?: boolean | undefined;
+    name?: string | undefined;
+}, string[] | {
+    columns: string[];
+    unique?: boolean | undefined;
+    name?: string | undefined;
+}>>;
+declare const tableFileSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    table: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            bigint: "bigint";
+            boolean: "boolean";
+            uuid: "uuid";
+            text: "text";
+            integer: "integer";
+            numeric: "numeric";
+            double: "double";
+            timestamptz: "timestamptz";
+            date: "date";
+            jsonb: "jsonb";
+        }>;
+        primary_key: z.ZodOptional<z.ZodBoolean>;
+        nullable: z.ZodOptional<z.ZodBoolean>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        description: z.ZodOptional<z.ZodString>;
+        renamed_from: z.ZodOptional<z.ZodString>;
+        cast: z.ZodOptional<z.ZodString>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    source: z.ZodOptional<z.ZodString>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        to: z.ZodString;
+        on: z.ZodString;
+        enforce: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    indexes: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+        columns: z.ZodArray<z.ZodString>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>, z.ZodTransform<{
+        columns: string[];
+        unique?: boolean | undefined;
+        name?: string | undefined;
+    }, string[] | {
+        columns: string[];
+        unique?: boolean | undefined;
+        name?: string | undefined;
+    }>>>>;
+    policies: z.ZodOptional<z.ZodObject<{
+        read: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ParsedPredicate, string>>>;
+        write: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ParsedPredicate, string>>>;
+    }, z.core.$strict>>;
+    actions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        requires: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ParsedPredicate, string>>>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                bigint: "bigint";
+                boolean: "boolean";
+                uuid: "uuid";
+                text: "text";
+                integer: "integer";
+                numeric: "numeric";
+                double: "double";
+                timestamptz: "timestamptz";
+                date: "date";
+                jsonb: "jsonb";
+            }>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        validates: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ValidatesEntry, string>>>>;
+        executes: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+        returns: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            bigint: "bigint";
+            boolean: "boolean";
+            uuid: "uuid";
+            text: "text";
+            integer: "integer";
+            numeric: "numeric";
+            double: "double";
+            timestamptz: "timestamptz";
+            date: "date";
+            jsonb: "jsonb";
+        }>>>;
+        audit: z.ZodOptional<z.ZodObject<{
+            action: z.ZodEnum<{
+                create: "create";
+                update: "update";
+                delete: "delete";
+            }>;
+            resource: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type TableFile = z.output<typeof tableFileSchema>;
+type LinkDefinition = z.output<typeof linkSchema>;
+type IndexDefinition = z.output<typeof indexSchema>;
+
+/**
+ * The namespace's Custom Roles manifest block — the platform grammar, verbatim
+ * (see custom-roles-block.ts). `roles` declares capabilities + roles (grants,
+ * inherits); `uses` attaches existing capabilities. Reconciled into the Custom
+ * Roles attachment set at apply, so it's grantable and enters claim resolution.
+ */
+interface NamespaceCapabilities {
+    readonly roles: CustomRolesBlock;
+    readonly uses: readonly string[];
+}
+interface NamespaceDefinition {
+    readonly namespace: string;
+    readonly description: string | null;
+    readonly capabilities: NamespaceCapabilities;
+    readonly tables: readonly TableFile[];
+}
+/** The capability claim keys the block declares — bare declarations plus every attach. */
+declare function declaredCapabilityKeys(capabilities: NamespaceCapabilities): Set<string>;
+interface DefinitionFile {
+    readonly file: string;
+    readonly table: TableFile;
+}
+declare function buildNamespaceDefinition(files: readonly DefinitionFile[], config?: NamespaceConfig): NamespaceDefinition;
+
+/**
+ * Emit the `Tables` type for a namespace — the generic parameter for
+ * `createOrmClient<…Tables>`. A `type` alias, deliberately not an
+ * `interface`: object type literals carry the implicit index signature that
+ * satisfies the client's `Record<string, Record<string, unknown>>`
+ * constraint; interfaces don't. Derived from the definitions alone (no
+ * database), so generation is deterministic and runs offline.
+ */
+declare function generateNamespaceTypes(definition: NamespaceDefinition): string;
+declare function typesInterfaceName(namespace: string): string;
+declare function actionsInterfaceName(namespace: string): string;
+
+declare function buildActionParamsSchema(action: ActionDefinition): z.ZodType<Record<string, unknown>>;
+/** Declared param names in signature order — the function's arg order and the executor's positional-call order. */
+declare const actionParamOrder: (action: ActionDefinition) => string[];
+/** The plpgsql argument name for a declared param — prefixed so it can never collide with a column of the same name inside the executes body. */
+declare const actionParamArg: (name: string) => string;
+/**
+ * Compile an action's `executes` (one statement or the ordered list) into the
+ * statements of its Postgres function body: `claim('x')`/`capability('k')`
+ * become the compiled fail-closed claims expressions (the same SQL policies
+ * use), and each `:param` becomes its `p_<name>` plpgsql argument — quoted
+ * literals pass through verbatim. A call shape outside the grammar (bad quoting,
+ * wrong args) fails loudly here; the build also rejects it in `executesIssues`.
+ */
+declare function compileActionStatements(action: ActionDefinition, renderParam?: (name: string) => string): string[];
+/** Compiled `requires` gate — a SQL boolean over the transaction claims, or null when unguarded. */
+declare function compileActionRequires(action: ActionDefinition): string | null;
+
+declare const COMPARE_OPS: readonly ["=", "!=", "<", "<=", ">", ">="];
+type CompareOp = (typeof COMPARE_OPS)[number];
+type Operand = {
+    kind: 'column';
+    name: string;
+} | {
+    kind: 'claim';
+    key: string;
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+};
+type Predicate = {
+    kind: 'and';
+    operands: readonly Predicate[];
+} | {
+    kind: 'or';
+    operands: readonly Predicate[];
+} | {
+    kind: 'not';
+    operand: Predicate;
+} | {
+    kind: 'compare';
+    op: CompareOp;
+    left: Operand;
+    right: Operand;
+} | {
+    kind: 'capability';
+    key: string;
+};
+interface ParsedPredicate {
+    readonly source: string;
+    readonly ast: Predicate;
+}
+declare function walkPredicate(predicate: Predicate, visit: (node: Predicate) => void): void;
+declare function predicateOperands(predicate: Predicate): Operand[];
+declare function referencedColumns(predicate: Predicate): string[];
+declare function referencedCapabilities(predicate: Predicate): string[];
+
+/** Column name → declared type, so claim comparisons can cast to the column's side. */
+type PredicateColumnTypes = Readonly<Record<string, ColumnType>>;
+/** Predicate AST → a parenthesized SQL boolean expression. Never interpolates raw policy text. */
+declare function compilePredicate(predicate: Predicate, columnTypes?: PredicateColumnTypes): string;
+
+/** Claims are stamped per transaction by the Data API (`set_config('request.jwt.claims', …, true)`). */
+declare const CLAIMS_SETTING = "request.jwt.claims";
+/** Claims JSON key holding the caller's granted capability pins (a string array). */
+declare const CAPABILITIES_CLAIM_KEY = "capabilities";
+declare const quoteIdentifier: (name: string) => string;
+declare const quoteLiteral: (value: string) => string;
+declare const claimExpression: (key: string) => string;
+/** NULL claims (or a missing capabilities array) coalesce to false — capability checks fail closed. */
+declare const capabilityExpression: (key: string) => string;
+
+/** Namespace names become Postgres identifiers (`orm_<ns>` schema, `orm_<ns>_consumer` role) — the tight grammar is a security control, not cosmetics. */
+declare const NAMESPACE_PATTERN: RegExp;
+declare const IDENTIFIER_PATTERN: RegExp;
+declare const MAX_IDENTIFIER_LENGTH = 63;
+/**
+ * The Data API carries a delegated, attenuated data token on this header (not
+ * `Authorization`, which stays the app-user/session bearer). One definition
+ * shared by the client transport, the server's caller resolver, and the
+ * function-invoke minter, so all three agree.
+ */
+declare const ORM_DATA_TOKEN_HEADER = "x-sequence-data-token";
+/**
+ * The SEPARATE header the invoke proxy uses to hand a managed function its
+ * *service* data token — the escalation path. A function receives BOTH this and
+ * `ORM_DATA_TOKEN_HEADER`; the default `createOrmClient` reads the user token,
+ * the deliberately-named `createServiceOrmClient` reads THIS one. Two distinct
+ * headers so reaching for the service identity is always an explicit act, never
+ * an accidental default. Both are sent to the Data API on `ORM_DATA_TOKEN_HEADER`
+ * — the server stays mode-agnostic and resolves whatever sub the token carries.
+ */
+declare const ORM_SERVICE_DATA_TOKEN_HEADER = "x-sequence-data-token-service";
+/**
+ * Custom Roles & Capabilities claim keys as policies reference them: a
+ * host-scoped registry key, or an org pin's `org/<key>`. Matches the registry
+ * key grammar EXACTLY (`[a-z0-9-]`, 1–64 chars, no `_` — the FGA object-id
+ * delimiter) so any capability that's declarable/attachable in namespace.yaml
+ * can also be referenced here — a stricter pattern would let a valid key
+ * register yet fail at apply (e.g. `org/2fa`, a one-char or digit-led key).
+ */
+declare const CAPABILITY_KEY_PATTERN: RegExp;
+declare const CLAIM_KEY_PATTERN: RegExp;
+/** Qualified reference to a table outside the defining file: `<schema>.<table>`. */
+declare const QUALIFIED_TABLE_PATTERN: RegExp;
+/** Synced reflected sources are restricted to the gold layer. */
+declare const SYNCED_SOURCE_PATTERN: RegExp;
+declare const ORM_SCHEMA_PREFIX = "orm_";
+declare const CONSUMER_ROLE_SUFFIX = "_consumer";
+declare const ormSchemaName: (namespace: string) => string;
+declare const consumerRoleName: (namespace: string) => string;
+declare const DEFINITION_FILE_EXTENSIONS: readonly [".yml", ".yaml"];
+/** Reserved basenames for the namespace-level config file (description, org capability pins). */
+declare const NAMESPACE_CONFIG_FILENAMES: Set<string>;
+declare const HASH_DOMAIN = "sequence-orm-definitions\0";
+/**
+ * The one size guard the package owns: a per-file byte cap where the loader
+ * reads untrusted YAML into memory — a real failure mode, not a product
+ * limit. Counts of tables/indexes/params and policy/SQL lengths are
+ * deliberately uncapped; Postgres enforces its own limits loudly at apply.
+ */
+declare const MAX_DEFINITION_FILE_BYTES: number;
+/** `/api/data/<ns>/actions/…` and `/api/data/<ns>/query` share the table path segment. */
+declare const RESERVED_TABLE_NAMES: Set<string>;
+/**
+ * The Data API's query-string grammar owns these parameter names — a column
+ * with one of them could never be filtered over the wire, so definitions
+ * refuse it up front ("validate rejects only what can never work").
+ */
+declare const RESERVED_COLUMN_NAMES: Set<string>;
+
+/** drizzle-kit's serialized schema — the diff/replay artifact the registry stores. */
+type NamespaceSnapshot = ReturnType<typeof generateDrizzleJson>;
+declare function generateSnapshot(definition: NamespaceDefinition, previousId?: string): NamespaceSnapshot;
+declare const emptySnapshot: (namespace: string) => NamespaceSnapshot;
+/**
+ * Persisted snapshots (registry version rows, committed migrations/meta)
+ * outlive drizzle-kit upgrades. `upPgSnapshot` migrates older snapshot
+ * formats to the kit's current one; a snapshot that still isn't current
+ * after upgrading came from a NEWER kit than this one — fail loudly rather
+ * than let the diff silently misread it.
+ */
+declare function normalizeSnapshot(snapshot: NamespaceSnapshot): NamespaceSnapshot;
+declare function diffStatements(previous: NamespaceSnapshot, current: NamespaceSnapshot): Promise<string[]>;
+interface MigrationHints {
+    /** ALTER RENAME / ALTER TYPE USING statements to run before the kit diff. */
+    readonly statements: string[];
+    /** Previous snapshot rewritten so the kit diff never sees the rename/cast. */
+    readonly adjusted: NamespaceSnapshot;
+}
+/**
+ * Renames and casts are declared in the YAML, never inferred: we emit the
+ * statement ourselves and rewrite the previous snapshot to match, so
+ * drizzle-kit never faces a create+drop ambiguity (its API resolves those
+ * interactively — fatal in a service).
+ */
+declare function applyMigrationHints(previous: NamespaceSnapshot, definition: NamespaceDefinition): MigrationHints;
+
+/**
+ * Whether a kit-emitted statement is one the security pass owns (and so is
+ * excluded from the convergence verdict). Exported for direct testing of the
+ * classification, which is load-bearing: a false positive silently drops a real
+ * pending statement and lets a non-converged schema pass.
+ */
+declare function isOwnedStatement(statement: string): boolean;
+/**
+ * The kit-owned statements a live database would still need to match the
+ * definition — drizzle-kit's `pushSchema` introspection diffed against the
+ * built entities. Empty means the schema converged: what the rehearsal (or
+ * any verification) uses as the introspect-level proof that executing the
+ * plan actually produced the desired state, not merely that it didn't error.
+ */
+declare function pendingKitStatements({ definition, db, }: {
+    definition: NamespaceDefinition;
+    /** A drizzle PgDatabase over the target — typed loose because pushSchema's own parameter is `PgDatabase<any>`. */
+    db: unknown;
+}): Promise<string[]>;
+
+interface DrizzleEntities {
+    /** The in-memory schema bag drizzle-kit snapshots (`generateDrizzleJson(imports)`). */
+    readonly imports: Record<string, unknown>;
+    /** Tables by definition name — the typed handles query execution uses. */
+    readonly tables: Record<string, PgTableWithColumns<never>>;
+    readonly schemaName: string;
+}
+/**
+ * Definitions → runtime Drizzle entities. Tables build in dependency order so
+ * enforced links can reference their target's built column; policies attach in
+ * the table's extras with predicates compiled from the parsed AST — raw policy
+ * text never reaches SQL. Tables without policies stay RLS-enabled: default deny.
+ */
+declare function buildDrizzleEntities(definition: NamespaceDefinition): DrizzleEntities;
+
+/**
+ * SQLSTATEs the action function raises for the two application-level denials
+ * that Postgres has no native code for. Custom 5-char classes (unused by
+ * Postgres) so the executor maps them precisely: requires → 403, validates →
+ * 422. RLS `WITH CHECK`, constraints, and bad values keep their native codes.
+ */
+declare const ACTION_REQUIRES_DENIED_SQLSTATE = "ORMRQ";
+declare const ACTION_VALIDATES_FAILED_SQLSTATE = "ORMVL";
+/** Internal function name for a declared action — the `action_` prefix is what the reconcile sweep drops. */
+declare const actionFunctionName: (actionName: string) => string;
+/**
+ * Every declared action becomes a `SECURITY INVOKER` Postgres function, so the
+ * apply-time `CREATE FUNCTION` is where Postgres validates the SQL (with
+ * `check_function_bodies` on, a bad column/table reference fails the apply and
+ * the action never goes live) and the invoke path is a single `SELECT fn(...)`
+ * under the consumer role — no client-side statement rewriting at call time.
+ *
+ * Actions carry no data and are absent from the drizzle snapshot, so instead
+ * of diffing them we reconcile: a leading sweep drops every `action_*` function
+ * in the schema (clearing removed/renamed/retyped ones — a signature change
+ * can't `CREATE OR REPLACE`), then each current action is created fresh. Runs
+ * last in the plan because the bodies reference tables the earlier DDL creates.
+ */
+declare function actionFunctionStatements(definition: NamespaceDefinition): string[];
+/**
+ * PREPARE each action's executes at apply so Postgres parses and plans it
+ * against the live schema — catching unknown columns/tables/types that a
+ * plpgsql function body does NOT check at CREATE (it defers to first invoke).
+ * A failed PREPARE aborts the apply, so a broken action never goes live. Runs
+ * on the migration connection with the namespace on search_path; the prepared
+ * statements die with that connection, so no DEALLOCATE is needed.
+ */
+declare function actionPrepareChecks(definition: NamespaceDefinition): string[];
+
+/**
+ * The security statements the kit never sees — FORCE row security (so
+ * policies bind the table owner too), the row policies themselves, and the
+ * grants that let the Data API's consumer role reach the namespace.
+ *
+ * Policies deliberately bypass drizzle-kit's diff: its API resolves
+ * create+drop pairs interactively (fatal in a service), and they are cheap
+ * and fully determined by the definition — so every apply drops and
+ * recreates them. Writes compile to command-scoped policies, never FOR ALL:
+ * permissive policies OR together, so an all-commands policy would let
+ * write-capable callers SELECT rows the read policy hides.
+ */
+declare function securityStatements(definition: NamespaceDefinition): string[];
+
+declare const sqlTypeName: (type: ColumnType) => string;
+
+declare const STATEMENT_KINDS: readonly ["hint", "ddl", "security", "function"];
+type StatementKind = (typeof STATEMENT_KINDS)[number];
+interface CompiledStatement {
+    readonly kind: StatementKind;
+    readonly sql: string;
+}
+interface PlannedMigration {
+    readonly namespace: string;
+    readonly schema: string;
+    readonly statements: readonly CompiledStatement[];
+    /** Snapshot of the desired state — persisted by the registry, previous input to the next plan. */
+    readonly snapshot: NamespaceSnapshot;
+}
+/**
+ * Desired definition + the previously applied snapshot → ordered statements.
+ * The owned policies on pre-existing tables drop first (Postgres refuses to
+ * alter or drop a column a live policy depends on), hints (declared
+ * renames/casts) rewrite the previous snapshot, drizzle-kit diffs the
+ * remainder, and the owned security statements (FORCE RLS, recreated
+ * policies, consumer grants) close every migration.
+ */
+declare function planMigration({ definition, previousSnapshot, }: {
+    definition: NamespaceDefinition;
+    previousSnapshot?: NamespaceSnapshot;
+}): Promise<PlannedMigration>;
+/** Full-create plan (empty previous snapshot) — what `plan` prints and first apply runs. */
+declare const compileNamespace: (definition: NamespaceDefinition) => Promise<PlannedMigration>;
+
+declare class OrmDefinitionError extends Error {
+    readonly file?: string | undefined;
+    readonly name = "OrmDefinitionError";
+    constructor(message: string, file?: string | undefined);
+}
+declare class PredicateParseError extends Error {
+    readonly position: number;
+    readonly name = "PredicateParseError";
+    constructor(message: string, position: number);
+}
+
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Key-sorted, undefined-skipped JSON — identical definitions hash identically regardless of YAML key order. */
+declare function stableJson(value: unknown): string;
+declare function canonicalizeDefinition(definition: NamespaceDefinition): JsonValue;
+declare function computeDefinitionHash(definition: NamespaceDefinition): string;
+
+interface LoadedNamespace {
+    readonly definition: NamespaceDefinition;
+    readonly contentHash: string;
+    readonly files: readonly string[];
+}
+declare function parseTableFile(file: string, contents: string): DefinitionFile;
+interface DefinitionSource {
+    readonly path: string;
+    readonly contents: string;
+}
+/**
+ * Raw sources → validated definition, splitting the reserved namespace
+ * config file from the table files. The one parse path for the loader and
+ * the registry, so a local directory and an uploaded bundle can't diverge.
+ */
+declare function parseDefinitionSources(sources: readonly DefinitionSource[]): NamespaceDefinition;
+declare function loadNamespaceDefinition(dir: string): Promise<LoadedNamespace>;
+
+interface DestructiveStatement {
+    readonly sql: string;
+    readonly reason: string;
+}
+declare function classifyDestructive(statements: readonly CompiledStatement[]): DestructiveStatement[];
+
+/**
+ * The reviewed migration a registration carries: replay-only environments
+ * (production, banksouth) execute nothing that doesn't match one of these.
+ * Statements are recomputed at load and verified to reproduce the committed
+ * file byte-for-byte, so the payload can never drift from what review saw.
+ */
+interface CommittedMigration {
+    readonly name: string;
+    readonly ordinal: number;
+    readonly previous_content_hash: string | null;
+    readonly destructive: boolean;
+    readonly checksum: string;
+    readonly statements: readonly CompiledStatement[];
+}
+/**
+ * Load the workspace tip as a registration payload. Returns null when there
+ * is no workspace (dev-loop registrations stay migration-less); throws when
+ * a workspace exists but is stale or drifted — a half-true artifact is worse
+ * than none.
+ */
+declare function loadCommittedTipMigration(dir: string, loaded: LoadedNamespace): Promise<CommittedMigration | null>;
+/**
+ * One link in the committed history: a migration's content hash and the hash it
+ * was diffed FROM. This is an ancestry record, NOT executable SQL — a
+ * registration carries the whole chain so a replay-only environment can prove
+ * that its active version is a reviewed ancestor of the target (and thus that a
+ * direct catch-up diff is in-lineage) even over migrations that were never
+ * registered there (batched deploys, skipped releases). The catch-up apply then
+ * runs the engine's own direct diff, never any SQL from this chain.
+ */
+interface CommittedChainEntry {
+    readonly name: string;
+    readonly contentHash: string;
+    readonly previousContentHash: string | null;
+}
+/**
+ * The committed hash chain for a definitions directory, oldest-first, taken from
+ * the journal (already integrity-checked by `orm validate` / `diff --check`).
+ * The tip must match the loaded definitions — a registration carries this so
+ * replay-only environments can verify catch-up ancestry without those
+ * intervening versions being registered. Empty when there is no workspace.
+ */
+declare function loadCommittedMigrations(dir: string, loaded: LoadedNamespace): Promise<CommittedChainEntry[]>;
+
+interface DiffOptions {
+    readonly dir: string;
+    readonly allowDestructive: boolean;
+    readonly check: boolean;
+    readonly log: (line: string) => void;
+}
+/**
+ * `orm diff` — append the next committed migration for a definitions
+ * directory, diffed against the workspace's tip snapshot. `--check` is the
+ * CI gate: no database, no credentials — verify checksums, the snapshot
+ * chain, that the definitions match the journal tip, and that regenerating
+ * the tip reproduces the committed file byte-for-byte.
+ */
+declare function diffCommand({ dir, allowDestructive, check, log }: DiffOptions): Promise<number>;
+
+/**
+ * The committed migration workspace inside a definitions directory:
+ *
+ *   <dir>/migrations/NNNN_<hash12>.sql        reviewable statements
+ *   <dir>/migrations/meta/NNNN.snapshot.json  desired-state snapshot after NNNN
+ *   <dir>/migrations/meta/journal.json        ordered index with checksums
+ *
+ * `orm diff` appends to it; `orm diff --check` (the CI gate) verifies it
+ * matches the definitions with no database and no credentials. Everything
+ * here is deterministic from (previous snapshot, definition) so the gate
+ * can regenerate and byte-compare.
+ */
+declare const MIGRATIONS_DIRNAME = "migrations";
+declare const journalEntrySchema: z.ZodObject<{
+    ordinal: z.ZodNumber;
+    name: z.ZodString;
+    content_hash: z.ZodString;
+    previous_content_hash: z.ZodNullable<z.ZodString>;
+    checksum: z.ZodString;
+    snapshot_checksum: z.ZodString;
+    destructive: z.ZodBoolean;
+}, z.core.$strip>;
+declare const journalSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    namespace: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        ordinal: z.ZodNumber;
+        name: z.ZodString;
+        content_hash: z.ZodString;
+        previous_content_hash: z.ZodNullable<z.ZodString>;
+        checksum: z.ZodString;
+        snapshot_checksum: z.ZodString;
+        destructive: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type MigrationJournal = z.infer<typeof journalSchema>;
+type JournalEntry = z.infer<typeof journalEntrySchema>;
+interface MigrationWorkspace {
+    readonly journal: MigrationJournal;
+    /** Snapshot at the journal tip — the previous input for the next diff. */
+    readonly tipSnapshot: NamespaceSnapshot | undefined;
+}
+declare const emptyJournal: (namespace: string) => MigrationJournal;
+declare function readMigrationWorkspace(dir: string, namespace: string): Promise<MigrationWorkspace>;
+declare function readSnapshot(dir: string, ordinal: number): Promise<NamespaceSnapshot>;
+declare function readMigrationSql(dir: string, entry: JournalEntry): Promise<string>;
+declare const checksumOf: (text: string) => string;
+declare const migrationName: (ordinal: number, contentHash: string) => string;
+declare function renderMigrationSql({ name, namespace, contentHash, plan, }: {
+    name: string;
+    namespace: string;
+    contentHash: string;
+    plan: PlannedMigration;
+}): string;
+interface WrittenMigration {
+    readonly name: string;
+    readonly ordinal: number;
+    readonly destructive: boolean;
+}
+declare function writeMigration({ dir, workspace, plan, contentHash, destructive, }: {
+    dir: string;
+    workspace: MigrationWorkspace;
+    plan: PlannedMigration;
+    contentHash: string;
+    destructive: boolean;
+}): Promise<WrittenMigration>;
+
+declare function parsePredicate(source: string): ParsedPredicate;
+
+declare const identifierSchema: z.ZodString;
+declare const namespaceSchema: z.ZodString;
+/** `<table>` for a table in the same namespace, `<schema>.<table>` for anything else. */
+declare const tableReferenceSchema: z.ZodString;
+declare const isQualifiedReference: (reference: string) => boolean;
+
+/**
+ * Rehydrate a stored canonical definition (see hash.ts) back into a validated
+ * NamespaceDefinition — predicates re-parse from their source strings, every
+ * invariant re-checks. The registry is never trusted blindly: callers compare
+ * computeDefinitionHash(result) against the stored content hash.
+ */
+declare function parseCanonicalDefinition(value: unknown): NamespaceDefinition;
+
+declare const parsedPredicateSchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedPredicate, string>>;
+
+export { ACTION_REQUIRES_DENIED_SQLSTATE, ACTION_VALIDATES_FAILED_SQLSTATE, AUDIT_ACTIONS, type ActionDefinition, CAPABILITIES_CLAIM_KEY, CAPABILITY_KEY_PATTERN, CLAIMS_SETTING, CLAIM_KEY_PATTERN, COLUMN_TYPES, COMPARE_OPS, CONSUMER_ROLE_SUFFIX, type ColumnDefault, type ColumnDefinition, type ColumnType, type CommittedChainEntry, type CommittedMigration, type CompareOp, type CompiledStatement, type CustomRolesBlock, DEFINITION_FILE_EXTENSIONS, type DefinitionFile, type DefinitionSource, type DestructiveStatement, type DiffOptions, type DrizzleEntities, HASH_DOMAIN, IDENTIFIER_PATTERN, type IndexDefinition, type JournalEntry, type LinkDefinition, type LoadedNamespace, MAX_DEFINITION_FILE_BYTES, MAX_IDENTIFIER_LENGTH, MIGRATIONS_DIRNAME, type MigrationJournal, type MigrationWorkspace, NAMESPACE_CONFIG_FILENAMES, NAMESPACE_PATTERN, type NamespaceCapabilities, type NamespaceConfig, type NamespaceDefinition, type NamespaceSnapshot, ORM_DATA_TOKEN_HEADER, ORM_SCHEMA_PREFIX, ORM_SERVICE_DATA_TOKEN_HEADER, type Operand, OrmDefinitionError, type ParsedPredicate, type PlannedMigration, type Predicate, PredicateParseError, QUALIFIED_TABLE_PATTERN, RESERVED_COLUMN_NAMES, RESERVED_TABLE_NAMES, STATEMENT_KINDS, SYNCED_SOURCE_PATTERN, type StatementKind, type TableFile, type ValidatesEntry, type WrittenMigration, actionFunctionName, actionFunctionStatements, actionParamArg, actionParamOrder, actionParamSchema, actionPrepareChecks, actionSchema, actionsInterfaceName, applyMigrationHints, buildActionParamsSchema, buildDrizzleEntities, buildNamespaceDefinition, canonicalizeDefinition, capabilityExpression, capabilityPinsSchema, castParts, checksumOf, claimExpression, classifyDestructive, columnSchema, columnTypeSchema, compileActionRequires, compileActionStatements, compileNamespace, compilePredicate, computeDefinitionHash, consumerRoleName, customRolesBlockSchema, customRolesDeclared, declaredCapabilityKeys, diffCommand, diffStatements, emptyJournal, emptySnapshot, extractNamedParams, generateNamespaceTypes, generateSnapshot, identifierSchema, isFunctionDefault, isOwnedStatement, isQualifiedReference, loadCommittedMigrations, loadCommittedTipMigration, loadNamespaceDefinition, migrationName, namespaceConfigSchema, namespaceSchema, normalizeSnapshot, ormSchemaName, parseCanonicalDefinition, parseCapabilityPin, parseDefinitionSources, parsePredicate, parseTableFile, parsedPredicateSchema, pendingKitStatements, planMigration, predicateOperands, quoteIdentifier, quoteLiteral, readMigrationSql, readMigrationWorkspace, readSnapshot, referencedCapabilities, referencedColumns, renderMigrationSql, securityStatements, sqlTypeName, stableJson, tableFileSchema, tableReferenceSchema, typesInterfaceName, validateCapabilityPins, walkPredicate, writeMigration };