@arivie/db-postgres 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.0
+
+- Initial Postgres adapter (Sprint 0 / C04).

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2026 Arivie Contributors
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,5 @@
+# @arivie/db-postgres
+
+Postgres connection adapter for Arivie: role-scoped `execute` (optional `params?: readonly unknown[]` threaded to `sql.unsafe(query, params)` for `$1`/`$2` placeholders), schema `introspect`, owner-identity verification, and idempotent read-only role setup.
+
+Full contract: [RFC-002 §4.5](../../../.research/07-rfc/RFC-002-concrete-tech-implementation/02-requirements-interfaces.md#45-anaclipdb-postgres--postgres-adapter).

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { SourceAdapterExecuteOpts, SourceAdapterCompileMetricOpts, SourceAdapterCompileMetricResult } from '@arivie/core/types';
+export { ArivieBoundaryError } from '@arivie/core/types';
+import postgres from 'postgres';
+
+interface PostgresAdapterOptions {
+    url: string;
+    readOnlyRole?: string;
+    allowedSchemas?: string[];
+    maxConnections?: number;
+    idleTimeoutMs?: number;
+}
+interface PostgresAdapter {
+    readonly kind: "postgres";
+    readonly id: string;
+    /** Connection URL used to construct the underlying client (for Mastra PostgresStore). */
+    readonly url: string;
+    sql: postgres.Sql;
+    execute(opts: SourceAdapterExecuteOpts<string>): Promise<ExecuteResult>;
+    introspect(): Promise<TableMetadata[]>;
+    verifyOwnerIdentity(expectedOwnerId: string): Promise<void>;
+    setupRole(role: string, options?: {
+        allowedTables?: string[];
+    }): Promise<void>;
+    compileMetric?(opts: SourceAdapterCompileMetricOpts): SourceAdapterCompileMetricResult<string>;
+    close?(): Promise<void>;
+}
+interface ExecuteResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    durationMs: number;
+    truncated: boolean;
+}
+interface TableMetadata {
+    schema: string;
+    name: string;
+    columns: {
+        name: string;
+        type: string;
+        nullable: boolean;
+        comment?: string;
+        isPii?: boolean;
+    }[];
+    primary_key: string[];
+    foreign_keys: {
+        column: string;
+        references: {
+            table: string;
+            column: string;
+        };
+    }[];
+    row_count: number;
+}
+
+declare function postgresAdapter(opts: PostgresAdapterOptions): PostgresAdapter;
+
+/**
+ * Compiles a semantic-layer measure on a Postgres-bound entity to parameterised SQL.
+ */
+declare function compileMetricForPostgres(opts: SourceAdapterCompileMetricOpts): {
+    query: string;
+    params?: (string | number | boolean | null)[];
+};
+
+type ToolErrorKind = "sql-invalid" | "sql-blocked" | "sql-permission-denied" | "sql-timeout" | "metric-not-found" | "metric-ambiguous" | "dimension-not-found" | "segment-not-found" | "join-ambiguous" | "filter-invalid" | "cross-source-too-large" | "cross-source-output-too-large" | "cross-source-not-wired" | "source-not-found" | "source-no-compile" | "join-invalid";
+declare class ToolError extends Error {
+    readonly kind: ToolErrorKind;
+    readonly code: "ARIVIE_TOOL_ERROR";
+    constructor(kind: ToolErrorKind, message?: string);
+}
+
+/**
+ * Validate a SQL query for the agent's `execute` tool.
+ *
+ * Throws `ToolError` on rejection; returns void on accept.
+ *
+ * Rejection conditions (Sprint 1 KI-1-05):
+ *   - First keyword is not SELECT or WITH.
+ *   - Query contains `;` outside literals/comments (multi-statement).
+ *   - Query contains any DML/DDL/session-mutation keyword outside literals/comments.
+ *   - Query references `pg_catalog` / `information_schema` (system catalog block).
+ */
+declare function validateExecuteSql(sql: string): void;
+
+export { type ExecuteResult, type PostgresAdapter, type PostgresAdapterOptions, type TableMetadata, ToolError, type ToolErrorKind, compileMetricForPostgres, postgresAdapter, validateExecuteSql };

