quantum-framework 0.18.0__tar.gz → 0.19.0__tar.gz

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-framework
-Version: 0.18.0
+Version: 0.19.0
 Summary: Full-stack declarative framework for building web, desktop, and mobile applications
 Author-email: Daniel Gregorio <danielgregorio2611@gmail.com>
 License: MIT

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantum-framework"
-version = "0.18.0"
+version = "0.19.0"
 description = "Full-stack declarative framework for building web, desktop, and mobile applications"
 readme = "README.md"
 license = {text = "MIT"}

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/quantum/cli/runner.py

@@ -399,6 +399,15 @@ Examples:
     migrate_create_parser = migrate_subparsers.add_parser('create', help='Create a new migration')
     migrate_create_parser.add_argument('name', help='Migration name')
 
+    # M6 (DB-10): schema.sql as the source of truth
+    migrate_plan_parser = migrate_subparsers.add_parser(
+        'plan', help='Compare schema.sql with the migrations and plan the migration')
+    migrate_plan_parser.add_argument('--schema', default='schema.sql', help='Schema file (default: schema.sql)')
+    migrate_plan_parser.add_argument('--write', metavar='NAME', help='Save the plan as migration V00N_NAME')
+    migrate_plan_parser.add_argument('--yes', action='store_true', help='Do not ask before writing')
+    migrate_plan_parser.add_argument('--allow-data-loss', action='store_true',
+                                     help='Write a plan that drops tables or columns')
+
     # Parse arguments
     args = parser.parse_args()
 
@@ -541,13 +550,18 @@ Examples:
                 if failed:
                     sys.exit(1)
 
+            elif args.migrate_command == 'plan':
+                from quantum.cli.schema_plan import run_plan
+                sys.exit(run_plan(Path.cwd(), args.schema, args.write, args.yes, args.allow_data_loss,
+                                  interactive=sys.stdin.isatty()))
+
             elif args.migrate_command == 'create':
                 filepath = runner.create(args.name)
                 print(f"Created migration: {filepath}")
                 print(f"Also created rollback: {filepath.with_suffix('.down.sql')}")
 
             else:
-                print("Usage: quantum migrate <status|up|down|create> [options]")
+                print("Usage: quantum migrate <status|up|down|create|plan> [options]")
                 sys.exit(1)
 
             sys.exit(0)

quantum_framework-0.19.0/quantum/cli/schema_plan.py

