@cybernetyx1/atlasflow-postgres 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @cybernetyx1/atlasflow-postgres
+
+PostgreSQL persistence adapter for AtlasFlow sessions, runs, and durable streams — durable state that survives restarts.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-postgres
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+`postgres(connectionString, options)` connects via the `postgres` driver and returns a persistence adapter. Call `migrate()` once on startup to create the schema, then pass the adapter into the runtime.
+
+```ts
+import { postgres } from "@cybernetyx1/atlasflow-postgres";
+
+const persistence = postgres(process.env.POSTGRES_URL!);
+await persistence.migrate(); // idempotent — creates tables if missing
+
+// pass `persistence` into the generated server / runtime as the durable store
+```
+
+To use a different client (for example PGlite in tests), build the adapter directly:
+
+```ts
+import { postgresAdapter } from "@cybernetyx1/atlasflow-postgres";
+
+const persistence = postgresAdapter(mySqlClient);
+await persistence.migrate();
+```
+
+Exports: `postgres`, `postgresAdapter`, and the `SqlClient` / `PostgresPersistence` types. The returned adapter also exposes `migrate()` and `close()`.
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { PersistenceAdapter, PersistenceAdapterOptions } from '@cybernetyx1/atlasflow-runtime';
+
+/**
+ * @cybernetyx1/atlasflow-postgres — durable PersistenceAdapter backed by PostgreSQL.
+ *
+ *   import { postgres } from "@cybernetyx1/atlasflow-postgres";
+ *   const persistence = postgres(process.env.DATABASE_URL);
+ *   await persistence.migrate();
+ *
+ * Written against a minimal SqlClient ($1-style placeholders), so the same
+ * adapter runs on the `postgres` driver in production and on PGlite in tests.
+ * JSON payloads are stored as text and (de)serialized here for portability.
+ */
+
+interface SqlClient {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    end?(): Promise<void>;
+}
+type PostgresPersistence = PersistenceAdapter & {
+    /** Create tables if they don't exist. Call once at startup. */
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+};
+/** Build a PersistenceAdapter from any SqlClient (e.g. PGlite in tests). */
+declare function postgresAdapter(client: SqlClient, options?: PersistenceAdapterOptions): PostgresPersistence;
+/** Connect to PostgreSQL via the `postgres` driver and build the adapter. */
+declare function postgres(connectionString: string, options?: PersistenceAdapterOptions): PostgresPersistence;
+
+export { type PostgresPersistence, type SqlClient, postgres, postgresAdapter };

package/dist/index.js

