okengine 0.22.0 → 0.23.1

package/src/elements/store/sql-session.ts

@@ -51,6 +51,24 @@ export type { WhereMap } from "./sql-condition.ts";
  */
 export type InferSelectRow<T> = T extends { readonly $inferSelect: infer R } ? R : SqlRow;
 
+/**
+ * Insert row from a Drizzle table's `$inferInsert`, or {@link SqlRow}.
+ *
+ * @typeParam T - Table handle or Drizzle table
+ */
+export type InferInsertRow<T> = T extends { readonly $inferInsert: infer R } ? R : SqlRow;
+
+/**
+ * Equality map or a Drizzle SQL fragment (`queryChunks`).
+ * A bare `unknown` would swallow the row type.
+ *
+ * @typeParam TRow - Selected or inserted row
+ */
+export type SqlPredicate<TRow> =
+  | { readonly [K in keyof TRow]?: TRow[K] }
+  | { readonly queryChunks: readonly unknown[] }
+  | undefined;
+
 /** Serialize stamp frames on a shared connection so concurrent identities cannot interleave. */
 const rlsStampTails = new WeakMap<SqlConnection, Promise<unknown>>();
 
@@ -119,6 +137,9 @@ function notifySqlCdc(event: {
  */
 const cdcMutationStorage = new AsyncLocalStorage<{ readonly mutationId: string }>();
 
+/** Pinned connection for {@link SqlStoreHandle.transaction}. */
+const sqlTxStorage = new AsyncLocalStorage<SqlConnection>();
+
 /**
  * Read the ambient mutation id, or `undefined` outside a stamped request.
  */
@@ -274,7 +295,7 @@ export interface SelectFromBuilder<TRow = SqlRow> extends PromiseLike<TRow[]> {
    *
    * @param where - Condition
    */
-  where(where: unknown): SelectWhereBuilder<TRow>;
+  where(where: SqlPredicate<TRow>): SelectWhereBuilder<TRow>;
   /**
    * Order rows with Drizzle `asc()` / `desc()` terms.
    *
@@ -312,14 +333,18 @@ export interface SelectBuilder<TLocked extends SqlRow | undefined = undefined> {
   ): SelectFromBuilder<TLocked extends undefined ? InferSelectRow<TTable> : TLocked>;
 }
 
-/** Fluent insert builder. */
-export interface InsertBuilder {
+/**
+ * Fluent insert builder.
+ *
+ * @typeParam TRow - `$inferInsert` when the table is a Drizzle table
+ */
+export interface InsertBuilder<TRow = SqlRow> {
   /**
    * Provide row values.
    *
    * @param row - Row to insert
    */
-  values(row: SqlRow): InsertValuesBuilder;
+  values(row: TRow): InsertValuesBuilder;
 }
 
 /**
@@ -340,7 +365,7 @@ export interface DeleteBuilder {
    *
    * @param where - Equality map or Drizzle SQL
    */
-  where(where: unknown): Promise<number>;
+  where(where: SqlPredicate<SqlRow>): Promise<number>;
 }
 
 /** Fluent update builder. */
@@ -360,7 +385,7 @@ export interface UpdateSetBuilder {
    *
    * @param where - Equality map or Drizzle SQL
    */
-  where(where: unknown): Promise<number>;
+  where(where: SqlPredicate<SqlRow>): Promise<number>;
 }
 
 /**
@@ -393,7 +418,7 @@ export interface SqlStoreHandle {
    *
    * @param table - Target table
    */
-  insert(table: TableHandle | unknown): InsertBuilder;
+  insert<TTable>(table: TTable): InsertBuilder<InferInsertRow<TTable>>;
   /**
    * Start an update on `table`.
    *
@@ -415,6 +440,22 @@ export interface SqlStoreHandle {
    */
   delete(table: TableHandle | unknown): DeleteBuilder;
   delete(table: TableHandle | unknown, id: string): Promise<boolean>;
+  /**
+   * Run `fn` on one pinned connection. `fx.emit` inside `fn` stages on the
+   * signal outbox and publishes only after this SQL transaction commits.
+   *
+   * @param fn - Transaction body. `tx` is this handle, bound to the pin.
+   */
+  transaction<T>(fn: (tx: SqlStoreHandle) => Promise<T>): Promise<T>;
+  /**
+   * Execute a Drizzle select, insert, update, or delete builder.
+   * Calls `toSQL()` so `drizzle-orm` stays off the edge graph.
+   *
+   * @param query - Builder with `toSQL()`
+   */
+  run<T extends SqlRow = SqlRow>(query: {
+    toSQL(): { readonly sql: string; readonly params: readonly unknown[] };
+  }): Promise<T[]>;
   /**
    * True when at least one row matches.
    *
@@ -424,7 +465,9 @@ export interface SqlStoreHandle {
   exists(table: TableHandle | unknown, idOrWhere: string | WhereMap): Promise<boolean>;
   /**
    * Insert when no row matches `matchOn`; never touches an existing match
-   * unless `options.onExisting` is `"update"`.
+   * unless `options.onExisting` is `"update"`. A match that is only the
+   * primary key is one `INSERT … ON CONFLICT` round trip on postgres and
+   * pglite. Memory SQL, and any other predicate, stays a read then a write.
    *
    * @param table - Table
    * @param matchOn - Equality map or Drizzle condition identifying the row
@@ -562,6 +605,10 @@ export function createSqlStoreHandle(
     }
   }
 
+  function activeConnection(): SqlConnection {
+    return sqlTxStorage.getStore() ?? connection;
+  }
+
   function query(sql: string, params: readonly unknown[] = []): Promise<SqlRow[]> {
     return withSchemaGuard(() => withRlsStamp((conn) => conn.query(sql, params), sql));
   }
@@ -570,9 +617,29 @@ export function createSqlStoreHandle(
     return withSchemaGuard(() => withRlsStamp((conn) => conn.exec(sql, params), sql));
   }
 
+  /**
+   * Rewrite Drizzle `$1` placeholders to the connection's `?` form.
+   *
+   * @param sql - Dialect SQL
+   * @param params - Bindings in `$n` order (1-based)
+   */
+  function fromDialect(
+    sql: string,
+    params: readonly unknown[],
+  ): { sql: string; params: unknown[] } {
+    if (!sql.includes("$")) return { sql, params: [...params] };
+    const ordered: unknown[] = [];
+    const text = sql.replace(/\$(\d+)/g, (_match, index: string) => {
+      ordered.push(params[Number(index) - 1]);
+      return "?";
+    });
+    return { sql: text, params: ordered };
+  }
+
   async function withRlsStamp<T>(fn: (conn: SqlConnection) => Promise<T>, sql: string): Promise<T> {
-    if (!rls || !RLS_CONTEXT_DRIVERS.has(connection.driverId)) return fn(connection);
-    if (isRlsStampExemptSql(sql)) return fn(connection);
+    if (!rls || !RLS_CONTEXT_DRIVERS.has(connection.driverId)) return fn(activeConnection());
+    if (isRlsStampExemptSql(sql)) return fn(activeConnection());
+    if (sqlTxStorage.getStore()) return fn(activeConnection());
     const run = (): Promise<T> => applyRlsStamp(fn);
     // PGlite is one backend session — concurrent identities must not interleave.
     // Pooled postgres pins each stamp via `transaction()` instead.
@@ -685,6 +752,101 @@ export function createSqlStoreHandle(
     return coerceCompiledWhere(table, compileWhere(where));
   }
 
+  /**
+   * Primary-key equality only. Any other predicate cannot use `ON CONFLICT`.
+   *
+   * @param compiled - Match clause
+   * @param pkCol - Primary key SQL name
+   */
+  function primaryKeyEquality(
+    compiled: ReturnType<typeof compileWhere>,
+    pkCol: string,
+  ): { readonly value: unknown } | undefined {
+    if (compiled.predicates.length !== 1) return undefined;
+    const pred = compiled.predicates[0];
+    if (!pred || pred.op !== "=" || pred.column !== pkCol) return undefined;
+    return { value: pred.value };
+  }
+
+  /**
+   * One round trip: `INSERT … ON CONFLICT (pk)`.
+   *
+   * `DO NOTHING` when the existing row must stay. `DO UPDATE` captures the
+   * pre-image in a CTE so CDC still sees before and after.
+   *
+   * @param table - Table
+   * @param name - SQL table name
+   * @param pkCol - Primary key SQL name
+   * @param pkValue - Bound primary key
+   * @param values - Insert / update payload
+   * @param onExisting - `"update"` rewrites the existing row
+   */
+  async function upsertOnPrimaryKey(
+    table: TableHandle | unknown,
+    name: string,
+    pkCol: string,
+    pkValue: unknown,
+    values: SqlRow,
+    onExisting: "update" | undefined,
+  ): Promise<UpsertResult> {
+    const prepared = prepareInsertRow(table, values);
+    if (!(pkCol in prepared)) prepared[pkCol] = pkValue;
+    const cols = Object.keys(prepared);
+    const colList = cols.map(quoteIdent).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    const params = cols.map((col) => prepared[col]);
+    const quotedPk = quoteIdent(pkCol);
+    const quotedName = quoteIdent(name);
+    const setEntries =
+      onExisting === "update"
+        ? Object.entries(prepareUpdateRow(table, values)).filter(([col]) => col !== pkCol)
+        : [];
+    if (onExisting !== "update" || setEntries.length === 0) {
+      const rows = await query(
+        `INSERT INTO ${quotedName} (${colList}) VALUES (${placeholders})` +
+          ` ON CONFLICT (${quotedPk}) DO NOTHING RETURNING *`,
+        params,
+      );
+      if (rows.length === 0) {
+        return { status: onExisting === "update" ? "changed" : "already-existed" };
+      }
+      notifySqlCdc({
+        tableName: name,
+        op: "insert",
+        before: null,
+        after: toJs(table, rows)[0] ?? null,
+      });
+      return { status: "upserted" };
+    }
+    const setSql = setEntries
+      .map(([col]) => `${quoteIdent(col)} = EXCLUDED.${quoteIdent(col)}`)
+      .join(", ");
+    // The old row is a CTE, then read from an outer SELECT. INSERT …
+    // RETURNING cannot see that CTE on PGlite, so the before image would
+    // be null and an update would look like an insert.
+    const result = await query(
+      `WITH __oke_old AS (` +
+        `SELECT * FROM ${quotedName} WHERE ${quotedPk} = ? FOR UPDATE` +
+        `), __oke_new AS (` +
+        `INSERT INTO ${quotedName} (${colList}) VALUES (${placeholders})` +
+        ` ON CONFLICT (${quotedPk}) DO UPDATE SET ${setSql}` +
+        ` RETURNING *` +
+        `) SELECT (SELECT row_to_json(__oke_old) FROM __oke_old) AS __oke_before_data,` +
+        ` (SELECT row_to_json(__oke_new) FROM __oke_new) AS __oke_after_data`,
+      [pkValue, ...params],
+    );
+    const raw = result[0];
+    const before = raw ? jsonImageToJs(table, raw.__oke_before_data) : null;
+    const after = raw ? jsonImageToJs(table, raw.__oke_after_data) : null;
+    notifySqlCdc({
+      tableName: name,
+      op: before ? "update" : "insert",
+      before,
+      after,
+    });
+    return { status: before ? "changed" : "upserted" };
+  }
+
   /**
    * Postgres `row_to_json` images come back as JSON strings on pglite and
    * objects on Bun.SQL — normalize to the JS row mapping (snake→camel).
@@ -1026,6 +1188,19 @@ export function createSqlStoreHandle(
       if (!compiled.clause) {
         throw new Error("upsert() requires at least one matchOn predicate");
       }
+      const pkCol = resolvePkColumn(table);
+      const pkMatch = primaryKeyEquality(compiled, pkCol);
+      // Memory SQL has no ON CONFLICT. Postgres and PGlite do.
+      if (pkMatch && connection.driverId !== "memory") {
+        return upsertOnPrimaryKey(
+          table,
+          name,
+          pkCol,
+          pkMatch.value,
+          values,
+          upsertOptions?.onExisting,
+        );
+      }
       const found = await query(
         `SELECT 1 AS "ok" FROM ${quoteIdent(name)} WHERE ${compiled.clause} LIMIT 1`,
         compiled.params,
@@ -1222,6 +1397,27 @@ export function createSqlStoreHandle(
       });
     },
 
+    async transaction<T>(fn: (tx: SqlStoreHandle) => Promise<T>): Promise<T> {
+      if (!connection.transaction) {
+        throw new Error("fx.store().transaction needs SqlConnection.transaction");
+      }
+      return connection.transaction(async (txConn) =>
+        sqlTxStorage.run(txConn, () => fn(handle as SqlStoreHandle)),
+      );
+    },
+
+    async run<T extends SqlRow = SqlRow>(builder: {
+      toSQL(): { readonly sql: string; readonly params: readonly unknown[] };
+    }): Promise<T[]> {
+      const compiled = builder.toSQL();
+      const dialect = fromDialect(compiled.sql, compiled.params);
+      if (isSqlDml(dialect.sql)) {
+        await exec(dialect.sql, dialect.params);
+        return [];
+      }
+      return query(dialect.sql, dialect.params) as Promise<T[]>;
+    },
+
     async ensureTable(table: TableHandle) {
       const cols = Object.values(table.columns);
       const pk = resolvePkColumn(table);

package/src/elements/store.ts

@@ -137,6 +137,7 @@ export type {
   SelectWhereBuilder,
   SelectOrderBuilder,
   InferSelectRow,
+  SqlPredicate,
   InsertBuilder,
   InsertValuesBuilder,
   SqlSessionOptions,

package/src/i18n/catalogs/ar.ts

@@ -40,6 +40,10 @@ export const builtinAr = {
       cause: 'التدفق "{flow}" يضمّن عبر "{resource}" دون الإعلان عنه.',
       fix: 'أضف "{resource}" إلى effects.embeds لهذا التدفق.',
     },
+    "1010": {
+      cause: 'التدفق "{flow}" يقرر "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.decides لهذا التدفق.',
+    },
     "1240": {
       cause: 'التدفق "{flow}" يُصدِر الإشارة "{resource}" بلا مشترك.',
       fix: "أضف on({resource}, …) أو عيّن الإشارة '{'optional: true'}'.",
@@ -90,6 +94,7 @@ export const builtinAr = {
     IdempotencyKeyInvalid: "يجب أن يكون Idempotency-Key من 16 إلى 255 حرفًا ASCII قابلًا للطباعة.",
     IdempotencyKeyReused: "استُخدم Idempotency-Key هذا من قبل مع طلب مختلف.",
     IdempotencyInProgress: "ما زال Idempotency-Key هذا قيد التنفيذ. أعد المحاولة بعد المهلة.",
+    JournalLeaseBusy: "هذا التشغيل مقفل لدى عامل آخر. أعد المحاولة بعد المهلة.",
     InvalidQuery: "الاستعلام غير صالح.",
     UnsupportedMediaType: "نوع المحتوى هذا غير مدعوم.",
     AuthFailed: "فشلت المصادقة.",

package/src/i18n/catalogs/en.ts

@@ -40,6 +40,10 @@ export const builtinEn = {
       cause: 'Flow "{flow}" embeds with "{resource}" without declaring it.',
       fix: "Add \"{resource}\" to this flow''s effects.embeds.",
     },
+    "1010": {
+      cause: 'Flow "{flow}" decides "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.decides.",
+    },
     "1240": {
       cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
       fix: "Add on({resource}, …) or mark the signal '{'optional: true'}'.",
@@ -90,6 +94,7 @@ export const builtinEn = {
     IdempotencyKeyInvalid: "Idempotency-Key must be 16–255 printable ASCII characters.",
     IdempotencyKeyReused: "This Idempotency-Key was already used with a different request.",
     IdempotencyInProgress: "This Idempotency-Key is still running. Retry after the given delay.",
+    JournalLeaseBusy: "This run is locked by another worker. Retry after the given delay.",
     InvalidQuery: "The query is not valid.",
     UnsupportedMediaType: "That content type is not supported.",
     AuthFailed: "Authentication failed.",

package/src/index.ts

@@ -175,6 +175,8 @@ export {
   type AiModelDecl,
   type AiPromptDecl,
   type AiAgentDecl,
+  type AiDecisionDecl,
+  type AiDecisionOptions,
   type AiMcpServerDecl,
   type AiMcpServerOptions,
   type AiRuntime,