@@ -0,0 +1,273 @@
+"""`quantum migrate plan`: a declarative schema (M6, DB-10).
+
+You edit `schema.sql` — the tables as they should be. `quantum migrate plan`
+compares it with the schema the migrations produce, shows what changes, marks
+what loses data, and `--write` saves the migration (and its rollback) after
+confirmation. `quantum migrate up` applies it as any other.
+
+Both sides are built in in-memory SQLite databases — the migrations applied in
+order, and schema.sql — and compared with the schema reader of `quantum check`
+(quantum/runtime/db_schema.py). The development database is not read: the
+plan is the same on any machine and in CI.
+
+SQLite can add a column but not change one, so any other change to a table
+rebuilds it: create the new table, copy the columns both have, drop the old,
+rename. Before a plan is written it is checked: applied to the migrations'
+schema it must produce exactly schema.sql's.
+"""
+
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from quantum.runtime.db_schema import Column, read_schema
+
+# Tables that belong to Quantum, not to the app's schema.
+INTERNAL_TABLES = {'_migrations', 'quantum_history'}
+
+
+class SchemaPlanError(Exception):
+    """The plan cannot be made (no schema.sql, invalid SQL, a change it cannot express)."""
+
+
+@dataclass
+class Step:
+    kind: str                 # add-table, drop-table, add-column, rebuild, add-index, drop-index
+    target: str               # "posts" or "posts.summary"
+    detail: str = ''
+    sql: List[str] = field(default_factory=list)
+    loses_data: bool = False
+    warning: str = ''
+
+    def line(self) -> str:
+        mark = {'add-table': '+', 'add-column': '+', 'add-index': '+', 'drop-table': '-',
+                'drop-index': '-', 'rebuild': '~'}.get(self.kind, '?')
+        text = f'{mark} {self.kind.replace("-", " ")} {self.target}'
+        if self.detail:
+            text += f' ({self.detail})'
+        if self.loses_data:
+            text += '  !! loses data'
+        if self.warning:
+            text += f'  !! {self.warning}'
+        return text
+
+
+def _database(scripts: List[Tuple[str, str]]) -> sqlite3.Connection:
+    conn = sqlite3.connect(':memory:')
+    for origin, sql in scripts:
+        try:
+            conn.executescript(sql)
+        except sqlite3.Error as exc:
+            raise SchemaPlanError(f'{origin}: {exc}') from exc
+    return conn
+
+
+def _migration_scripts(migrations_dir: Path) -> List[Tuple[str, str]]:
+    if not migrations_dir.exists():
+        return []
+    files = [f for f in sorted(migrations_dir.glob('*.sql')) if not f.name.endswith('.down.sql')]
+    return [(f.name, f.read_text(encoding='utf-8')) for f in files if '_' in f.stem]
+
+
+def _tables(conn) -> Dict[str, object]:
+    return {name: t for name, t in read_schema(conn).items() if name not in INTERNAL_TABLES}
+
+
+def _create_sql(conn, table: str) -> str:
+    return conn.execute("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
+                        (table,)).fetchone()[0]
+
+
+def _indexes(conn) -> Dict[str, Tuple[str, str]]:
+    """Explicit indexes: name -> (table, sql)."""
+    return {name: (table, sql) for name, table, sql in conn.execute(
+        "SELECT name, tbl_name, sql FROM sqlite_master WHERE type = 'index' AND sql IS NOT NULL")
+        if table not in INTERNAL_TABLES}
+
+
+def _column_sql(column: Column) -> str:
+    parts = [f'"{column.name}"']
+    if column.type:
+        parts.append(column.type)
+    if column.not_null:
+        parts.append('NOT NULL')
+    if column.default is not None:
+        parts.append(f'DEFAULT {column.default}')
+    if column.options:
+        options = ', '.join("'" + o.replace("'", "''") + "'" for o in column.options)
+        parts.append(f'CHECK ("{column.name}" IN ({options}))')
+    if column.references:
+        parts.append(f'REFERENCES "{column.references[0]}"("{column.references[1]}")')
+    return ' '.join(parts)
+
+
+def _differences(a: Column, b: Column) -> List[str]:
+    changed = []
+    for label, x, y in (('type', (a.type or '').upper(), (b.type or '').upper()),
+                        ('NOT NULL', a.not_null, b.not_null), ('default', a.default, b.default),
+                        ('primary key', a.primary_key, b.primary_key), ('CHECK', a.options, b.options),
+                        ('references', a.references, b.references)):
+        if x != y:
+            changed.append(label)
+    return changed
+
+
+def diff(current_db, desired_db) -> List[Step]:
+    """The steps that turn the first database's schema into the second's."""
+    current, desired = _tables(current_db), _tables(desired_db)
+    steps: List[Step] = []
+    rebuilt = set()
+
+    for name in sorted(set(desired) - set(current)):
+        steps.append(Step('add-table', name, sql=[_create_sql(desired_db, name) + ';']))
+
+    for name in sorted(set(current) & set(desired)):
+        before, after = current[name].columns, desired[name].columns
+        added = [c for c in after if c not in before]
+        removed = [c for c in before if c not in after]
+        changed = {c: _differences(before[c], after[c]) for c in before
+                   if c in after and _differences(before[c], after[c])}
+        addable = all(not after[c].primary_key and (not after[c].not_null or after[c].default is not None)
+                      for c in added)
+        if not removed and not changed and addable:
+            for c in added:
+                steps.append(Step('add-column', f'{name}.{c}', after[c].type or '',
+                                  [f'ALTER TABLE "{name}" ADD COLUMN {_column_sql(after[c])};']))
+            continue
+        if not (added or removed or changed):
+            continue
+        common = ', '.join(f'"{c}"' for c in after if c in before)
+        create = re.sub(r'^\s*CREATE\s+TABLE\s+("?)' + re.escape(name) + r'\1',
+                        f'CREATE TABLE "{name}__new"', _create_sql(desired_db, name), count=1, flags=re.I)
+        details = [f'+ {c}' for c in added] + [f'- {c}' for c in removed] + \
+                  [f'{c}: {", ".join(d)}' for c, d in changed.items()]
+        warning = ''
+        if any('NOT NULL' in d and after[c].not_null for c, d in changed.items()) or \
+                any(after[c].not_null and after[c].default is None for c in added):
+            warning = 'fails if existing rows have no value for a NOT NULL column'
+        steps.append(Step('rebuild', name, '; '.join(details), [
+            create + ';',
+            f'INSERT INTO "{name}__new" ({common}) SELECT {common} FROM "{name}";',
+            f'DROP TABLE "{name}";',
+            f'ALTER TABLE "{name}__new" RENAME TO "{name}";',
+        ], loses_data=bool(removed) or any('type' in d for d in changed.values()), warning=warning))
+        rebuilt.add(name)
+
+    for name in sorted(set(current) - set(desired)):
+        steps.append(Step('drop-table', name, sql=[f'DROP TABLE "{name}";'], loses_data=True))
+
+    # Indexes: a rebuilt table lost its own, so they are created again.
+    before_idx, after_idx = _indexes(current_db), _indexes(desired_db)
+    for name, (table, sql) in sorted(before_idx.items()):
+        if table in desired and table not in rebuilt and after_idx.get(name, (None, None))[1] != sql:
+            steps.append(Step('drop-index', name, sql=[f'DROP INDEX "{name}";']))
+    for name, (table, sql) in sorted(after_idx.items()):
+        if before_idx.get(name, (None, None))[1] != sql or table in rebuilt:
+            steps.append(Step('add-index', name, sql=[sql + ';']))
+    return steps
+
+
+def _schema_only(conn) -> str:
+    """The CREATE statements of a database, tables before indexes, without its rows."""
+    rows = conn.execute("SELECT type, sql FROM sqlite_master WHERE sql IS NOT NULL "
+                        "AND name NOT LIKE 'sqlite_%' ORDER BY type = 'index', rowid").fetchall()
+    return '\n'.join(sql + ';' for _type, sql in rows)
+
+
+def _signature(conn) -> tuple:
+    tables = _tables(conn)
+    return (tuple(sorted((n, tuple(sorted((c.name, (c.type or '').upper(), c.not_null, c.default, c.primary_key,
+                                              tuple(c.options or ()), c.references)
+                                             for c in t.columns.values()))) for n, t in tables.items())),
+            tuple(sorted((n, s) for n, (_t, s) in _indexes(conn).items())))
+
+
+@dataclass
+class Plan:
+    steps: List[Step]
+    up_sql: str
+    down_sql: str
+
+    @property
+    def loses_data(self) -> bool:
+        return any(s.loses_data for s in self.steps)
+
+
+def make_plan(schema_file: Path, migrations_dir: Path) -> Plan:
+    if not schema_file.exists():
+        raise SchemaPlanError(f'{schema_file} does not exist: write the tables as they should be, '
+                              f'e.g. CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT NOT NULL);')
+    migrations = _migration_scripts(migrations_dir)
+    current = _database(migrations)
+    desired = _database([(schema_file.name, schema_file.read_text(encoding='utf-8'))])
+    steps = diff(current, desired)
+    up = '\n'.join(s for step in steps for s in step.sql)
+    down = '\n'.join(s for step in diff(desired, current) for s in step.sql)
+    if steps:
+        # The plan must do what it says: applied, it yields schema.sql's schema.
+        # Checked on the structure only — what existing rows may break is the
+        # step's warning, shown in the plan, not a reason to hide the plan.
+        check = _database([('migrations (schema only)', _schema_only(current)), ('plan', up)])
+        if _signature(check) != _signature(desired):
+            raise SchemaPlanError('the generated migration does not reproduce schema.sql — '
+                                  'write this change as a migration by hand (quantum migrate create)')
+    return Plan(steps, up, down)
+
+
+def next_version(migrations_dir: Path) -> str:
+    numbers = [int(m.group(1)) for f in migrations_dir.glob('V*.sql')
+               for m in [re.match(r'V(\d+)_', f.name)] if m]
+    return f'V{(max(numbers) + 1 if numbers else 1):03d}'
+
+
+def write_plan(plan: Plan, migrations_dir: Path, name: str) -> Path:
+    migrations_dir.mkdir(parents=True, exist_ok=True)
+    slug = re.sub(r'[^a-z0-9_]+', '_', name.lower()).strip('_') or 'schema'
+    version = next_version(migrations_dir)
+    path = migrations_dir / f'{version}_{slug}.sql'
+    header = '-- Generated by `quantum migrate plan` from schema.sql (DB-10)\n'
+    summary = '\n'.join(f'-- {s.line()}' for s in plan.steps)
+    path.write_text(f'{header}{summary}\n\n{plan.up_sql}\n', encoding='utf-8')
+    (migrations_dir / f'{version}_{slug}.down.sql').write_text(
+        f'{header}-- rollback\n\n{plan.down_sql}\n', encoding='utf-8')
+    return path
+
+
+def run_plan(project: Path, schema: Optional[str], write: Optional[str], yes: bool,
+             allow_data_loss: bool, ask=input, interactive: bool = True) -> int:
+    """The `quantum migrate plan` command. Returns the exit code."""
+    from quantum.cli.commands.migrate import _paths_migrations
+    migrations_dir = project / _paths_migrations(project)
+    schema_file = project / (schema or 'schema.sql')
+    try:
+        plan = make_plan(schema_file, migrations_dir)
+    except SchemaPlanError as exc:
+        print(f'[ERROR] {exc}')
+        return 1
+    if not plan.steps:
+        print(f'Nothing to do: the migrations already produce {schema_file.name}.')
+        return 0
+    print(f'Plan: {schema_file.name} vs. the migrations in {migrations_dir.name}/\n')
+    for step in plan.steps:
+        print('  ' + step.line())
+    print('\nSQL:\n' + plan.up_sql)
+    if not write:
+        print('\nNothing written. `quantum migrate plan --write <name>` saves it as a migration.')
+        return 0
+    if plan.loses_data and not allow_data_loss:
+        print('\n[REFUSED] This plan loses data (marked !!). Check it, then run again with '
+              '--allow-data-loss.')
+        return 1
+    if not yes:
+        if not interactive:
+            print('\n[REFUSED] Confirm with --yes (not a terminal: nobody to ask).')
+            return 1
+        answer = ask(f'\nWrite migration {next_version(migrations_dir)}_{write}? [y/N] ').strip().lower()
+        if answer not in ('y', 'yes'):
+            print('Nothing written.')
+            return 1
+    path = write_plan(plan, migrations_dir, write)
+    print(f'Written: {path} (and {path.stem}.down.sql). Apply with `quantum migrate up`.')
+    return 0

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/quantum/core/features/ui_engine/src/ast_nodes.py