@@ -0,0 +1,630 @@
+// src/index.ts
+import postgresDriver from "postgres";
+import { DurableStreamSubscriptionStoreBase } from "@cybernetyx1/atlasflow-runtime";
+var PgSessionStore = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  async get(key) {
+    const { rows } = await this.sql.query("SELECT data FROM atlasflow_sessions WHERE key = $1", [key]);
+    const row = rows[0];
+    return row ? JSON.parse(row.data) : null;
+  }
+  async put(key, data) {
+    await this.sql.query(
+      "INSERT INTO atlasflow_sessions (key, data, updated_at) VALUES ($1, $2, $3) ON CONFLICT (key) DO UPDATE SET data = EXCLUDED.data, updated_at = EXCLUDED.updated_at",
+      [key, JSON.stringify(data), data.updatedAt]
+    );
+  }
+  async delete(key) {
+    await this.sql.query("DELETE FROM atlasflow_sessions WHERE key = $1", [key]);
+  }
+};
+var PgRunStore = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  async create(record) {
+    await this.sql.query(
+      `INSERT INTO atlasflow_runs (
+         run_id, agent, instance_id, status, result, error, started_at, ended_at,
+         message, payload, images, kind, state, lease_owner, lease_acquired_at, lease_expires_at
+       )
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16)`,
+      [
+        record.runId,
+        record.agent,
+        record.instanceId,
+        record.status,
+        json(record.result),
+        json(record.error),
+        timestampOrNow(record.startedAt),
+        nullableTimestamp(record.endedAt),
+        record.message ?? null,
+        json(record.payload),
+        json(record.images),
+        record.kind ?? null,
+        json(record.state),
+        record.leaseOwner ?? null,
+        nullableTimestamp(record.leaseAcquiredAt),
+        nullableTimestamp(record.leaseExpiresAt)
+      ]
+    );
+  }
+  async update(runId, patch) {
+    const columns = {};
+    if (patch.status !== void 0) columns.status = patch.status;
+    if (patch.result !== void 0) columns.result = json(patch.result);
+    if (patch.error !== void 0) columns.error = json(patch.error);
+    if (patch.endedAt !== void 0) columns.ended_at = patch.endedAt;
+    if (patch.message !== void 0) columns.message = patch.message;
+    if (patch.payload !== void 0) columns.payload = json(patch.payload);
+    if (patch.images !== void 0) columns.images = json(patch.images);
+    if (patch.kind !== void 0) columns.kind = patch.kind;
+    if (patch.state !== void 0) columns.state = json(patch.state);
+    if (patch.leaseOwner !== void 0) columns.lease_owner = patch.leaseOwner;
+    if (patch.leaseAcquiredAt !== void 0) columns.lease_acquired_at = patch.leaseAcquiredAt;
+    if (patch.leaseExpiresAt !== void 0) columns.lease_expires_at = patch.leaseExpiresAt;
+    const keys = Object.keys(columns);
+    if (keys.length === 0) return;
+    const sets = keys.map((k, i) => `${k}=$${i + 2}`).join(", ");
+    await this.sql.query(`UPDATE atlasflow_runs SET ${sets} WHERE run_id=$1`, [runId, ...keys.map((k) => columns[k])]);
+  }
+  async get(runId) {
+    const { rows } = await this.sql.query("SELECT * FROM atlasflow_runs WHERE run_id = $1", [runId]);
+    return rows[0] ? rowToRun(rows[0]) : null;
+  }
+  async list(filter) {
+    const conds = [];
+    const params = [];
+    if (filter?.status) {
+      params.push(filter.status);
+      conds.push(`status = $${params.length}`);
+    }
+    if (filter?.agent) {
+      params.push(filter.agent);
+      conds.push(`agent = $${params.length}`);
+    }
+    const where = conds.length ? `WHERE ${conds.join(" AND ")}` : "";
+    const limit = filter?.limit ? `LIMIT ${Math.floor(filter.limit)}` : "";
+    const { rows } = await this.sql.query(`SELECT * FROM atlasflow_runs ${where} ORDER BY started_at DESC ${limit}`, params);
+    return rows.map(rowToRun);
+  }
+  async claimLease(runId, owner, now, ttlMs) {
+    const { rows } = await this.sql.query(
+      `UPDATE atlasflow_runs
+       SET lease_owner = $2, lease_acquired_at = $3, lease_expires_at = $4
+       WHERE run_id = $1
+         AND status = 'running'
+         AND (
+           lease_owner IS NULL
+           OR lease_owner = $2
+           OR lease_expires_at IS NULL
+           OR lease_expires_at <= $3
+         )
+       RETURNING run_id`,
+      [runId, owner, now, now + ttlMs]
+    );
+    return rows.length > 0;
+  }
+  async claimQueued(runId, owner, now, ttlMs) {
+    const { rows } = await this.sql.query(
+      `UPDATE atlasflow_runs
+       SET status = 'running', lease_owner = $2, lease_acquired_at = $3, lease_expires_at = $4
+       WHERE run_id = $1 AND status = 'queued'
+       RETURNING run_id`,
+      [runId, owner, now, now + ttlMs]
+    );
+    return rows.length > 0;
+  }
+  async heartbeatLease(runId, owner, now, ttlMs) {
+    const { rows } = await this.sql.query(
+      `UPDATE atlasflow_runs
+       SET lease_expires_at = $3
+       WHERE run_id = $1 AND status = 'running' AND lease_owner = $2
+       RETURNING run_id`,
+      [runId, owner, now + ttlMs]
+    );
+    return rows.length > 0;
+  }
+  async releaseLease(runId, owner) {
+    await this.sql.query(
+      `UPDATE atlasflow_runs
+       SET lease_owner = NULL, lease_acquired_at = NULL, lease_expires_at = NULL
+       WHERE run_id = $1 AND lease_owner = $2`,
+      [runId, owner]
+    );
+  }
+  async appendEvent(runId, event) {
+    await this.sql.query(
+      "INSERT INTO atlasflow_run_events (run_id, idx, event) VALUES ($1, $2, $3) ON CONFLICT (run_id, idx) DO NOTHING",
+      [runId, event.index, JSON.stringify(event)]
+    );
+  }
+  async events(runId) {
+    const { rows } = await this.sql.query("SELECT event FROM atlasflow_run_events WHERE run_id = $1 ORDER BY idx ASC", [runId]);
+    return rows.map((r) => JSON.parse(r.event));
+  }
+  async eventCount(runId) {
+    const { rows } = await this.sql.query("SELECT COUNT(*) AS n FROM atlasflow_run_events WHERE run_id = $1", [runId]);
+    return Number(rows[0]?.n ?? 0);
+  }
+};
+var PgStreamStore = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  async create(path, opts = {}) {
+    const existing = await this.get(path);
+    if (existing) {
+      const contentType2 = opts.contentType === void 0 ? existing.contentType : normalizeStreamContentType(opts.contentType);
+      if (normalizeStreamContentType(existing.contentType) !== contentType2 || opts.ttlSeconds !== existing.ttlSeconds || opts.expiresAt !== existing.expiresAt || (opts.initialData?.length ?? 0) > 0) {
+        throw new Error("stream already exists with different configuration");
+      }
+      return { record: existing, created: false };
+    }
+    let contentType = normalizeStreamContentType(opts.contentType);
+    let currentOffset = "-1";
+    let inheritedMessages = [];
+    if (opts.fork) {
+      const source = await this.get(opts.fork.path);
+      if (!source) throw new Error("fork source not found");
+      contentType = resolveForkContentType(source, opts.contentType);
+      currentOffset = resolveForkOffset(source, opts.fork.offset);
+      const forkIndex = parseStreamMessageIndex(currentOffset);
+      inheritedMessages = (await this.messages(opts.fork.path)).filter((message) => message.index <= forkIndex);
+    }
+    const now = Date.now();
+    let record = {
+      path,
+      contentType,
+      closed: opts.closed === true,
+      currentOffset,
+      createdAt: now,
+      updatedAt: now,
+      ...opts.ttlSeconds !== void 0 ? { ttlSeconds: opts.ttlSeconds } : {},
+      ...opts.expiresAt !== void 0 ? { expiresAt: opts.expiresAt } : {}
+    };
+    await this.sql.query(
+      `INSERT INTO atlasflow_streams
+       (path, content_type, closed, current_offset, last_seq, created_at, updated_at, ttl_seconds, expires_at, producers, closed_by)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)`,
+      [
+        record.path,
+        record.contentType,
+        record.closed,
+        record.currentOffset,
+        record.lastSeq ?? null,
+        record.createdAt,
+        record.updatedAt,
+        record.ttlSeconds ?? null,
+        record.expiresAt ?? null,
+        json(record.producers),
+        json(record.closedBy)
+      ]
+    );
+    for (const message of inheritedMessages) {
+      await this.sql.query("INSERT INTO atlasflow_stream_messages (path, idx, stream_offset, data_base64, created_at) VALUES ($1,$2,$3,$4,$5)", [
+        path,
+        message.index,
+        message.offset,
+        message.dataBase64,
+        message.createdAt
+      ]);
+    }
+    if ((opts.initialData?.length ?? 0) > 0) {
+      const normalized = normalizeStreamBody(opts.initialData, contentType, true);
+      if (normalized.length > 0) {
+        const message = makeStreamMessage(parseStreamMessageIndex(record.currentOffset) + 1, normalized);
+        record = { ...record, currentOffset: message.offset, updatedAt: message.createdAt };
+        await this.sql.query("INSERT INTO atlasflow_stream_messages (path, idx, stream_offset, data_base64, created_at) VALUES ($1,$2,$3,$4,$5)", [
+          path,
+          message.index,
+          message.offset,
+          message.dataBase64,
+          message.createdAt
+        ]);
+        await this.sql.query("UPDATE atlasflow_streams SET current_offset=$2, updated_at=$3 WHERE path=$1", [path, record.currentOffset, record.updatedAt]);
+      }
+    }
+    return { record, created: true };
+  }
+  async get(path) {
+    const { rows } = await this.sql.query("SELECT * FROM atlasflow_streams WHERE path = $1", [path]);
+    return rows[0] ? rowToStream(rows[0]) : null;
+  }
+  async delete(path) {
+    const existing = await this.get(path);
+    if (!existing) return false;
+    await this.sql.query("DELETE FROM atlasflow_stream_messages WHERE path = $1", [path]);
+    await this.sql.query("DELETE FROM atlasflow_streams WHERE path = $1", [path]);
+    return true;
+  }
+  async append(path, data, opts) {
+    const existing = await this.get(path);
+    if (!existing) return null;
+    assertStreamContentType(existing.contentType, opts.contentType);
+    if (existing.closed) throw new Error("stream is closed");
+    assertStreamSeq(existing, opts.seq);
+    const normalized = normalizeStreamBody(data, existing.contentType, false);
+    const message = makeStreamMessage(parseStreamMessageIndex(existing.currentOffset) + 1, normalized);
+    const record = {
+      ...existing,
+      currentOffset: message.offset,
+      ...opts.seq !== void 0 ? { lastSeq: opts.seq } : {},
+      closed: opts.close === true,
+      updatedAt: message.createdAt
+    };
+    await this.sql.query("INSERT INTO atlasflow_stream_messages (path, idx, stream_offset, data_base64, created_at) VALUES ($1,$2,$3,$4,$5)", [
+      path,
+      message.index,
+      message.offset,
+      message.dataBase64,
+      message.createdAt
+    ]);
+    await this.sql.query("UPDATE atlasflow_streams SET current_offset=$2, closed=$3, last_seq=$4, updated_at=$5 WHERE path=$1", [
+      path,
+      record.currentOffset,
+      record.closed,
+      record.lastSeq ?? null,
+      record.updatedAt
+    ]);
+    return { record, message };
+  }
+  async appendWithProducer(path, data, opts) {
+    const existing = await this.get(path);
+    if (!existing) return null;
+    if (existing.closed) return closedStreamProducerAppend(existing, opts.producer);
+    assertStreamContentType(existing.contentType, opts.contentType);
+    const producerResult = validateStreamProducer(existing, opts.producer);
+    if (producerResult.status !== "accepted") return { record: existing, message: null, producerResult };
+    assertStreamSeq(existing, opts.seq);
+    const normalized = normalizeStreamBody(data, existing.contentType, false);
+    const message = makeStreamMessage(parseStreamMessageIndex(existing.currentOffset) + 1, normalized);
+    const record = {
+      ...existing,
+      currentOffset: message.offset,
+      ...opts.seq !== void 0 ? { lastSeq: opts.seq } : {},
+      closed: opts.close === true,
+      updatedAt: message.createdAt
+    };
+    commitStreamProducer(record, producerResult);
+    if (opts.close) record.closedBy = { ...opts.producer };
+    await this.sql.query("INSERT INTO atlasflow_stream_messages (path, idx, stream_offset, data_base64, created_at) VALUES ($1,$2,$3,$4,$5)", [
+      path,
+      message.index,
+      message.offset,
+      message.dataBase64,
+      message.createdAt
+    ]);
+    await this.sql.query(
+      "UPDATE atlasflow_streams SET current_offset=$2, closed=$3, last_seq=$4, updated_at=$5, producers=$6, closed_by=$7 WHERE path=$1",
+      [path, record.currentOffset, record.closed, record.lastSeq ?? null, record.updatedAt, json(record.producers), json(record.closedBy)]
+    );
+    return { record, message, producerResult, streamClosed: opts.close === true };
+  }
+  async close(path) {
+    const existing = await this.get(path);
+    if (!existing) return null;
+    const record = { ...existing, closed: true, updatedAt: Date.now() };
+    await this.sql.query("UPDATE atlasflow_streams SET closed=true, updated_at=$2 WHERE path=$1", [path, record.updatedAt]);
+    return record;
+  }
+  async closeWithProducer(path, producer) {
+    const existing = await this.get(path);
+    if (!existing) return null;
+    if (existing.closed) {
+      if (producerMatchesClosedBy(existing, producer)) {
+        return { record: existing, alreadyClosed: true, producerResult: { status: "duplicate", lastSeq: producer.seq } };
+      }
+      return { record: existing, alreadyClosed: true, producerResult: { status: "stream_closed" } };
+    }
+    const producerResult = validateStreamProducer(existing, producer);
+    if (producerResult.status !== "accepted") return { record: existing, alreadyClosed: false, producerResult };
+    const record = { ...existing, closed: true, closedBy: { ...producer }, updatedAt: Date.now() };
+    commitStreamProducer(record, producerResult);
+    await this.sql.query(
+      "UPDATE atlasflow_streams SET closed=true, updated_at=$2, producers=$3, closed_by=$4 WHERE path=$1",
+      [path, record.updatedAt, json(record.producers), json(record.closedBy)]
+    );
+    return { record, alreadyClosed: false, producerResult };
+  }
+  async messages(path) {
+    const { rows } = await this.sql.query("SELECT * FROM atlasflow_stream_messages WHERE path = $1 ORDER BY idx ASC", [path]);
+    return rows.map(rowToStreamMessage);
+  }
+  async list() {
+    const { rows } = await this.sql.query("SELECT path FROM atlasflow_streams ORDER BY path ASC");
+    return rows.map((row) => row.path);
+  }
+};
+var PgSubscriptionStore = class extends DurableStreamSubscriptionStoreBase {
+  constructor(sql, streams, webhookOptions) {
+    super(streams, void 0, webhookOptions);
+    this.sql = sql;
+  }
+  sql;
+  async load(id) {
+    const { rows } = await this.sql.query("SELECT data FROM atlasflow_stream_subscriptions WHERE id = $1", [id]);
+    return rows[0] ? JSON.parse(rows[0].data) : null;
+  }
+  async save(record) {
+    await this.sql.query(
+      `INSERT INTO atlasflow_stream_subscriptions (id, data, updated_at)
+       VALUES ($1, $2, $3)
+       ON CONFLICT (id) DO UPDATE SET data = EXCLUDED.data, updated_at = EXCLUDED.updated_at`,
+      [record.id, JSON.stringify(record), Date.now()]
+    );
+  }
+  async remove(id) {
+    const existing = await this.load(id);
+    if (!existing) return false;
+    await this.sql.query("DELETE FROM atlasflow_stream_subscriptions WHERE id = $1", [id]);
+    return true;
+  }
+  async listRecords() {
+    const { rows } = await this.sql.query("SELECT data FROM atlasflow_stream_subscriptions ORDER BY id ASC");
+    return rows.map((row) => JSON.parse(row.data));
+  }
+};
+function json(value) {
+  return value === void 0 || value === null ? null : JSON.stringify(value);
+}
+function timestampOrNow(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : Date.now();
+}
+function nullableTimestamp(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function rowToRun(row) {
+  return {
+    runId: row.run_id,
+    agent: row.agent,
+    instanceId: row.instance_id,
+    status: row.status,
+    result: parse(row.result),
+    error: parse(row.error),
+    startedAt: Number(row.started_at),
+    endedAt: row.ended_at == null ? void 0 : Number(row.ended_at),
+    message: row.message ?? void 0,
+    payload: parse(row.payload),
+    images: parse(row.images),
+    kind: row.kind ?? void 0,
+    state: parse(row.state),
+    leaseOwner: row.lease_owner ?? void 0,
+    leaseAcquiredAt: row.lease_acquired_at == null ? void 0 : Number(row.lease_acquired_at),
+    leaseExpiresAt: row.lease_expires_at == null ? void 0 : Number(row.lease_expires_at)
+  };
+}
+function parse(value) {
+  return value == null ? void 0 : JSON.parse(value);
+}
+function rowToStream(row) {
+  return {
+    path: row.path,
+    contentType: row.content_type,
+    closed: Boolean(row.closed),
+    currentOffset: row.current_offset,
+    lastSeq: row.last_seq ?? void 0,
+    createdAt: Number(row.created_at),
+    updatedAt: Number(row.updated_at),
+    ttlSeconds: row.ttl_seconds == null ? void 0 : Number(row.ttl_seconds),
+    expiresAt: row.expires_at ?? void 0,
+    producers: parse(row.producers),
+    closedBy: parse(row.closed_by)
+  };
+}
+function rowToStreamMessage(row) {
+  return {
+    index: Number(row.idx),
+    offset: row.stream_offset,
+    dataBase64: row.data_base64,
+    createdAt: Number(row.created_at)
+  };
+}
+function normalizeStreamContentType(value) {
+  const normalized = value?.split(";")[0]?.trim().toLowerCase();
+  return normalized && /^[\w.+-]+\/[\w.+-]+$/.test(normalized) ? normalized : "application/octet-stream";
+}
+function isJsonStreamContentType(contentType) {
+  return normalizeStreamContentType(contentType) === "application/json";
+}
+function normalizeStreamBody(data, contentType, initialCreate) {
+  if (!isJsonStreamContentType(contentType)) return data;
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(data));
+  } catch {
+    throw new Error("Invalid JSON");
+  }
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 0) {
+      if (initialCreate) return new Uint8Array(0);
+      throw new Error("Empty arrays are not allowed");
+    }
+    return new TextEncoder().encode(JSON.stringify(parsed));
+  }
+  return new TextEncoder().encode(JSON.stringify([parsed]));
+}
+function assertStreamContentType(expected, actual) {
+  if (normalizeStreamContentType(expected) !== normalizeStreamContentType(actual)) throw new Error("Content-type mismatch");
+}
+function assertStreamSeq(record, seq) {
+  if (seq === void 0) return;
+  if (seq.length === 0) throw new Error("Invalid Stream-Seq");
+  if (record.lastSeq !== void 0 && seq <= record.lastSeq) throw new Error("Stream sequence conflict");
+}
+function resolveForkContentType(source, requested) {
+  const sourceContentType = normalizeStreamContentType(source.contentType);
+  if (requested === void 0) return sourceContentType;
+  const requestedContentType = normalizeStreamContentType(requested);
+  if (requestedContentType !== sourceContentType) throw new Error("Content-type mismatch");
+  return requestedContentType;
+}
+function resolveForkOffset(source, requested) {
+  const offset = requested ?? source.currentOffset;
+  const index = parseStreamMessageIndex(offset);
+  const tail = parseStreamMessageIndex(source.currentOffset);
+  if (index > tail) throw new Error("Fork offset is beyond source tail");
+  return offset;
+}
+var PRODUCER_STATE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+function validateStreamProducer(record, producer) {
+  cleanupExpiredProducers(record);
+  const state = record.producers?.[producer.producerId];
+  const now = Date.now();
+  if (!state) {
+    if (producer.seq !== 0) return { status: "sequence_gap", expectedSeq: 0, receivedSeq: producer.seq };
+    return {
+      status: "accepted",
+      isNew: true,
+      producerId: producer.producerId,
+      proposedState: { epoch: producer.epoch, lastSeq: 0, lastUpdated: now }
+    };
+  }
+  if (producer.epoch < state.epoch) return { status: "stale_epoch", currentEpoch: state.epoch };
+  if (producer.epoch > state.epoch) {
+    if (producer.seq !== 0) return { status: "invalid_epoch_seq" };
+    return {
+      status: "accepted",
+      isNew: true,
+      producerId: producer.producerId,
+      proposedState: { epoch: producer.epoch, lastSeq: 0, lastUpdated: now }
+    };
+  }
+  if (producer.seq <= state.lastSeq) return { status: "duplicate", lastSeq: state.lastSeq };
+  if (producer.seq === state.lastSeq + 1) {
+    return {
+      status: "accepted",
+      isNew: false,
+      producerId: producer.producerId,
+      proposedState: { epoch: producer.epoch, lastSeq: producer.seq, lastUpdated: now }
+    };
+  }
+  return { status: "sequence_gap", expectedSeq: state.lastSeq + 1, receivedSeq: producer.seq };
+}
+function commitStreamProducer(record, result) {
+  if (result.status !== "accepted") return;
+  record.producers = { ...record.producers ?? {}, [result.producerId]: { ...result.proposedState } };
+}
+function cleanupExpiredProducers(record) {
+  if (!record.producers) return;
+  const now = Date.now();
+  const next = {};
+  for (const [id, state] of Object.entries(record.producers)) {
+    if (now - state.lastUpdated <= PRODUCER_STATE_TTL_MS) next[id] = state;
+  }
+  record.producers = Object.keys(next).length ? next : void 0;
+}
+function producerMatchesClosedBy(record, producer) {
+  return record.closedBy?.producerId === producer.producerId && record.closedBy.epoch === producer.epoch && record.closedBy.seq === producer.seq;
+}
+function closedStreamProducerAppend(record, producer) {
+  if (producerMatchesClosedBy(record, producer)) {
+    return {
+      record,
+      message: null,
+      streamClosed: true,
+      producerResult: { status: "duplicate", lastSeq: producer.seq }
+    };
+  }
+  return { record, message: null, streamClosed: true, producerResult: { status: "stream_closed" } };
+}
+function makeStreamMessage(index, data) {
+  return { index, offset: formatStreamOffset(index), dataBase64: bytesToBase64(data), createdAt: Date.now() };
+}
+function formatStreamOffset(index) {
+  if (index < 0) return "-1";
+  return `0000000000000000_${String(index).padStart(16, "0")}`;
+}
+function parseStreamMessageIndex(offset) {
+  if (offset === "-1") return -1;
+  const match = /^\d+_(\d+)$/.exec(offset);
+  if (!match) throw new Error(`Invalid stream offset: ${offset}`);
+  return Number(match[1]);
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    binary += String.fromCharCode(...bytes.slice(i, i + 32768));
+  }
+  return btoa(binary);
+}
+var MIGRATE_SQL = [
+  `CREATE TABLE IF NOT EXISTS atlasflow_sessions (key TEXT PRIMARY KEY, data TEXT NOT NULL, updated_at BIGINT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS atlasflow_runs (
+     run_id TEXT PRIMARY KEY, agent TEXT NOT NULL, instance_id TEXT NOT NULL, status TEXT NOT NULL,
+     result TEXT, error TEXT, started_at BIGINT NOT NULL, ended_at BIGINT, message TEXT, payload TEXT)`,
+  // v2: multimodal agent input replay for durable/background runs.
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS images TEXT`,
+  `CREATE TABLE IF NOT EXISTS atlasflow_run_events (run_id TEXT NOT NULL, idx INTEGER NOT NULL, event TEXT NOT NULL, PRIMARY KEY (run_id, idx))`,
+  // v3: workflow runs (gated processes) — additive, safe on existing tables
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS kind TEXT`,
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS state TEXT`,
+  // v4: execution leases prevent duplicate recovery / duplicate side effects.
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS lease_owner TEXT`,
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS lease_acquired_at BIGINT`,
+  `ALTER TABLE atlasflow_runs ADD COLUMN IF NOT EXISTS lease_expires_at BIGINT`,
+  `CREATE TABLE IF NOT EXISTS atlasflow_streams (
+     path TEXT PRIMARY KEY,
+     content_type TEXT NOT NULL,
+     closed BOOLEAN NOT NULL,
+     current_offset TEXT NOT NULL,
+     last_seq TEXT,
+     created_at BIGINT NOT NULL,
+     updated_at BIGINT NOT NULL,
+     ttl_seconds BIGINT,
+     expires_at TEXT,
+     producers TEXT,
+     closed_by TEXT
+   )`,
+  `ALTER TABLE atlasflow_streams ADD COLUMN IF NOT EXISTS producers TEXT`,
+  `ALTER TABLE atlasflow_streams ADD COLUMN IF NOT EXISTS closed_by TEXT`,
+  `ALTER TABLE atlasflow_streams ADD COLUMN IF NOT EXISTS last_seq TEXT`,
+  `CREATE TABLE IF NOT EXISTS atlasflow_stream_messages (
+     path TEXT NOT NULL,
+     idx INTEGER NOT NULL,
+     stream_offset TEXT NOT NULL,
+     data_base64 TEXT NOT NULL,
+     created_at BIGINT NOT NULL,
+     PRIMARY KEY (path, idx)
+   )`,
+  `CREATE TABLE IF NOT EXISTS atlasflow_stream_subscriptions (
+     id TEXT PRIMARY KEY,
+     data TEXT NOT NULL,
+     updated_at BIGINT NOT NULL
+   )`
+];
+function postgresAdapter(client, options = {}) {
+  const streams = new PgStreamStore(client);
+  return {
+    sessions: new PgSessionStore(client),
+    runs: new PgRunStore(client),
+    streams,
+    subscriptions: new PgSubscriptionStore(client, streams, options.webhooks),
+    async migrate() {
+      for (const stmt of MIGRATE_SQL) await client.query(stmt);
+    },
+    async close() {
+      await client.end?.();
+    }
+  };
+}
+function postgres(connectionString, options = {}) {
+  const sql = postgresDriver(connectionString);
+  const client = {
+    async query(text, params = []) {
+      const rows = await sql.unsafe(text, params);
+      return { rows };
+    },
+    end: () => sql.end()
+  };
+  return postgresAdapter(client, options);
+}
+export {
+  postgres,
+  postgresAdapter
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cybernetyx1/atlasflow-postgres",
+  "version": "0.1.0",
+  "description": "PostgreSQL persistence adapter for AtlasFlow sessions, runs, journals, and streams.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/postgres"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "postgres": "^3.4.5",
+    "@cybernetyx1/atlasflow-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "valibot": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}