okmodel 0.0.0 → 0.1.0

package/dist/contracts/catalog/types.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Catalog kinds, identity, and the shared envelope.
+ *
+ * Every object uses one envelope (kind, identity, owner, definition,
+ * dependencies, provenance). Kinds other than table, column, index,
+ * constraint, sequence, and type (enum) are named here so a later prompt
+ * can fill them in without changing the envelope.
+ */
+/** Who may change an object. `ignored` is invisible to diffs. */
+export declare const OWNERS: readonly ["managed", "external", "ignored"];
+/** Ownership stored on every catalog object. */
+export type Owner = (typeof OWNERS)[number];
+/**
+ * Object kinds from spec section 5.7.
+ *
+ * Built in this layer: table, column, index, constraint, sequence, and type.
+ * A type object is an enum: ordered labels, and no other form.
+ */
+export declare const OBJECT_KINDS: readonly ["table", "column", "index", "constraint", "sequence", "view", "materializedView", "type", "function", "trigger", "policy", "extension", "role", "grant", "defaultPrivilege"];
+/** A catalog object kind. */
+export type ObjectKind = (typeof OBJECT_KINDS)[number];
+/** Kinds that have factories in this layer. */
+export declare const BUILT_KINDS: readonly ["table", "column", "index", "constraint", "sequence", "type"];
+/** A kind this layer can construct. */
+export type BuiltKind = (typeof BUILT_KINDS)[number];
+/**
+ * Lifecycle operations a kind declares.
+ *
+ * Spec section 5.7: create, replace when compatible, alter, drop, and
+ * recreate-with-dependents.
+ */
+export declare const OBJECT_OPERATIONS: readonly ["create", "replace", "alter", "drop", "recreateWithDependents"];
+/** One lifecycle operation. */
+export type ObjectOperation = (typeof OBJECT_OPERATIONS)[number];
+/**
+ * Operations each kind declares.
+ *
+ * Roles are created and altered in place and are never dropped (D119).
+ * Materialized views have no replace. Grants and default privileges are
+ * declared so the map covers section 5.7; those objects are not built here.
+ */
+export declare const KIND_OPERATIONS: {
+    readonly [K in ObjectKind]: readonly ObjectOperation[];
+};
+/**
+ * A schema name.
+ *
+ * `static` is a concrete schema. `template` keeps a pattern such as
+ * `tenant_{id}`. Snapshots and diffs store the template.
+ */
+export type Namespace = {
+    readonly form: "static";
+    readonly name: string;
+} | {
+    readonly form: "template";
+    readonly pattern: string;
+};
+/**
+ * A table (or other namespace-qualified parent) inside a namespace.
+ *
+ * The namespace may be a template. It is not resolved here.
+ */
+export type ObjectRef = {
+    readonly namespace: Namespace;
+    readonly name: string;
+};
+/** Identity of a table, view, materialized view, sequence, or type. */
+export type NamespaceIdentity = {
+    readonly kind: "table" | "view" | "materializedView" | "sequence" | "type";
+    readonly namespace: Namespace;
+    readonly name: string;
+};
+/**
+ * Identity of an object that lives on a parent table.
+ *
+ * Columns, indexes, and constraints use `(parent, name)`. Triggers and
+ * policies use `(table, name)`, the same shape.
+ */
+export type AnchoredIdentity = {
+    readonly kind: "column" | "index" | "constraint" | "trigger" | "policy";
+    readonly parent: ObjectRef;
+    readonly name: string;
+};
+/** Function identity. Argument types keep overloads distinct. */
+export type FunctionIdentity = {
+    readonly kind: "function";
+    readonly namespace: Namespace;
+    readonly name: string;
+    readonly argTypes: readonly string[];
+};
+/**
+ * Grant identity.
+ *
+ * The key is `(role, object, privilege)`. It is not a stored identifier and
+ * is exempt from the dialect length limit (D119).
+ */
+export type GrantIdentity = {
+    readonly kind: "grant";
+    readonly role: string;
+    readonly object: GrantObjectRef;
+    readonly privilege: string;
+};
+/** What a grant attaches to. `namespace` is the schema itself. */
+export type GrantObjectRef = {
+    readonly kind: "table" | "sequence" | "namespace";
+    readonly namespace: Namespace;
+    readonly name: string;
+};
+/**
+ * Default-privilege identity.
+ *
+ * The key is `(forRole, namespace, objectKind, grantee, privilege)`. It is
+ * exempt from the dialect length limit (D119).
+ */
+export type DefaultPrivilegeIdentity = {
+    readonly kind: "defaultPrivilege";
+    readonly forRole: string;
+    readonly namespace: Namespace;
+    readonly objectKind: string;
+    readonly grantee: string;
+    readonly privilege: string;
+};
+/** Role identity. Roles are cluster objects and have no namespace. */
+export type RoleIdentity = {
+    readonly kind: "role";
+    readonly name: string;
+};
+/** Extension identity. Extensions are database-scoped and have no namespace. */
+export type ExtensionIdentity = {
+    readonly kind: "extension";
+    readonly name: string;
+};
+/** Stable identity. The variant depends on the kind. */
+export type ObjectIdentity = NamespaceIdentity | AnchoredIdentity | FunctionIdentity | GrantIdentity | DefaultPrivilegeIdentity | RoleIdentity | ExtensionIdentity;
+/** Where an object came from. */
+export type Provenance = {
+    readonly origin: "file";
+    readonly name: string;
+} | {
+    readonly origin: "trait";
+    readonly name: string;
+} | {
+    readonly origin: "extension";
+    readonly name: string;
+};
+/**
+ * An edge to another object.
+ *
+ * A target whose kind is `column` is column granularity. Any other kind is
+ * object granularity.
+ */
+export type DependencyEdge = {
+    readonly target: ObjectIdentity;
+};
+/** How a partitioned table assigns rows. */
+export type PartitionMethod = "range" | "list" | "hash";
+/** Table definition. Columns, indexes, and constraints are their own objects. */
+export type TableDefinition = {
+    readonly partition?: {
+        readonly method: PartitionMethod;
+        readonly columns: readonly string[];
+    };
+};
+/**
+ * Column definition.
+ *
+ * `dataType` is the type name (`uuid`, `text`, `varchar(200)`), not a SQL
+ * expression. At most one of `defaultExpression`, `identity`, and `generated`
+ * is set.
+ */
+export type ColumnDefinition = {
+    readonly dataType: string;
+    readonly nullable: boolean;
+    readonly defaultExpression?: string;
+    readonly identity?: {
+        readonly always: boolean;
+    };
+    readonly generated?: {
+        readonly stored: boolean;
+        readonly expression: string;
+    };
+};
+/**
+ * Index definition.
+ *
+ * `nameKey` is the stable token the name was generated from. It does not
+ * follow a later field rename. Column order is significant.
+ */
+export type IndexDefinition = {
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    readonly nameKey: string;
+    readonly predicate?: string;
+    readonly expression?: string;
+};
+/** Constraint family. */
+export type ConstraintKind = "primaryKey" | "unique" | "foreignKey" | "check";
+/**
+ * What Postgres does when a referenced row changes.
+ *
+ * Stored on the foreign key so `onDelete` and `onUpdate` survive compile.
+ */
+export declare const REFERENTIAL_ACTIONS: readonly ["cascade", "no action", "restrict", "set default", "set null"];
+/** One referential action. */
+export type ReferentialAction = (typeof REFERENTIAL_ACTIONS)[number];
+/**
+ * Returns the action when `value` is one this catalog stores.
+ *
+ * @param value - Author or document text
+ * @returns The action, or `undefined` when it is not in the list
+ */
+export declare function referentialAction(value: string): ReferentialAction | undefined;
+/** Constraint definition. `nameKey` stays put when a field is renamed. */
+export type ConstraintDefinition = {
+    readonly constraintKind: ConstraintKind;
+    readonly columns: readonly string[];
+    readonly nameKey: string;
+    readonly deferrable: boolean;
+    readonly initially: "immediate" | "deferred";
+    readonly nullsNotDistinct: boolean;
+    readonly expression?: string;
+    readonly references?: {
+        readonly parent: ObjectRef;
+        readonly columns: readonly string[];
+        readonly onDelete?: ReferentialAction;
+        readonly onUpdate?: ReferentialAction;
+    };
+};
+/**
+ * Enum definition.
+ *
+ * `labels` is the stored order. That order is part of the catalog hash.
+ * Domains are not represented here.
+ */
+export type TypeDefinition = {
+    readonly labels: readonly string[];
+};
+/** Sequence definition. Start and increment are decimal integers. */
+export type SequenceDefinition = {
+    readonly dataType: "smallint" | "integer" | "bigint";
+    readonly start: string;
+    readonly increment: string;
+    readonly cycle: boolean;
+};
+/** Shared fields on every catalog object. */
+export type CatalogEnvelope<K extends ObjectKind, I extends ObjectIdentity, D> = {
+    readonly kind: K;
+    readonly identity: I;
+    readonly owner: Owner;
+    readonly definition: D;
+    readonly dependencies: readonly DependencyEdge[];
+    readonly provenance: Provenance;
+};
+/** A table, possibly partitioned. Copied partition keys are not objects. */
+export type TableObject = CatalogEnvelope<"table", NamespaceIdentity & {
+    readonly kind: "table";
+}, TableDefinition>;
+/** A column of a table. */
+export type ColumnObject = CatalogEnvelope<"column", AnchoredIdentity & {
+    readonly kind: "column";
+}, ColumnDefinition>;
+/** A secondary index. */
+export type IndexObject = CatalogEnvelope<"index", AnchoredIdentity & {
+    readonly kind: "index";
+}, IndexDefinition>;
+/** A table constraint. */
+export type ConstraintObject = CatalogEnvelope<"constraint", AnchoredIdentity & {
+    readonly kind: "constraint";
+}, ConstraintDefinition>;
+/** A sequence. */
+export type SequenceObject = CatalogEnvelope<"sequence", NamespaceIdentity & {
+    readonly kind: "sequence";
+}, SequenceDefinition>;
+/** An enum. Identity is `(namespace, name)`. */
+export type TypeObject = CatalogEnvelope<"type", NamespaceIdentity & {
+    readonly kind: "type";
+}, TypeDefinition>;
+/**
+ * One built catalog object.
+ *
+ * Views, functions, triggers, extensions, roles, grants, and default
+ * privileges use {@link CatalogEnvelope} when they are built. They are not
+ * part of this union yet.
+ */
+export type CatalogObject = TableObject | ColumnObject | IndexObject | ConstraintObject | SequenceObject | TypeObject;
+/** Format version stored in the serialized catalog. */
+export declare const CATALOG_VERSION = 1;
+/** A catalog document. Object order is identity-key order. */
+export type Catalog = {
+    readonly version: typeof CATALOG_VERSION;
+    readonly objects: readonly CatalogObject[];
+};

