@manhquy/flow-skill 0.1.0 → 0.2.0

package/README.md

@@ -10,20 +10,24 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Pre-release channel (current — v0.1.0-rc.3, ships skill v0.22.0)
+# Stable (latest) — current: v0.1.0, ships skill v0.24.0
+npx @manhquy/flow-skill
+
+# Pre-release channel (opt-in)
 npx @manhquy/flow-skill@rc
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.3`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+> **Stable is on `latest`**: bare `npx @manhquy/flow-skill` (or `@0.1.x`) resolves the GA release.
+> Pin `@rc` only if you want the pre-release channel. See [SECURITY.md](./SECURITY.md).
 >
 > **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
-> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@rc` or
+> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill` or
 > `npx flow-skill` after install) to copy the skill into agent homes.
 >
-> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.1.0-rc.3`).
-> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.22.0`).
+> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.1.0`).
+> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.24.0`).
 > `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
@@ -93,8 +97,7 @@ rm -rf <project>/.claude/skills/flow
 
 - **Windows `EBUSY` / `EPERM` mid-install**: an agent (Claude Code, Codex, Antigravity IDE) is holding a file inside the destination. Close the agent and re-run. The installer already retries with 100/300/900 ms backoff before surfacing the error.
 - **Stale advisory lock**: a prior run crashed. The next run detects the dead PID and reclaims the lock automatically. If it does not (very rare — the recorded PID was recycled by another live process), delete `<parent-of-dest>/.flow-skill.installing.lock`.
-- **`No matching version found` on `@0.1.x`**: you are trying to install a pre-release version through a stable range. Use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N` until stable `0.1.0` ships.
-- **`No matching version found` on `@0.22.0`**: that is the **skill product** version, not the npm package version. Use `@rc` / `@0.1.0-rc.N` (installer) — skill content version is printed by `--help` as `ships skill v…`.
+- **`No matching version found` on `@0.24.0`**: that is the **skill product** version, not the npm package version. Install the installer by its own version (bare / `@0.1.x` / `@rc`) — skill content version is printed by `--help` as `ships skill v…`.
 - **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@rc` (or `npx flow-skill` if already installed) and restart the agent.
 - **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
 
@@ -103,7 +106,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0-rc.3","skillVersion":"0.22.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.1.0","skillVersion":"0.24.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}

package/README_VN.md

@@ -10,15 +10,18 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 ## Cài đặt
 
 ```
-# Kênh pre-release (hiện tại — v0.1.0-rc.3, ships skill v0.22.0)
+# Stable (latest) — hiện tại: v0.1.0, ships skill v0.24.0
+npx @manhquy/flow-skill
+
+# Kênh pre-release (tùy chọn)
 npx @manhquy/flow-skill@rc
 ```
 
 Prompt tương tác hỏi cài vào agent nào. Chọn một hoặc nhiều, xác nhận, xong.
 
-> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.3`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
+> **Stable ở `latest`**: bare `npx @manhquy/flow-skill` (hoặc `@0.1.x`) lấy bản GA. Pin `@rc` nếu muốn kênh pre-release. Xem [SECURITY.md](./SECURITY.md).
 >
-> **`npm i` alone chưa đủ** — phải **chạy** CLI (`npx @manhquy/flow-skill@rc`). Hai trục version: package npm vs skill product (`ships skill v…` / `skillVersion` trong JSONL).
+> **`npm i` alone chưa đủ** — phải **chạy** CLI (`npx @manhquy/flow-skill`). Hai trục version: package npm vs skill product (`ships skill v…` / `skillVersion` trong JSONL).
 
 ## Non-interactive
 
@@ -97,7 +100,7 @@ Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ
 
 - **`EBUSY`/`EPERM` giữa install trên Windows**: một agent đang giữ handle vào file trong destination. Đóng agent + re-run. Installer đã retry 100/300/900 ms trước khi báo error.
 - **Advisory lock cũ**: run trước crash. Run mới tự phát hiện PID dead → reclaim. Trường hợp hiếm (PID được recycle bởi process khác đang chạy): xóa `<parent-of-dest>/.flow-skill.installing.lock`.
-- **`No matching version found` với `@0.1.x`**: cài pre-release qua stable range. Dùng `@rc` hoặc `@0.1.0-rc.N` cho tới khi stable `0.1.0` ship.
+- **`No matching version found` với `@0.24.0`**: đó là version **skill product**, không phải version npm package. Cài installer theo version của nó (bare / `@0.1.x` / `@rc`) — version skill in ra ở `--help` (`ships skill v…`).
 - **Node quá cũ** (`requires Node.js >=22.14.0`): update bằng `nvm install 22`, `fnm install 22`, hoặc installer chính thức của Node. Node 20 hết vòng đời từ 4/2026; npm OIDC Trusted Publishing cần npm >=11.5.1 (bundle theo Node 22.14+).
 
 ## Yêu cầu

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {

package/skills/flow/SKILL.md

@@ -8,7 +8,7 @@ keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deplo
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.24.0"
+  version: "0.25.0"
   attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); harness/agent layers from repository-harness, claudekit-engineer, BMAD-METHOD. v0.22 concierge routing pattern adapted from BMAD-METHOD's bmad-help; forge-idea ritual adapted from BMAD-METHOD's bmad-forge-idea (both MIT, BMad Code LLC)."
 ---
 

package/skills/flow/harness/GAP-MATRIX-0.1.17.md

@@ -14,7 +14,8 @@ Supersedes: brainstorm 260703 Thread1 (“nothing to upgrade”).
 | 005 | present | present | File hash may differ on comments only — do not overclaim DDL fork |
 | 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted this plan |
 | 009–012 | **usage/accessed** (flow-only) | improvement identity / links / closure | **Semantic collision** — same numbers, different DDL |
-| 013 | absent | changeset content sha | Not adopted |
+| 013 | absent | changeset content sha | Not adopted — stays reserved/absent |
+| 014+ | **graph-executor** (flow-owned band) | absent | Flow-owned since the 2026-07-26 supersession (plan `260726-1718-harness-graph-executor-langgraph-port`) |
 
 ## Commands / invariants
 
@@ -25,7 +26,7 @@ Supersedes: brainstorm 260703 Thread1 (“nothing to upgrade”).
 | `story verify` | optional shell verify_command | required for shell-proven complete | shell=True = operator-authored only |
 | `query sql` | **not exposed** | read-only connection | Do not add mutating SQL |
 | Rust forward | refused on flow-lineage DB | n/a | `FLOW_HARNESS_BACKEND=rust` → exit 2 when usage mirror / schema≥9 |
-| Changesets / work-graph | not ported | 006–013 | Out of scope (FOMO red line) |
+| Changesets / work-graph | **flow-owned graph executor** (schema band 014+) | 006–013 | **Superseded 2026-07-26** (was: out of scope, FOMO red line) — flow builds its own work-graph; upstream 006–013 will NOT be adopted. Decision record: plan `260726-1718-harness-graph-executor-langgraph-port` |
 | `query contract --json` | not on Python CLI | protocol v1 discovery | Optional external binary smoke only |
 
 ## Pins (consumer)
@@ -38,4 +39,4 @@ DO_NOT_USE              = harness-cli-v0.1.16   # no assets / failed promotion
 
 ## Rust refuse-forward
 
-Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint must refuse forwarding to external `harness-cli` (exit 2). Never unfreeze on `.flow/harness.db` without schema re-home ≥014 (separate epic).
+Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint must refuse forwarding to external `harness-cli` (exit 2). `graph` verbs are NEVER forwarded regardless of DB state (flow-only surface, band 014+). The former "schema re-home ≥014 (separate epic)" note is superseded 2026-07-26: 014+ is now the flow-owned graph-executor band; 013 remains reserved/absent.

package/skills/flow/harness/README.md

@@ -32,6 +32,30 @@ message). Use the Python backend for flow projects. The seam stays in code as a
 power-path for non-flow DBs; flow does not build or ship the binary.
 
 Disable the durable layer entirely with `FLOW_HARNESS_DISABLE=1` (engine still runs).
+**Python floor: 3.7** (measured, not asserted — `subprocess.run(capture_output=, text=)`;
+no walrus/match/builtin generics). `scripts/release-preflight.sh` enforces it, and
+`docs/migration-v1.md` records what a python-mandatory v1 would change.
+
+**Topology pin.** `pins/flow-topology.sha256` pins the canonical-JSON sha256 of
+`references/flow-topology.json`; graph verbs refuse to run on a mismatch (topology is
+executable-adjacent data). After an INTENTIONAL topology edit, run `graph lint` and
+regenerate from the repo root:
+
+```
+PY="$(command -v python3 || command -v python)"   # same cascade flow.sh _python() uses
+"$PY" -c "import json,hashlib;print(hashlib.sha256(json.dumps(json.load(open('skills/flow/references/flow-topology.json')),sort_keys=True,separators=(',',':')).encode()).hexdigest()+'  flow-topology.json')" > skills/flow/harness/pins/flow-topology.sha256
+```
+
+**DB location.** `<FLOW_PROJECT_ROOT>/.flow/harness.db`, with two graph-era rules: a root inside
+a LINKED git worktree is translated to its main-worktree equivalent (all parallel cards share one
+DB). Not translated — each worktree keeps its own DB — for submodules and for
+`--separate-git-dir` repos, where git reports the separate git dir as the main worktree and the
+checkout path is not discoverable; guessing there would put durable state inside `.git`.
+`FLOW_HARNESS_DB=<path>`
+is a narrow test/tool override of the DB path only — never repurpose `FLOW_PROJECT_ROOT` for
+this. Worktree telemetry merges at workspace-remove time via
+`rollup --src <sink> --src-key "<main events.jsonl>#<branch>#<created_at>"` (lifecycle-unique;
+prefixed with the destination sink so `usage`/`prune` see the rows).
 
 ### STRICT durable writes (`flow.sh`)
 
@@ -147,5 +171,8 @@ stage_from→to, card, project_type, mode, flow_version, tier, host, read_only.
 - `schema/00N-*.sql` — DDL. **001-005 are a faithful port of repository-harness** (005 =
   tool-extensions, kind-aware tool registry). **009-012 are flow-specific** (accessed-count +
   usage-log mirror), re-homed off 005-008 so the upstream 005 number is free and the lineages no
-  longer collide. Migrations are column-idempotent and safe to re-run; an old DB built under the
-  pre-005 numbering is reconciled automatically on the next `init`.
+  longer collide. **014+ is the flow-owned graph-executor band** (2026-07-26 supersession of the
+  work-graph red line — see GAP-MATRIX; 013 stays reserved/absent). Migrations are
+  column-idempotent and safe to re-run; an old DB built under the pre-005 numbering is
+  reconciled automatically on the next `init`.
+- `graph_ids.py` — monotonic, lexicographically sortable ids for graph-executor rows (stdlib).

package/skills/flow/harness/_db.py

@@ -1,19 +1,113 @@
 """SQLite durable layer for the flow harness (stdlib sqlite3 only).
 
 Schema lives in schema/00N-*.sql (001-005 a faithful port of repository-harness; 009-012
-flow-specific: accessed-count + usage-log mirror) and is applied by missing-version set; each
-migration bumps schema_version and statements are idempotent, so init/upgrade is safe to re-run.
-DB path defaults to <FLOW_PROJECT_ROOT>/.flow/harness.db.
+flow-specific: accessed-count + usage-log mirror; 014+ flow-owned graph-executor band) and is
+applied by missing-version set; each migration bumps schema_version and statements are
+idempotent, so init/upgrade is safe to re-run. DB path defaults to
+<FLOW_PROJECT_ROOT>/.flow/harness.db, translated to the MAIN worktree when the root sits
+inside a linked git worktree so every parallel card shares one DB.
 """
 
+import contextlib
 import os
 import re
 import sqlite3
+import subprocess
+import time
 
 SCHEMA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema")
 
 
+_worktree_main_cache = {}
+
+
+def _git_env():
+    """Strip inherited GIT_DIR/GIT_WORK_TREE (exported by every git hook, `rebase -x`,
+    `bisect run`, `submodule foreach`): with them set, git answers about a FOREIGN repo
+    and the worktree translation silently splits the journal."""
+    env = dict(os.environ)
+    for k in ("GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE",
+              "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES"):
+        env.pop(k, None)
+    return env
+
+
+def _linked_worktree_main_root(root):
+    """Map `root` inside a LINKED git worktree to its main-worktree equivalent path, else None.
+
+    Card worktrees are full checkouts (they contain flow/ + cards/), so without this
+    translation every parallel card mints its own throwaway .flow/harness.db that
+    `git worktree remove` then deletes. Keys on the RESOLVED ROOT (never CWD — flow.sh
+    passes FLOW_PROJECT_ROOT per call and the two are independent). Cached per process:
+    this runs on every connect and an uncached `git` spawn multiplies on Windows.
+    Any failure (git absent, git < 2.31, not a repo) returns None = current behavior.
+    """
+    if root in _worktree_main_cache:
+        return _worktree_main_cache[root]
+    out = None
+    try:
+        r = subprocess.run(
+            ["git", "-C", root, "rev-parse", "--path-format=absolute",
+             "--git-dir", "--git-common-dir", "--show-toplevel"],
+            capture_output=True, text=True, timeout=10, env=_git_env(),
+        )
+        git_dir = common_dir = worktree_top = None
+        if r.returncode == 0:
+            vals = [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]
+            if len(vals) >= 3:
+                git_dir, common_dir, worktree_top = vals[0], vals[1], vals[2]
+        elif "not a git repository" not in (r.stderr or "").lower():
+            # git < 2.31 lacks --path-format (declared floor); best-effort re-derive.
+            # Gated on the failure NOT being "not a repo" so non-git roots cost one spawn.
+            def _rp(flag):
+                q = subprocess.run(["git", "-C", root, "rev-parse", flag], env=_git_env(),
+                                   capture_output=True, text=True, timeout=10)
+                return q.stdout.strip() if q.returncode == 0 and q.stdout.strip() else None
+            git_dir = _rp("--absolute-git-dir")
+            common_dir = _rp("--git-common-dir")
+            worktree_top = _rp("--show-toplevel")
+            if common_dir and not os.path.isabs(common_dir):
+                common_dir = os.path.abspath(os.path.join(root, common_dir))
+        if git_dir and common_dir and worktree_top:
+            # Linked worktree iff the per-worktree git dir differs from the shared common
+            # dir. Submodules and --separate-git-dir repos have git_dir == common_dir (both
+            # live OUTSIDE the worktree) and must never be translated - dirname(common_dir)
+            # is git internals there, not a project root. realpath everywhere: macOS mktemp
+            # and symlinked checkouts otherwise fail the containment compare silently.
+            if os.path.realpath(git_dir) != os.path.realpath(common_dir):
+                wt = subprocess.run(["git", "-C", root, "worktree", "list", "--porcelain"], env=_git_env(),
+                                    capture_output=True, text=True, timeout=10)
+                first = next((ln for ln in wt.stdout.splitlines()
+                              if ln.startswith("worktree ")), "") if wt.returncode == 0 else ""
+                main_top = first[len("worktree "):].strip()  # main worktree is always first
+                # --separate-git-dir: the main `.git` is a FILE, so git itself reports the
+                # separate git dir as the "main worktree" and does not record the checkout
+                # anywhere discoverable (core.worktree is unset). Translating would put the
+                # DB inside git internals, so REFUSE instead of guessing: the worktree keeps
+                # its own DB (pre-graph behavior), documented in README, rather than
+                # corrupting state. A real checkout always has a `.git` entry.
+                if main_top and not os.path.exists(os.path.join(main_top, ".git")):
+                    main_top = ""
+                rr = os.path.realpath(root)
+                wtop = os.path.realpath(worktree_top)
+                inside = rr == wtop or rr.startswith(wtop + os.sep)
+                if main_top and inside:
+                    main_top = os.path.realpath(main_top)
+                    rel = os.path.relpath(rr, wtop)
+                    out = main_top if rel == "." else os.path.join(main_top, rel)
+    except Exception:
+        out = None  # best-effort: never break the python path over the resolver
+    _worktree_main_cache[root] = out
+    return out
+
+
 def default_db_path(root=None):
+    # Narrow override for tests/tools: DB path ONLY. Never FLOW_PROJECT_ROOT — that is
+    # the global root override and repurposing it would hijack CARDS_DIR/lock/DEBT
+    # resolution for every flow.sh call in a worktree.
+    override = os.environ.get("FLOW_HARNESS_DB")
+    if override:
+        return override
     root = root or os.environ.get("FLOW_PROJECT_ROOT") or os.getcwd()
     # On native Windows Python, translate a Git Bash POSIX root like /c/proj -> c:/proj
     # so the db lands under the project (not relative to the current drive root). Only
@@ -22,6 +116,9 @@ def default_db_path(root=None):
         m = re.match(r"^/([a-zA-Z])/(.*)$", root)
         if m:
             root = m.group(1) + ":/" + m.group(2)
+    main_equiv = _linked_worktree_main_root(root)
+    if main_equiv:
+        root = main_equiv
     return os.path.join(root, ".flow", "harness.db")
 
 
@@ -100,6 +197,9 @@ def connect(db_path=None, root=None, auto_migrate=True):
     con = sqlite3.connect(db_path)
     con.row_factory = sqlite3.Row
     con.execute("PRAGMA foreign_keys = ON")
+    # Explicit 5s wait for the write lock: two parallel card workers share one DB
+    # (worktree-translated path), so contention must queue, not raise `database is locked`.
+    con.execute("PRAGMA busy_timeout = 5000")
     if auto_migrate:
         migrate(con)
     return con
@@ -126,9 +226,25 @@ def _apply_migration(con, sql):
     pragmas = [s for s in stmts if s.upper().startswith("PRAGMA")]
     ddl = [s for s in stmts if not s.upper().startswith("PRAGMA")]
     for p in pragmas:
-        con.execute(p)
+        # Belt-and-braces retry (a pragma can still meet a busy DB on a cold start).
+        for attempt in range(20):
+            try:
+                con.execute(p)
+                break
+            except sqlite3.OperationalError as e:
+                if "locked" not in str(e).lower() and "busy" not in str(e).lower():
+                    raise
+                if attempt == 19:
+                    raise
+                time.sleep(0.05 * (attempt + 1))
     try:
-        con.execute("BEGIN")
+        # IMMEDIATE, not deferred: a deferred BEGIN takes SHARED on the first read probe
+        # (_idempotent_statement inspects sqlite_master/table_info) and the later DDL must
+        # upgrade SHARED->RESERVED - an upgrade SQLite refuses with SQLITE_BUSY IMMEDIATELY,
+        # bypassing the busy handler, so busy_timeout never applies. Taking RESERVED up
+        # front puts the wait where busy_timeout can cover it. This is what made cold-start
+        # parallel card workers lose records.
+        con.execute("BEGIN IMMEDIATE")
         for s in ddl:
             stmt = _idempotent_statement(con, s)
             if stmt is None:
@@ -136,7 +252,10 @@ def _apply_migration(con, sql):
             con.execute(stmt)
         con.execute("COMMIT")
     except Exception:
-        con.execute("ROLLBACK")
+        # rollback(), not execute("ROLLBACK"): if BEGIN IMMEDIATE itself failed there is no
+        # active transaction, and the raw statement would raise "cannot rollback", masking
+        # the original lock error.
+        con.rollback()
         raise
 
 
@@ -219,6 +338,56 @@ def update(con, table, id_col, id_val, **cols):
     return cur.rowcount
 
 
+def update_where(con, table, where, **cols):
+    # SECURITY INVARIANT: `table` and every key in `where`/`cols` must be code literals,
+    # never user input. Composite-key variant of update() for the graph tables whose
+    # primary keys span (execution_id, ns, ...); update()'s single id_col cannot address them.
+    sets, vals = [], []
+    for k, v in cols.items():
+        if v is not None:
+            sets.append(f"{k} = ?")
+            vals.append(v)
+    if not sets:
+        return 0
+    conds = []
+    for k, v in where.items():
+        if v is None:
+            # `col = NULL` never matches in SQL - a None key would silently update nothing.
+            raise ValueError(f"update_where: where[{k!r}] is None")
+        conds.append(f"{k} = ?")
+        vals.append(v)
+    sql = f"UPDATE {table} SET {', '.join(sets)} WHERE {' AND '.join(conds)}"
+    cur = con.execute(sql, vals)
+    con.commit()
+    return cur.rowcount
+
+
+@contextlib.contextmanager
+def transaction(con):
+    """Multi-row atomicity: BEGIN IMMEDIATE ... COMMIT/ROLLBACK.
+
+    IMMEDIATE takes the write lock up front so concurrent worktree writers queue on
+    busy_timeout instead of failing mid-transaction. Do NOT call insert()/update()/
+    update_where() inside this block — their per-call con.commit() would end the
+    transaction early; use con.execute directly. An already-open transaction at entry
+    RAISES (this helper never commits or discards a caller's pending work). The
+    except-path uses con.rollback(), a no-op when SQLite already auto-rolled-back
+    (disk full / IO error), so the ORIGINAL exception always propagates.
+    """
+    if con.in_transaction:
+        raise sqlite3.ProgrammingError(
+            "transaction(): connection already has an open transaction - "
+            "commit or roll it back before entering this block"
+        )
+    con.execute("BEGIN IMMEDIATE")
+    try:
+        yield con
+        con.commit()
+    except Exception:
+        con.rollback()
+        raise
+
+
 def rows(con, sql, params=()):
     return [dict(r) for r in con.execute(sql, params).fetchall()]