package/dist/index.js

@@ -0,0 +1,597 @@
+import { createHash } from 'crypto';
+import postgres from 'postgres';
+import { ArivieBoundaryError } from '@arivie/core/types';
+export { ArivieBoundaryError } from '@arivie/core/types';
+
+// src/adapter.ts
+var ToolError = class extends Error {
+  constructor(kind, message) {
+    super(message ?? kind);
+    this.kind = kind;
+    this.name = "ToolError";
+  }
+  kind;
+  code = "ARIVIE_TOOL_ERROR";
+};
+
+// src/compile-metric.ts
+var FILTER_COL_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+var ENTITY_COL_REF = /\b([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\b/g;
+function isFilterPrimitive(v) {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v === null;
+}
+function collectEntityRefs(text) {
+  const refs = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(ENTITY_COL_REF)) {
+    refs.add(match[1]);
+  }
+  return refs;
+}
+function detectJoinsNeeded(entity, dimensionSqls, filterKeys) {
+  const joinTargets = new Set((entity.joins ?? []).map((j) => j.to));
+  const refs = /* @__PURE__ */ new Set();
+  for (const sql of dimensionSqls) {
+    for (const ref of collectEntityRefs(sql)) {
+      if (joinTargets.has(ref) && ref !== entity.name) {
+        refs.add(ref);
+      }
+    }
+  }
+  for (const key of filterKeys) {
+    const dot = key.indexOf(".");
+    if (dot > 0) {
+      const refEntity = key.slice(0, dot);
+      if (joinTargets.has(refEntity) && refEntity !== entity.name) {
+        refs.add(refEntity);
+      }
+    }
+  }
+  return refs;
+}
+function buildJoinClauses(entity, joinsNeeded) {
+  const clauses = [];
+  for (const otherEntity of joinsNeeded) {
+    const matching = (entity.joins ?? []).filter((j) => j.to === otherEntity);
+    if (matching.length === 0) {
+      continue;
+    }
+    if (matching.length > 1) {
+      throw new ToolError(
+        "join-ambiguous",
+        `multiple join paths to '${otherEntity}'; specify entityHint to disambiguate`
+      );
+    }
+    const join = matching[0];
+    clauses.push(`LEFT JOIN ${join.to} ON ${join.on}`);
+  }
+  return clauses;
+}
+function compileMetricForPostgres(opts) {
+  const { entity, metric } = opts;
+  const measure = entity.measures?.find((m) => m.name === metric);
+  if (measure == null) {
+    throw new ToolError(
+      "metric-not-found",
+      `metric '${metric}' not found on entity '${entity.name}'`
+    );
+  }
+  const dimensionNames = opts.dimensions ?? [];
+  const selectExprs = [`(${measure.sql}) AS "${measure.name}"`];
+  const dimensionSqls = [];
+  for (const dimName of dimensionNames) {
+    const dim = entity.dimensions?.find((d) => d.name === dimName);
+    if (dim == null) {
+      throw new ToolError(
+        "dimension-not-found",
+        `dimension '${dimName}' not found on entity '${entity.name}'`
+      );
+    }
+    selectExprs.push(`(${dim.sql}) AS "${dim.name}"`);
+    dimensionSqls.push(dim.sql);
+  }
+  const filterKeys = Object.keys(opts.filters ?? {});
+  const joinsNeeded = detectJoinsNeeded(entity, dimensionSqls, filterKeys);
+  const joinClauses = buildJoinClauses(entity, joinsNeeded);
+  const whereClauses = [];
+  const params = [];
+  for (const segName of opts.segments ?? []) {
+    const seg = entity.segments?.find((s) => s.name === segName);
+    if (seg == null) {
+      throw new ToolError(
+        "segment-not-found",
+        `segment '${segName}' not found on entity '${entity.name}'`
+      );
+    }
+    whereClauses.push(`(${seg.sql})`);
+  }
+  for (const [col, value] of Object.entries(opts.filters ?? {})) {
+    if (!FILTER_COL_PATTERN.test(col)) {
+      throw new ToolError(
+        "filter-invalid",
+        `filter column '${col}' must be a plain identifier`
+      );
+    }
+    if (!isFilterPrimitive(value)) {
+      throw new ToolError(
+        "filter-invalid",
+        `filter value for '${col}' must be string|number|boolean|null`
+      );
+    }
+    if (value === null) {
+      whereClauses.push(`${col} IS NULL`);
+    } else {
+      whereClauses.push(`${col} = $${params.length + 1}`);
+      params.push(value);
+    }
+  }
+  const fromTable = typeof entity.source === "string" ? entity.source : entity.name;
+  const parts = [`SELECT ${selectExprs.join(", ")}`, `FROM ${fromTable}`];
+  if (joinClauses.length > 0) {
+    parts.push(...joinClauses);
+  }
+  if (whereClauses.length > 0) {
+    parts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  if (dimensionNames.length > 0) {
+    parts.push(
+      `GROUP BY ${dimensionNames.map((d) => `"${d}"`).join(", ")}`
+    );
+  }
+  const query = parts.join(" ");
+  return params.length > 0 ? { query, params } : { query };
+}
+
+// src/identifier.ts
+var IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function escapeIdent(name) {
+  if (!IDENT_RE.test(name)) {
+    throw new ToolError("sql-invalid", `invalid identifier: ${name}`);
+  }
+  return `"${name}"`;
+}
+
+// src/execute.ts
+function isPostgresError(err) {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+async function executeImpl(sql, opts) {
+  const startedAt = Date.now();
+  if (!Number.isFinite(opts.timeoutMs) || !Number.isInteger(opts.timeoutMs) || opts.timeoutMs <= 0) {
+    throw new ToolError(
+      "sql-invalid",
+      `timeoutMs must be a positive integer; got ${String(opts.timeoutMs)}`
+    );
+  }
+  if (!Number.isFinite(opts.rowLimit) || !Number.isInteger(opts.rowLimit) || opts.rowLimit <= 0) {
+    throw new ToolError(
+      "sql-invalid",
+      `rowLimit must be a positive integer; got ${String(opts.rowLimit)}`
+    );
+  }
+  if (opts.runAsRole == null || opts.runAsRole === "") {
+    throw new ToolError("sql-invalid", "runAsRole is required");
+  }
+  const runAsRole = opts.runAsRole;
+  try {
+    const rows = await sql.begin(async (tx) => {
+      await tx.unsafe(`SET LOCAL ROLE ${escapeIdent(runAsRole)}`);
+      await tx.unsafe(
+        `SET LOCAL statement_timeout = ${opts.timeoutMs}`
+      );
+      let queryParams;
+      if (opts.params != null) {
+        const copy = [...opts.params];
+        for (let i = 0; i < copy.length; i++) {
+          const v = copy[i];
+          if (v !== null && typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+            throw new ToolError(
+              "sql-invalid",
+              `params[${i}] must be string|number|boolean|null; got ${typeof v}`
+            );
+          }
+        }
+        queryParams = copy;
+      }
+      return await tx.unsafe(opts.query, queryParams);
+    });
+    const truncated = rows.length > opts.rowLimit;
+    const limited = rows.slice(0, opts.rowLimit);
+    return {
+      rows: limited,
+      rowCount: limited.length,
+      durationMs: Date.now() - startedAt,
+      truncated
+    };
+  } catch (err) {
+    if (isPostgresError(err)) {
+      if (err.code === "42501") {
+        throw new ToolError(
+          "sql-permission-denied",
+          "permission denied for SQL operation"
+        );
+      }
+      if (err.code === "57014") {
+        throw new ToolError("sql-timeout", "statement timeout");
+      }
+    }
+    throw err;
+  }
+}
+
+// src/introspect.ts
+var PII_RE = /email|phone|ssn|address|dob|password|secret|token|card/i;
+async function introspect(sql) {
+  const tables = await sql`
+    SELECT table_name
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+      AND table_type = 'BASE TABLE'
+    ORDER BY table_name
+  `;
+  const result = [];
+  for (const { table_name } of tables) {
+    const columns = await sql`
+      SELECT
+        c.column_name,
+        c.data_type,
+        c.is_nullable,
+        pgd.description AS comment
+      FROM information_schema.columns c
+      LEFT JOIN pg_catalog.pg_statio_all_tables st
+        ON st.schemaname = c.table_schema
+        AND st.relname = c.table_name
+      LEFT JOIN pg_catalog.pg_description pgd
+        ON pgd.objoid = st.relid
+        AND pgd.objsubid = c.ordinal_position
+      WHERE c.table_schema = 'public'
+        AND c.table_name = ${table_name}
+      ORDER BY c.ordinal_position
+    `;
+    const pkRows = await sql`
+      SELECT kcu.column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+        AND tc.table_name = kcu.table_name
+      WHERE tc.table_schema = 'public'
+        AND tc.table_name = ${table_name}
+        AND tc.constraint_type = 'PRIMARY KEY'
+      ORDER BY kcu.ordinal_position
+    `;
+    const fkRows = await sql`
+      SELECT
+        kcu.column_name,
+        ccu.table_name AS references_table,
+        ccu.column_name AS references_column
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+        AND tc.table_name = kcu.table_name
+      JOIN information_schema.constraint_column_usage ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.table_schema = 'public'
+        AND tc.table_name = ${table_name}
+        AND tc.constraint_type = 'FOREIGN KEY'
+      ORDER BY kcu.ordinal_position
+    `;
+    const countRows = await sql`
+      SELECT reltuples::bigint AS row_count
+      FROM pg_class
+      WHERE relname = ${table_name}
+    `;
+    const rowCountRaw = countRows[0]?.row_count;
+    const row_count = rowCountRaw === null || rowCountRaw === void 0 ? 0 : Number(rowCountRaw);
+    result.push({
+      schema: "public",
+      name: table_name,
+      columns: columns.map((col) => {
+        const column = {
+          name: col.column_name,
+          type: col.data_type,
+          nullable: col.is_nullable === "YES"
+        };
+        if (col.comment) {
+          column.comment = col.comment;
+        }
+        if (PII_RE.test(col.column_name)) {
+          column.isPii = true;
+        }
+        return column;
+      }),
+      primary_key: pkRows.map((r) => r.column_name),
+      foreign_keys: fkRows.map((r) => ({
+        column: r.column_name,
+        references: {
+          table: r.references_table,
+          column: r.references_column
+        }
+      })),
+      row_count
+    });
+  }
+  return result;
+}
+
+// src/setup-role.ts
+var SETUP_ROLE_LOCK_KEY = 982374623;
+function isDuplicateRoleError(err) {
+  return err != null && typeof err === "object" && "code" in err && err.code === "42710";
+}
+async function setupRole(sql, role, options) {
+  const roleIdent = escapeIdent(role);
+  await sql.unsafe(`SELECT pg_advisory_lock(${SETUP_ROLE_LOCK_KEY})`);
+  try {
+    try {
+      await sql.unsafe(`CREATE ROLE ${roleIdent} LOGIN`);
+    } catch (err) {
+      if (!isDuplicateRoleError(err)) {
+        throw err;
+      }
+    }
+    await sql.unsafe(`
+      CREATE TABLE IF NOT EXISTS arivie_owner_identity (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+    await sql.unsafe(`GRANT USAGE ON SCHEMA public TO ${roleIdent}`);
+    const allowedTables = options?.allowedTables;
+    if (allowedTables && allowedTables.length > 0) {
+      for (const table of allowedTables) {
+        await sql.unsafe(
+          `GRANT SELECT ON TABLE public.${escapeIdent(table)} TO ${roleIdent}`
+        );
+      }
+    } else {
+      await sql.unsafe(
+        `GRANT SELECT ON ALL TABLES IN SCHEMA public TO ${roleIdent}`
+      );
+    }
+    await sql.unsafe(
+      `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ${roleIdent}`
+    );
+  } finally {
+    await sql.unsafe(`SELECT pg_advisory_unlock(${SETUP_ROLE_LOCK_KEY})`);
+  }
+}
+
+// src/verify.ts
+async function verifyOwnerIdentity(sql, expectedOwnerId) {
+  const rows = await sql`
+    SELECT value FROM arivie_owner_identity WHERE key = 'owner_id'
+  `;
+  if (rows.length === 0) {
+    throw new ArivieBoundaryError(
+      {
+        reason: "identity-table-missing",
+        expected: expectedOwnerId
+      },
+      "arivie_owner_identity table missing or empty; run 'arivie setup' first"
+    );
+  }
+  const dbValue = rows[0]?.value;
+  if (dbValue !== expectedOwnerId) {
+    throw new ArivieBoundaryError(
+      {
+        reason: "identity-mismatch",
+        dbValue,
+        expected: expectedOwnerId
+      },
+      `owner identity mismatch: database has '${String(dbValue)}', expected '${expectedOwnerId}'`
+    );
+  }
+}
+
+// src/adapter.ts
+function derivePostgresAdapterId(url) {
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname || "localhost";
+    const db = parsed.pathname.replace(/^\//, "") || "postgres";
+    return `postgres:${host}/${db}`;
+  } catch {
+    const hash = createHash("sha256").update(url).digest("hex").slice(0, 12);
+    return `postgres:${hash}`;
+  }
+}
+function postgresAdapter(opts) {
+  const sql = postgres(opts.url, {
+    max: opts.maxConnections ?? 10,
+    idle_timeout: (opts.idleTimeoutMs ?? 3e4) / 1e3,
+    onnotice: () => {
+    }
+  });
+  return {
+    kind: "postgres",
+    id: derivePostgresAdapterId(opts.url),
+    url: opts.url,
+    sql,
+    execute: (executeOpts) => executeImpl(sql, executeOpts),
+    introspect: () => introspect(sql),
+    verifyOwnerIdentity: (expectedOwnerId) => verifyOwnerIdentity(sql, expectedOwnerId),
+    setupRole: (role, options) => setupRole(sql, role, options),
+    compileMetric: compileMetricForPostgres,
+    close: async () => {
+      await sql.end();
+    }
+  };
+}
+
+// src/sql-guard.ts
+var FORBIDDEN_KEYWORDS = [
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "MERGE",
+  "TRUNCATE",
+  "DROP",
+  "CREATE",
+  "ALTER",
+  "GRANT",
+  "REVOKE",
+  "REINDEX",
+  "VACUUM",
+  "CLUSTER",
+  "COPY",
+  "CALL",
+  "DO",
+  "LOCK",
+  "COMMENT",
+  "REFRESH",
+  "REASSIGN",
+  "EXECUTE",
+  "PREPARE",
+  "DEALLOCATE",
+  "DISCARD",
+  "LISTEN",
+  "NOTIFY",
+  "UNLISTEN",
+  "SET",
+  "RESET"
+];
+var SYSTEM_CATALOG_PATTERN = /\b(pg_catalog|information_schema)\b/i;
+var FORBIDDEN_PATTERN = new RegExp(
+  `\\b(${FORBIDDEN_KEYWORDS.join("|")})\\b`,
+  "i"
+);
+function stripLiteralsAndComments(sql) {
+  const out = [];
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const c = sql[i];
+    if (c === void 0) {
+      break;
+    }
+    const next = i + 1 < n ? sql[i + 1] : "";
+    if (c === "-" && next === "-") {
+      while (i < n && sql[i] !== "\n") {
+        out.push(" ");
+        i += 1;
+      }
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      out.push("  ");
+      i += 2;
+      while (i < n) {
+        if (sql[i] === "*" && i + 1 < n && sql[i + 1] === "/") {
+          out.push("  ");
+          i += 2;
+          break;
+        }
+        out.push(" ");
+        i += 1;
+      }
+      continue;
+    }
+    if (c === "'") {
+      out.push("'");
+      i += 1;
+      while (i < n) {
+        if (sql[i] === "'") {
+          if (i + 1 < n && sql[i + 1] === "'") {
+            out.push("  ");
+            i += 2;
+            continue;
+          }
+          out.push("'");
+          i += 1;
+          break;
+        }
+        out.push(" ");
+        i += 1;
+      }
+      continue;
+    }
+    if (c === '"') {
+      out.push('"');
+      i += 1;
+      while (i < n) {
+        if (sql[i] === '"') {
+          if (i + 1 < n && sql[i + 1] === '"') {
+            out.push("  ");
+            i += 2;
+            continue;
+          }
+          out.push('"');
+          i += 1;
+          break;
+        }
+        out.push(" ");
+        i += 1;
+      }
+      continue;
+    }
+    if (c === "$") {
+      const tagMatch = /^\$([A-Za-z_][A-Za-z_0-9]*)?\$/.exec(sql.slice(i));
+      if (tagMatch != null) {
+        const tag = tagMatch[0];
+        out.push(" ".repeat(tag.length));
+        i += tag.length;
+        const end = sql.indexOf(tag, i);
+        if (end === -1) {
+          while (i < n) {
+            out.push(" ");
+            i += 1;
+          }
+          continue;
+        }
+        while (i < end) {
+          out.push(" ");
+          i += 1;
+        }
+        out.push(" ".repeat(tag.length));
+        i += tag.length;
+        continue;
+      }
+    }
+    out.push(c);
+    i += 1;
+  }
+  return out.join("");
+}
+function firstKeyword(sql) {
+  const stripped = stripLiteralsAndComments(sql);
+  const m = /\s*\(*\s*([A-Za-z_][A-Za-z_0-9]*)/.exec(stripped);
+  return m?.[1] ? m[1].toUpperCase() : null;
+}
+function validateExecuteSql(sql) {
+  const trimmed = sql.trim();
+  if (trimmed.length === 0) {
+    throw new ToolError("sql-invalid", "empty query");
+  }
+  const stripped = stripLiteralsAndComments(trimmed);
+  if (stripped.includes(";")) {
+    const lastSemi = stripped.lastIndexOf(";");
+    const tail = stripped.slice(lastSemi + 1).trim();
+    if (tail.length > 0) {
+      throw new ToolError(
+        "sql-invalid",
+        "multi-statement queries are not allowed"
+      );
+    }
+  }
+  const head = firstKeyword(trimmed);
+  if (head !== "SELECT" && head !== "WITH") {
+    throw new ToolError(
+      "sql-invalid",
+      "only SELECT and WITH statements are allowed"
+    );
+  }
+  if (SYSTEM_CATALOG_PATTERN.test(stripped)) {
+    throw new ToolError("sql-blocked", "system catalog access is blocked");
+  }
+  const forbidden = FORBIDDEN_PATTERN.exec(stripped);
+  if (forbidden != null) {
+    throw new ToolError(
+      "sql-blocked",
+      `forbidden keyword '${forbidden[1]?.toUpperCase()}' in query`
+    );
+  }
+}
+
+export { ToolError, compileMetricForPostgres, postgresAdapter, validateExecuteSql };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@arivie/db-postgres",
+  "version": "0.1.0",
+  "description": "Arivie Postgres adapter — role-scoped execute, introspect, owner-identity verification.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@arivie/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "postgres": "^3.4.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@testcontainers/postgresql": "^11.0.0",
+    "postgres": "^3.4.9",
+    "testcontainers": "^11.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.0",
+    "@arivie/semantic": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo no-lint-yet"
+  }
+}