@@ -1896,6 +1896,24 @@ class UIPagerNode(QuantumNode, UILayoutMixin):
         return [] if self.for_query else ["ui:pager needs for="]
 
 
+class UIHistoryNode(QuantumNode, UILayoutMixin):
+    """<ui:history table="t" key="{row.id}" datasource="db"> — a row's change history (DB-11)."""
+
+    def __init__(self):
+        self.table: Optional[str] = None
+        self.key: Optional[str] = None
+        self.datasource: Optional[str] = None
+        self.limit: int = 50
+        self.children: List[QuantumNode] = []
+        self._init_layout_attrs()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": "ui_history", "table": self.table, "key": self.key}
+
+    def validate(self) -> List[str]:
+        return []
+
+
 def is_ui_node(node) -> bool:
     """A ui:* element (UI-1): markup, drawn by a renderer, never executed."""
     return type(node).__module__ == __name__
@@ -1908,6 +1926,6 @@ CORE_TAGS = frozenset({
     'window', 'hbox', 'vbox', 'grid', 'panel', 'section', 'scrollbox', 'spacer', 'rule',
     'header', 'footer', 'card', 'card-header', 'card-body', 'card-footer', 'tabpanel', 'tab',
     'text', 'badge', 'alert', 'link', 'image', 'progress',
-    'table', 'column', 'list', 'item', 'pager',
+    'table', 'column', 'list', 'item', 'pager', 'history',
     'form', 'formitem', 'input', 'checkbox', 'switch', 'radio', 'select', 'option', 'button',
 })

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/quantum/core/features/ui_engine/src/parser.py