package/dist/contracts/catalog/words.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PostgreSQL reserved keywords.
+ *
+ * An unquoted reserved word is rejected (OKM1122). Non-reserved keywords are
+ * allowed as names. The list is the PostgreSQL 17 "reserved" column. The set
+ * is built on first use.
+ */
+/**
+ * Reserved keywords, lowercase.
+ *
+ * @returns The PostgreSQL reserved-word set
+ */
+export declare function reservedWords(): ReadonlySet<string>;

package/dist/contracts/connection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Connection failures shared by adapters and the Postgres error mapping.
+ *
+ * A lost connection during `COMMIT` is `outcome_unknown` (the adapter decides
+ * that). Any other connection failure is kind `unavailable`.
+ */
+/**
+ * Reports whether `sqlstate` is a connection or availability class.
+ *
+ * Class `08` is connection exception. `53300` is too many connections.
+ * `57P01`–`57P03` are shutdown and "cannot connect now".
+ *
+ * @param sqlstate - Postgres SQLSTATE
+ * @returns `true` when the server could not keep the session
+ */
+export declare function isConnectionSqlstate(sqlstate: string): boolean;
+/**
+ * Reports whether a driver or OS code means the socket is gone.
+ *
+ * @param code - `error.code` from Node or the driver
+ * @returns `true` for a refused, reset, or closed connection
+ */
+export declare function isConnectionErrno(code: string): boolean;
+/**
+ * Reports whether `error` is a dropped or refused connection.
+ *
+ * Constraint failures are not connection failures. `23505` stays a unique
+ * violation even when it is raised at commit.
+ *
+ * @param error - Caught value
+ * @returns `true` when no session remains
+ */
+export declare function isConnectionFailure(error: unknown): boolean;

