@facilis.dev/db 0.0.0-stage → 0.1.0

package/dist/tasks.d.ts

@@ -0,0 +1,312 @@
+/** Every facilis_tasks.status value, in lifecycle order. */
+export declare const FACILIS_TASK_STATUSES: readonly ["pending", "decided", "expired", "cancelled"];
+export type FacilisTaskStatus = (typeof FACILIS_TASK_STATUSES)[number];
+/** What the task asks for; approvals are the only kind the v1 slice ships. */
+export declare const FACILIS_TASK_KINDS: readonly ["approval"];
+export type FacilisTaskKind = (typeof FACILIS_TASK_KINDS)[number];
+/** How a decided task closes. */
+export declare const FACILIS_TASK_DECISIONS: readonly ["approve", "reject"];
+export type FacilisTaskDecision = (typeof FACILIS_TASK_DECISIONS)[number];
+/**
+ * One manual task. Statuses stay text (a new state is a code change, not a migration) and the
+ * workflow columns are nullable so a task can exist standalone before the workflow layer lands
+ * (D-135 W1).
+ */
+export declare const facilisTasks: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "facilis_tasks";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        workflowId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "workflow_id";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        stepIndex: import("drizzle-orm/pg-core").PgColumn<{
+            name: "step_index";
+            tableName: "facilis_tasks";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        kind: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kind";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        decision: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decision";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        titleKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "title_key";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        titleParams: import("drizzle-orm/pg-core").PgColumn<{
+            name: "title_params";
+            tableName: "facilis_tasks";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        payload: import("drizzle-orm/pg-core").PgColumn<{
+            name: "payload";
+            tableName: "facilis_tasks";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        requestedBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "requested_by";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        assignedPermission: import("drizzle-orm/pg-core").PgColumn<{
+            name: "assigned_permission";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "expires_at";
+            tableName: "facilis_tasks";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        decidedBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decided_by";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        decidedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decided_at";
+            tableName: "facilis_tasks";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        comment: import("drizzle-orm/pg-core").PgColumn<{
+            name: "comment";
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "facilis_tasks";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "facilis_tasks";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type FacilisTaskRow = typeof facilisTasks.$inferSelect;
+export type NewFacilisTaskRow = typeof facilisTasks.$inferInsert;

package/dist/tasks.js

@@ -0,0 +1,52 @@
+// The manual-task table (D-135, docs/WORKFLOWS.md §5).
+//
+// A task is framework state, not application data: tenant-scoped so the structural invariant
+// holds (pgPolicy + ENABLE ROW LEVEL SECURITY), re-exported by the project's db/schema.ts, and
+// DDL-owned by a Drizzle migration like the job queue (D-107).
+import { sql } from "drizzle-orm";
+import { index, integer, jsonb, pgPolicy, pgTable, text, timestamp, uuid, } from "drizzle-orm/pg-core";
+import { tenantIsolationPolicy } from "./rls.js";
+import { tenantColumn } from "./tenant-column.js";
+/** Every facilis_tasks.status value, in lifecycle order. */
+export const FACILIS_TASK_STATUSES = ["pending", "decided", "expired", "cancelled"];
+/** What the task asks for; approvals are the only kind the v1 slice ships. */
+export const FACILIS_TASK_KINDS = ["approval"];
+/** How a decided task closes. */
+export const FACILIS_TASK_DECISIONS = ["approve", "reject"];
+/**
+ * One manual task. Statuses stay text (a new state is a code change, not a migration) and the
+ * workflow columns are nullable so a task can exist standalone before the workflow layer lands
+ * (D-135 W1).
+ */
+export const facilisTasks = pgTable("facilis_tasks", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    workflowId: uuid("workflow_id"),
+    stepIndex: integer("step_index"),
+    kind: text("kind").notNull(),
+    status: text("status").notNull(),
+    decision: text("decision"),
+    titleKey: text("title_key").notNull(),
+    titleParams: jsonb("title_params").notNull().default({}),
+    payload: jsonb("payload"),
+    requestedBy: text("requested_by"),
+    assignedPermission: text("assigned_permission"),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    decidedBy: text("decided_by"),
+    decidedAt: timestamp("decided_at", { withTimezone: true }),
+    comment: text("comment"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    tenantId: tenantColumn(),
+}, (table) => [
+    tenantIsolationPolicy(),
+    // A RESTRICTIVE policy only narrows what a permissive policy already allows; with no
+    // permissive policy Postgres denies every row (D-008). The queue's reads/writes run as
+    // facilis_app, so the scoped tenant needs this gate — exactly like facilis_jobs.
+    pgPolicy("facilis_tasks_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+    index("facilis_tasks_status_created_idx").on(table.status, table.createdAt),
+    index("facilis_tasks_workflow_idx").on(table.workflowId),
+    index("facilis_tasks_assigned_idx").on(table.assignedPermission, table.status),
+]).enableRLS();

package/dist/tenant-column.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SQL expression that fills a tenant column from the policy-scope GUC.
+ *
+ * It reads the same `app.tenant_id` every RLS policy reads, transaction-locally set by
+ * `runWithPolicyScope` before the handler runs (contracts §4.2). The `nullif` guard is the
+ * same one the policies use: after a `RESET` a GUC reads as `''`, and `''::uuid` raises.
+ */
+export declare function tenantDefaultSql(): import("drizzle-orm").SQL<unknown>;
+/**
+ * A `tenant_id` column that takes its value from the policy scope (D-040).
+ *
+ * ```ts
+ * export const todos = pgTable("todos", { tenantId: tenantColumn(), ... }, ...).enableRLS();
+ * ```
+ *
+ * The default is the DB's, not the app's: an insert never names the tenant (raw SQL included),
+ * and it cannot name a different one — the RESTRICTIVE tenant policy still checks the written
+ * row against the same GUC. It also makes the column optional in Drizzle's insert type, so app
+ * code stops passing `tenantId: auth.tenantId` and the compiler stops asking for it.
+ */
+export declare function tenantColumn(name?: string): import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgUUIDBuilderInitial<string>>>;

package/dist/tenant-column.js

@@ -0,0 +1,27 @@
+import { sql } from "drizzle-orm";
+import { uuid } from "drizzle-orm/pg-core";
+/**
+ * SQL expression that fills a tenant column from the policy-scope GUC.
+ *
+ * It reads the same `app.tenant_id` every RLS policy reads, transaction-locally set by
+ * `runWithPolicyScope` before the handler runs (contracts §4.2). The `nullif` guard is the
+ * same one the policies use: after a `RESET` a GUC reads as `''`, and `''::uuid` raises.
+ */
+export function tenantDefaultSql() {
+    return sql `nullif(current_setting('app.tenant_id', true), '')::uuid`;
+}
+/**
+ * A `tenant_id` column that takes its value from the policy scope (D-040).
+ *
+ * ```ts
+ * export const todos = pgTable("todos", { tenantId: tenantColumn(), ... }, ...).enableRLS();
+ * ```
+ *
+ * The default is the DB's, not the app's: an insert never names the tenant (raw SQL included),
+ * and it cannot name a different one — the RESTRICTIVE tenant policy still checks the written
+ * row against the same GUC. It also makes the column optional in Drizzle's insert type, so app
+ * code stops passing `tenantId: auth.tenantId` and the compiler stops asking for it.
+ */
+export function tenantColumn(name = "tenant_id") {
+    return uuid(name).notNull().default(tenantDefaultSql());
+}

package/dist/views.d.ts

@@ -0,0 +1,92 @@
+import { type SQL } from "drizzle-orm";
+import { type ManualViewBuilder, type PgColumnBuilderBase } from "drizzle-orm/pg-core";
+import type { FacilisDb } from "./client.js";
+/** Brand carrier for a view object, so a declaration is recognisable from its export. */
+export declare const VIEW_BRAND: unique symbol;
+/** SQL view names are unquoted identifiers; generated code always satisfies this. */
+export declare const VIEW_NAME_PATTERN: RegExp;
+/** A view's own permission, when declared. Same identifier shape the config uses. */
+export declare const VIEW_PERMISSION_PATTERN: RegExp;
+export interface ViewMetadata {
+    readonly name: string;
+    readonly query: SQL;
+    /** Underlying tables, for manifest/graph metadata. Informational only. */
+    readonly tables: readonly string[];
+    /** The view's own permission; null keeps the D-097 invoker behaviour (D-098). */
+    readonly permission: string | null;
+    /** "definer" exactly when a permission is set, "invoker" otherwise. */
+    readonly access: "invoker" | "definer";
+}
+export interface DefineViewOptions<TName extends string = string, TColumns extends Record<string, PgColumnBuilderBase> = Record<string, PgColumnBuilderBase>> {
+    /** SQL view name: ^[a-z][a-z0-9_]{0,62}$ */
+    readonly name: TName;
+    /** Column builders; keys must equal the SQL column names. */
+    readonly columns: TColumns;
+    /** Literal, read-only SELECT/WITH/VALUES/TABLE. Values must not be interpolated. */
+    readonly query: SQL;
+    /** Underlying tables the query selects (metadata only). */
+    readonly tables?: readonly string[];
+    /**
+     * Optional view permission (D-098). With it the view becomes a definer view
+     * (security_invoker = false) and the declared permission alone decides access; the base
+     * tables' permissions are not consulted. Omit it for the D-097 invoker behaviour.
+     */
+    readonly permission?: string;
+}
+/** A Drizzle view usable in `db.select().from(...)`, branded with its declaration. */
+export type FacilisView<TName extends string, TColumns extends Record<string, PgColumnBuilderBase>> = ReturnType<ManualViewBuilder<TName, TColumns>["existing"]> & {
+    readonly [VIEW_BRAND]: ViewMetadata;
+};
+export type ViewErrorCode = "invalid_name" | "invalid_sql" | "invalid_permission";
+/** A declaration that cannot become a database view; the code reaches the dev endpoint. */
+export declare class ViewDefinitionError extends Error {
+    readonly code: ViewErrorCode;
+    constructor(code: ViewErrorCode, message: string);
+}
+/**
+ * Declare a SQL view. Never throws: an invalid declaration is reported when the framework
+ * tries to create it, so a typo in db/views cannot take the dev server down at import time.
+ */
+export declare function defineView<const TName extends string, const TColumns extends Record<string, PgColumnBuilderBase>>(options: DefineViewOptions<TName, TColumns>): FacilisView<TName, TColumns>;
+/** The declaration carried by a view object, when `value` is one. */
+export declare function viewMetadata(value: unknown): ViewMetadata | null;
+export declare function isFacilisView(value: unknown): boolean;
+/**
+ * Declarations in one or more module namespaces, deduplicated by name (first wins).
+ * A module namespace can export anything, so non-view exports are skipped.
+ */
+export declare function collectViewMetadata(modules: ReadonlyArray<Record<string, unknown>> | Record<string, unknown>): ViewMetadata[];
+/**
+ * CREATE OR REPLACE VIEW for a declaration. Rejects a non-identifier name and a query
+ * that is not a single static read-only statement: the SQL is inlined into the DDL, so
+ * this check is the boundary, not a style rule.
+ */
+export declare function viewCreateStatement(metadata: ViewMetadata): SQL;
+/**
+ * CREATE OR REPLACE VIEW for a raw SQL text (the query console's create-view flow).
+ *
+ * With a permission the view is a definer view whose only gate is that permission: the
+ * outer wrapper applies it to any query shape, and the permission name is validated before
+ * it is inlined (the DDL has no bind parameters, by construction).
+ */
+export declare function viewDefinitionStatement(name: string, query: SQL | string, permission?: string): SQL;
+/** Grants SELECT on a view to the policy-scoped app role. Idempotent. */
+export declare function grantViewSelect(db: FacilisDb, name: string): Promise<void>;
+export interface ViewApplyFailure {
+    readonly name: string;
+    readonly error: string;
+}
+export interface ViewApplyResult {
+    readonly created: readonly string[];
+    readonly failed: readonly ViewApplyFailure[];
+}
+export interface ViewApplyOptions {
+    /** Permissions declared in facilis.config.ts; a view naming another one fails as data. */
+    readonly permissions?: readonly string[];
+}
+/**
+ * Creates every declared view, then retries the failures once: a view may select from
+ * another view declared later in the same module. A failure is data, never a throw, so a
+ * broken view degrades to a manifest warning like every other boot step.
+ */
+export declare function applyViews(db: FacilisDb, modules: ReadonlyArray<Record<string, unknown>> | Record<string, unknown>, options?: ViewApplyOptions): Promise<ViewApplyResult>;