@@ -28,7 +28,7 @@ from .ast_nodes import (
     UIToastNode, UIToastContainerNode,
     UICarouselNode, UISlideNode,
     UIStepperNode, UIStepNode,
-    UICalendarNode, UIDatePickerNode, UIPagerNode,
+    UICalendarNode, UIDatePickerNode, UIPagerNode, UIHistoryNode,
 )
 from quantum.core.features.theming.src import UIThemeNode, UIColorNode
 from quantum.core.ast_nodes import TextNode
@@ -82,6 +82,7 @@ class UIParser:
         'table': '_parse_ui_table',
         'column': '_parse_ui_column',
         'pager': '_parse_ui_pager',
+        'history': '_parse_ui_history',
         'list': '_parse_ui_list',
         'item': '_parse_ui_item',
         'image': '_parse_ui_image',
@@ -550,6 +551,21 @@ class UIParser:
         self._apply_layout_attrs(node, element)
         return node
 
+    def _parse_ui_history(self, element: ET.Element) -> UIHistoryNode:
+        node = UIHistoryNode()
+        node.table = element.get('table')
+        node.key = element.get('key')
+        node.datasource = element.get('datasource')
+        missing = [a for a in ('table', 'key', 'datasource') if not element.get(a)]
+        if missing:
+            raise UIParseError(f'<ui:history> needs {", ".join(a + "=" for a in missing)}')
+        limit = element.get('limit')
+        if limit is not None and not limit.isdigit():
+            raise UIParseError(f'<ui:history limit="{limit}">: a number of entries')
+        node.limit = int(limit) if limit is not None else 50
+        self._apply_layout_attrs(node, element)
+        return node
+
     def _parse_ui_list(self, element: ET.Element) -> UIListNode:
         node = UIListNode()
         node.source = element.get('source')

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/quantum/runtime/action_handler.py