package/dist/contracts/driver.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Driver contract (spec §4.2). Types only: this module has no runtime.
+ *
+ * Adapters implement these shapes. Values cross the boundary as wire text.
+ * Codecs stay in the dialect.
+ */
+/** How a driver runs transactions. Atomic `batch` is not a mode. */
+export type TransactionMode = "interactive" | "batch" | "none";
+/** How a driver prepares statements. */
+export type PreparedMode = "named" | "unnamed" | "none";
+/**
+ * Execution capabilities for one driver (spec §4).
+ *
+ * Atomic `batch` is required on every driver and is not a flag.
+ */
+export type DriverCapabilities = {
+    /** `reserve` exists only when this is `"interactive"`. */
+    readonly transactions: TransactionMode;
+    /** Rows can be pulled in chunks. */
+    readonly stream: boolean;
+    /** `LISTEN` / `NOTIFY`. */
+    readonly listen: boolean;
+    /** An in-flight statement can be aborted. */
+    readonly cancel: boolean;
+    /** Prepared-statement mode this driver uses. */
+    readonly prepared: PreparedMode;
+    /** The server can describe a statement without running it. */
+    readonly describe: boolean;
+};
+/** A Postgres wire value. Null is SQL NULL. */
+export type WireValue = string | null;
+/** One statement. `$1` is `params[0]`. */
+export type Statement = {
+    readonly text: string;
+    /** Wire parameters. Omitted when the statement has none. */
+    readonly params?: readonly WireValue[];
+};
+/** A server notice, normalised from the driver's own notice object. */
+export type Notice = {
+    readonly severity: string;
+    readonly code?: string;
+    readonly message: string;
+};
+/**
+ * Result of one statement.
+ *
+ * `count` is the affected-row count. `rows` are wire text.
+ */
+export type ExecuteResult = {
+    readonly rows: readonly (readonly WireValue[])[];
+    readonly count: number;
+    readonly notices: readonly Notice[];
+};
+/** Per-call cancellation and deadline (spec §4.2, §15). */
+export type ExecuteOptions = {
+    /** Abort the call. An abort is kind `cancelled`. */
+    readonly signal?: AbortSignal;
+    /**
+     * Milliseconds for the whole call.
+     *
+     * A deadline is kind `timeout`.
+     */
+    readonly timeout?: number;
+};
+/** Column names and parameter count from a describe. */
+export type DescribeResult = {
+    readonly columns: readonly string[];
+    readonly parameterCount: number;
+};
+/** Pool counters for selection strategies (spec §4.2). */
+export type DriverStats = {
+    readonly size: number;
+    readonly idle: number;
+    readonly inflight: number;
+    readonly waiting: number;
+};
+/**
+ * Why a call ended before a statement result (D124).
+ *
+ * `outcome_unknown` means a commit was sent and the result never arrived.
+ * The dialect maps it to OKM1401. Adapters do not construct `OkmError`.
+ */
+export type DriverFailureKind = "timeout" | "cancelled" | "outcome_unknown";
+/**
+ * Fields on {@link DriverError}.
+ *
+ * `batchIndex` is the failing statement, or `null` when the failure is the
+ * commit itself (a deferred constraint). `kind` is set for a timeout, an
+ * abort, or a commit whose result never arrived, and is absent on a database
+ * error.
+ */
+export type DriverErrorFields = {
+    readonly sqlstate?: string;
+    readonly constraint?: string;
+    readonly table?: string;
+    readonly column?: string;
+    readonly detail?: string;
+    readonly cause?: unknown;
+    readonly batchIndex?: number | null;
+    readonly kind?: DriverFailureKind;
+};
+/**
+ * A connection checked out of a pool.
+ *
+ * Present when `transactions` is `"interactive"`. `batch` on a connection
+ * that already has a transaction uses a savepoint and does not commit the
+ * outer transaction (D124).
+ */
+export type DriverConnection = {
+    /** Runs one statement on this connection. */
+    execute(text: string, params?: readonly WireValue[], options?: ExecuteOptions): Promise<ExecuteResult>;
+    /** Atomic batch. Inside a transaction this is a savepoint and does not commit the outer one. */
+    batch(statements: readonly Statement[], options?: ExecuteOptions): Promise<readonly ExecuteResult[]>;
+    /** Returns the connection after `RESET ALL` and `pg_advisory_unlock_all()`. */
+    release(): Promise<void>;
+    /** Aborts the in-flight statement. Present when `cancel` is set. */
+    cancel?(): void;
+};
+/**
+ * One endpoint's pool.
+ *
+ * `reserve`, `stream`, `describe`, `listen`, and `cancel` are present only
+ * when the matching capability is set.
+ */
+export type DriverPool = {
+    /** Declared execution capabilities. */
+    readonly capabilities: DriverCapabilities;
+    /** Runs one statement on some connection. */
+    execute(text: string, params?: readonly WireValue[], options?: ExecuteOptions): Promise<ExecuteResult>;
+    /** Atomic batch. All statements commit, or none do. */
+    batch(statements: readonly Statement[], options?: ExecuteOptions): Promise<readonly ExecuteResult[]>;
+    /** Checks out one connection. Present when `transactions` is `"interactive"`. */
+    reserve?(): Promise<DriverConnection>;
+    /** Describes a statement without running it. Present when `describe` is set. */
+    describe?(text: string, params?: readonly WireValue[]): Promise<DescribeResult>;
+    /** Yields row chunks. Present when `stream` is set. */
+    stream?(text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;
+    /** Listens on a channel. Present when `listen` is set. The returned function stops listening. */
+    listen?(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
+    /** Aborts in-flight statements on this pool. Present when `cancel` is set. */
+    cancel?(): void;
+    /** Pool counters. */
+    stats(): DriverStats;
+    /** Closes every connection. */
+    close(): Promise<void>;
+};
+/**
+ * Pool options shared by adapters.
+ *
+ * One `open` is one endpoint. The runtime does not share a pool across
+ * endpoints.
+ */
+export type DriverPoolConfig = {
+    /** Connections in the pool. PGlite is always one. */
+    readonly max?: number;
+    /**
+     * Wait for a connection up to `acquire` milliseconds, then fail with
+     * OKM1846. Omitted means wait without that deadline.
+     */
+    readonly timeouts?: {
+        readonly acquire?: number;
+    };
+};