@@ -122,9 +122,12 @@ class ActionHandler:
                 context.set_variable(key, value)
 
             # 4. Execute action body
+            from quantum.runtime import history
+            history_token = history.enter(getattr(action, 'name', None), context.session_vars)   # M22
             try:
                 redirect_info = self._execute_action_body(action, context)
             finally:
+                history.leave(history_token)
                 # M12: the /_dev panel shows the action's variables (no-op off debug).
                 from quantum.runtime.dev_panel import note_scopes
                 note_scopes(context, 'action')

{quantum_framework-0.18.0 → quantum_framework-0.19.0}/quantum/runtime/database_service.py

@@ -86,6 +86,7 @@ class DatabaseService:
                 'port': local_cfg.get('port', 5432),
                 'username': local_cfg.get('username', ''),
                 'password': local_cfg.get('password', ''),
+                'history': bool(local_cfg.get('history')),        # M22 (DB-11)
             }
 
         # DB-7: a datasource is declared in quantum.config.yaml, or it does not
@@ -277,6 +278,13 @@ class DatabaseService:
             # Convert :param syntax to database-specific placeholder
             prepared_sql, prepared_params = self._prepare_query(sql, params, db_type)
 
+            # M22 (DB-11): with history on, an action's write records the rows it touches.
+            capture = None
+            if config.get('history') and db_type == 'sqlite':
+                from quantum.runtime import history
+                capture = history.begin(conn, sql, params,
+                                        lambda q, p: self._prepare_query(q, p, db_type))
+
             # Execute query
             cursor.execute(prepared_sql, prepared_params)
 
@@ -309,6 +317,10 @@ class DatabaseService:
                 # Non-SELECT query (INSERT, UPDATE, DELETE). Commit now ONLY
                 # when standalone; inside a transaction the commit is deferred
                 # to commit_transaction so a later failure can roll it back.
+                if capture is not None:
+                    # Before the commit: the write and its history go together.
+                    from quantum.runtime import history
+                    history.finish(conn, capture, getattr(cursor, 'lastrowid', None))
                 if not in_transaction:
                     conn.commit()
                 data = []

quantum_framework-0.19.0/quantum/runtime/history.py

@@ -0,0 +1,203 @@
+"""Change history, per datasource (M22, DB-11).
+
+With `history: true` on a datasource, every write an action makes to it —
+INSERT, UPDATE, DELETE, including the cells of an editable table (UI-13) — is
+recorded in a `quantum_history` table of that same database: when, who (the
+session's user), which action, which row, and the row before and after, as
+JSON. The record is written on the same connection, before the commit, so a
+write and its history commit or roll back together.
+
+Only writes made by actions are recorded: page statements do not write in a
+well-formed app, and migrations are not changes to records. A write whose
+shape is not a single-table INSERT/UPDATE/DELETE is still recorded, with its
+SQL and no before/after — never skipped silently.
+
+`<ui:history table="posts" key="{post.id}" datasource="db">` shows a row's
+history on any page.
+"""
+
+import contextvars
+import json
+import re
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+TABLE = 'quantum_history'
+
+CREATE_SQL = (f'CREATE TABLE IF NOT EXISTS {TABLE} ('
+              'id INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, user TEXT, action TEXT, '
+              'table_name TEXT NOT NULL, row_key TEXT, op TEXT NOT NULL, before TEXT, after TEXT, '
+              'sql TEXT)')
+
+_ACTION = contextvars.ContextVar('quantum_history_action', default=None)
+
+_WRITE = re.compile(r'^\s*(INSERT\s+(?:OR\s+\w+\s+)?INTO|UPDATE|DELETE\s+FROM)\s+"?(\w+)"?', re.I)
+_WHERE = re.compile(r'\bWHERE\b(.*)$', re.I | re.S)
+
+
+def enter(action: str, session_vars: Optional[dict]):
+    """Mark the writes that follow as made by this action, for this user."""
+    session = session_vars or {}
+    user = session.get('userName') or session.get('userId')
+    return _ACTION.set({'action': action, 'user': None if user is None else str(user)})
+
+
+def leave(token) -> None:
+    _ACTION.reset(token)
+
+
+def current() -> Optional[dict]:
+    return _ACTION.get()
+
+
+def parse_write(sql: str):
+    """(op, table, where) of a single-table write, or None when it is not one."""
+    m = _WRITE.match(sql)
+    if not m:
+        return None
+    op = {'INSERT': 'insert', 'UPDATE': 'update', 'DELETE': 'delete'}[m.group(1).split()[0].upper()]
+    where = _WHERE.search(sql)
+    return op, m.group(2), (where.group(1).strip().rstrip(';') if where else None)
+
+
+class Capture:
+    """One write being recorded: the rows before, then the rows after."""
+
+    def __init__(self, op: str, table: str, sql: str, key: Optional[str], before: List[dict], shaped: bool):
+        self.op, self.table, self.sql, self.key = op, table, sql, key
+        self.before, self.shaped = before, shaped
+
+
+def _rows(cursor) -> List[dict]:
+    columns = [d[0] for d in cursor.description or []]
+    return [dict(zip(columns, row)) for row in cursor.fetchall()]
+
+
+def _primary_key(conn, table: str) -> Optional[str]:
+    keys = [row[1] for row in conn.execute(f'PRAGMA table_info("{table}")') if row[5]]
+    return keys[0] if len(keys) == 1 else None
+
+
+def begin(conn, sql: str, params, prepare) -> Optional[Capture]:
+    """Before a write: which rows it will touch, as they are. None when nothing is recorded."""
+    state = current()
+    if state is None:
+        return None
+    shape = parse_write(sql)
+    if shape is None:
+        table = re.search(r'\b(?:INTO|UPDATE|FROM)\s+"?(\w+)"?', sql, re.I)
+        if not table or table.group(1) == TABLE:
+            return None
+        return Capture('write', table.group(1), sql, None, [], shaped=False)
+    op, table, where = shape
+    if table == TABLE:
+        return None
+    key = _primary_key(conn, table)
+    before: List[dict] = []
+    if op in ('update', 'delete'):
+        query, args = prepare(f'SELECT * FROM "{table}"' + (f' WHERE {where}' if where else ''), params)
+        cursor = conn.cursor()
+        cursor.execute(query, args)
+        before = _rows(cursor)
+        cursor.close()
+    return Capture(op, table, sql, key, before, shaped=True)
+
+
+def finish(conn, capture: Optional[Capture], last_row_id: Optional[int]) -> None:
+    """After the write, before the commit: record each row it changed."""
+    if capture is None:
+        return
+    state = current() or {}
+    conn.execute(CREATE_SQL)
+    records = []
+    if not capture.shaped:
+        records.append((None, None, None))
+    elif capture.op == 'insert':
+        row = None
+        if last_row_id:
+            cursor = conn.execute(f'SELECT * FROM "{capture.table}" WHERE rowid = ?', (last_row_id,))
+            found = _rows(cursor)
+            row = found[0] if found else None
+        key = row.get(capture.key) if (row and capture.key) else last_row_id
+        records.append((key, None, row))
+    else:
+        for before in capture.before:
+            key = before.get(capture.key) if capture.key else None
+            after = None
+            if capture.op == 'update' and capture.key:
+                cursor = conn.execute(f'SELECT * FROM "{capture.table}" WHERE "{capture.key}" = ?', (key,))
+                found = _rows(cursor)
+                after = found[0] if found else None
+            records.append((key, before, after))
+    now = datetime.now().isoformat(timespec='seconds')
+    for key, before, after in records:
+        conn.execute(
+            f'INSERT INTO {TABLE} (at, user, action, table_name, row_key, op, before, after, sql) '
+            'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+            (now, state.get('user'), state.get('action'), capture.table,
+             None if key is None else str(key), capture.op,
+             None if before is None else json.dumps(before, default=str, ensure_ascii=False),
+             None if after is None else json.dumps(after, default=str, ensure_ascii=False),
+             None if capture.shaped else capture.sql))
+
+
+def changes(before: Optional[dict], after: Optional[dict]) -> List[tuple]:
+    """(column, old, new) of what an update changed."""
+    if not before or not after:
+        return []
+    return [(c, before.get(c), after.get(c)) for c in after if before.get(c) != after.get(c)]
+
+
+def read(conn, table: str, key: Any, limit: int = 50) -> List[dict]:
+    """A row's history, newest first; empty when nothing was ever recorded."""
+    exists = conn.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (TABLE,)).fetchone()
+    if not exists:
+        return []
+    cursor = conn.execute(
+        f'SELECT at, user, action, op, before, after, sql FROM {TABLE} '
+        'WHERE table_name = ? AND row_key = ? ORDER BY id DESC LIMIT ?', (table, str(key), limit))
+    result = []
+    for at, user, action, op, before, after, sql in cursor.fetchall():
+        result.append({'at': at, 'user': user, 'action': action, 'op': op,
+                          'before': json.loads(before) if before else None,
+                          'after': json.loads(after) if after else None, 'sql': sql})
+    return result
+
+
+def entries_for(renderer, node) -> List[Dict[str, str]]:
+    """<ui:history>: the row's entries as text — when, who, action, change (web and console)."""
+    from pathlib import Path
+    from quantum.runtime.db_schema import SchemaError, connect_readonly
+    config = getattr(renderer, 'config', None) or {}
+    sources = config.get('datasources') or {}
+    if node.datasource not in sources:
+        raise ValueError(f'<ui:history datasource="{node.datasource}">: not declared in quantum.config.yaml')
+    if not sources[node.datasource].get('history'):
+        raise ValueError(f'<ui:history>: datasource "{node.datasource}" does not record history — '
+                         f'add `history: true` to it (DB-11)')
+    key = renderer._apply_databinding(node.key) if '{' in (node.key or '') else node.key
+    try:
+        conn = connect_readonly(sources[node.datasource], Path.cwd())
+    except SchemaError as exc:
+        raise ValueError(f'<ui:history>: {exc}') from exc
+    try:
+        entries = read(conn, node.table, key, node.limit)
+    finally:
+        conn.close()
+    lines = []
+    for entry in entries:
+        if entry['op'] == 'insert':
+            change = 'created'
+        elif entry['op'] == 'delete':
+            change = 'deleted'
+        elif entry['op'] == 'update':
+            change = '; '.join(f'{c}: {old} → {new}' for c, old, new in changes(entry['before'], entry['after']))                 or 'no change'
+        else:
+            change = entry.get('sql') or entry['op']
+        lines.append({'at': entry['at'].replace('T', ' '), 'user': entry['user'] or '—',
+                      'action': entry['action'] or '—', 'change': change})
+    return lines
+
+
+HEADERS = (('at', 'When'), ('user', 'Who'), ('action', 'Action'), ('change', 'Change'))
+