@giamme/forge 0.0.0-stage → 0.9.0

package/scripts/forge_dataset/capture.py

@@ -0,0 +1,330 @@
+"""Live capture: called from forge-runtime.py's begin()/finish() and from point events.
+
+Every function here is an entry point a running pipeline calls, so every one of them
+is fail-open: errors go to errors.log, nothing is printed (begin()'s stdout is the
+attempt path the shell captures), and nothing is raised.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from . import PROVENANCE, enabled, location_refused, log_error, provenance, put_blob, put_file, record
+from . import harvest as h
+
+
+def _environment() -> dict:
+    return dict(parent=os.environ.get('FORGE_DATASET_PARENT') or None,
+                inv=os.environ.get('FORGE_DATASET_INVOCATION') or None,
+                trigger=os.environ.get('FORGE_DATASET_TRIGGER') or None)
+
+
+def on_begin(attempt: str, root: str, role: str) -> None:
+    """Write the execution's provenance into its immutable attempt dir and a start receipt.
+
+    The provenance travels with the attempt dir, so a plan split or combined later (which
+    copies attempt dirs unchanged) still names the run the execution really belonged to.
+    """
+    if not enabled():
+        return
+    try:
+        attempt_dir, root_dir = Path(attempt), Path(root)
+        ctx = h.locate(root_dir, role)
+        if location_refused(ctx['repo']):
+            return
+        uid = h.run_uid(ctx['run_dir'], create=True)
+        env = _environment()
+        if role == 'task' and not env['trigger']:
+            env['trigger'] = 'initial'
+        # The code is fingerprinted here, when the execution starts: the prompt is built
+        # from it now, and finish() runs in another process that may see a later edit.
+        prov = dict(
+            schema=1, run=uid, run_id=ctx['run_id'], mode=ctx['mode'], scope=ctx['scope'],
+            plan=str(ctx['plan']) if ctx['plan'] else None, task=ctx['task'], repo=ctx['repo'],
+            link=ctx['link'], role=role, root=str(root_dir), wall_started_ns=time.time_ns(),
+            provenance=provenance(), **env,
+        )
+        if os.environ.get('FORGE_SHADOW') == '1':
+            # Carried in the attempt dir, so an import long after still knows what this was.
+            prov['shadow'] = dict(attempt=h.as_int(os.environ.get('FORGE_SHADOW_ATTEMPT')),
+                                  reviewed=os.environ.get('FORGE_SHADOW_REVIEWED') or None,
+                                  primary=os.environ.get('FORGE_SHADOW_FROM') or None)
+        if role in h.PIPELINE_ROLES:
+            prov['files'] = h.snapshot(root_dir)
+        if role == 'task':
+            prov['attempt_start'] = h.as_int(h.first_line(root_dir / 'attempt')) or 0
+            prov['resume'] = h.first_line(root_dir / 'resume') or None
+        h.write_json(attempt_dir / 'dataset.json', prov)
+        record([dict(rid=attempt_dir.name + ':start', kind='start', ts=time.time(), run=uid,
+                     run_id=ctx['run_id'], mode=ctx['mode'], task=ctx['task'], parent=env['parent'],
+                     inv=env['inv'], data=dict(role=role, root=str(root_dir), scope=ctx['scope'],
+                                               trigger=env['trigger'], link=ctx['link']))],
+               repo=ctx['repo'], where='begin')
+    except Exception as error:
+        log_error('begin', error)
+
+
+def provenance_for(attempt_dir: Path, root_dir: Path, role: str) -> dict:
+    """The provenance begin() wrote, or one reconstructed for an attempt dir without it."""
+    prov = h.read_json(attempt_dir / 'dataset.json')
+    if prov is None:
+        ctx = h.locate(root_dir, role)
+        prov = dict(run=h.run_uid(ctx['run_dir'], create=False), run_id=ctx['run_id'], mode=ctx['mode'],
+                    scope=ctx['scope'], plan=str(ctx['plan']) if ctx['plan'] else None, task=ctx['task'],
+                    repo=ctx['repo'], link=ctx['link'], files=None)
+    return prov
+
+
+def events_for(attempt_dir: Path, root_dir: Path, role: str, harness: str, rc, prov: dict, src: str) -> list:
+    if harness != 'pipeline':
+        if prov.get('shadow'):
+            prov['attempt_now'] = prov['shadow'].get('attempt')   # its dir has no attempt counter
+        elif prov.get('scope') == 'task':
+            prov['attempt_now'] = h.as_int(h.first_line(root_dir / 'attempt'))
+        return [h.dispatch_event(attempt_dir, root_dir, role, harness, rc, prov, src)]
+    if role == 'task':
+        return [h.task_event(attempt_dir, root_dir, rc, prov, src)]
+    if role == 'solo':
+        return [h.solo_event(attempt_dir, root_dir, rc, prov, src)]
+    if role == 'verification':
+        return h.verification_events(attempt_dir, root_dir, rc, prov, src)
+    if role == 'parallel':
+        return [h.run_end_event(attempt_dir, root_dir, rc, prov, src)]
+    return []
+
+
+def stamp(events: list, started: dict | None, check_change: bool = True) -> None:
+    """Attribute an execution's events to the code it started with.
+
+    A live edit between begin and finish would otherwise credit the outcome to code the
+    execution never ran; the change itself is kept, so a mixed execution can be dropped.
+    An import has no finish-time code to compare with, so it only keeps what begin saw.
+    """
+    if not started:
+        return
+    changed = check_change and started.get('code_sha') != provenance().get('code_sha')
+    for event in events:
+        for key in PROVENANCE:
+            event.setdefault(key, started.get(key))
+        if changed:
+            event.setdefault('data', {})['code_changed'] = True
+
+
+def on_finish(attempt: str, root: str, role: str, harness: str, rc) -> None:
+    if not enabled():
+        return
+    try:
+        attempt_dir, root_dir = Path(attempt), Path(root)
+        prov = provenance_for(attempt_dir, root_dir, role)
+        if location_refused(prov.get('repo')):
+            return
+        prov['wall_ended'] = time.time()
+        events = events_for(attempt_dir, root_dir, role, harness, rc, prov, 'live')
+        stamp(events, prov.get('provenance'))
+        record(events, repo=prov.get('repo'), where='finish')
+    except Exception as error:
+        log_error('finish', error)
+
+
+def point(name: str, directory: str | None, task: str | None = None, values: dict | None = None,
+          files: dict | None = None, kind: str = 'event', texts: dict | None = None,
+          repo: str | None = None) -> None:
+    """A fact that would be gone by the time any EXIT trap could read it.
+
+    Merge conflicts are aborted, combine rolls back, integrate removes its candidate
+    worktree; this records each one at the moment it is still on disk.
+    """
+    if not enabled():
+        return
+    try:
+        env = _environment()
+        ctx = h.locate(Path(directory)) if directory else dict(run_dir=None, run_id=None, mode=None, repo=None)
+        if location_refused(repo or ctx.get('repo')):
+            return
+        uid = h.run_uid(ctx['run_dir'], create=False) if ctx.get('run_dir') else None
+        data = dict(values or {}, name=name)
+        refs = {}
+        for label, path in (files or {}).items():
+            ref = put_file(path, 'diff' if path.endswith('.diff') else 'text')
+            if ref:
+                refs[label] = ref
+        for label, value in (texts or {}).items():
+            if value:
+                refs[label] = put_blob(value, 'log')
+        task = task or ctx.get('task')
+        data['blobs'] = refs
+        rid = 'event:%s:%s' % (name, h.sha256(json.dumps([uid, task, time.time_ns(), data], sort_keys=True,
+                                                         default=str).encode())[:24])
+        record([dict(rid=rid, kind=kind, ts=time.time(), run=uid, run_id=ctx.get('run_id'),
+                     mode=ctx.get('mode'), task=task, parent=env['parent'], inv=env['inv'], data=data)],
+               repo=repo or ctx.get('repo'), where='event:' + name)
+    except Exception as error:
+        log_error('event:' + name, error)
+
+
+def mint_run_uid(run_dir) -> None:
+    """Create the run dir's dataset uid now, if capture is on. Write-only, fail-open.
+
+    For decisions recorded before the run's own first capture would mint it (a plan's
+    predictions run inside `plan`): without it each would carry a legacy id that never
+    joins the attempts the plan goes on to run.
+    """
+    if not enabled():
+        return
+    try:
+        h.run_uid(Path(run_dir), create=True)
+    except Exception as error:
+        log_error('mint_run_uid', error)
+
+
+def jev(*, site, key, canonical: bytes, ok, reason, latency, model, usage, questions, answers,
+        run_dir, acting, shadow, extra=None) -> None:
+    """One Jev request: the full state and questions it judged, and what came back.
+
+    The request blob's original sha equals jev.jsonl's `key`, so a run dir that still
+    exists joins to it, and a judgment can later be replayed against any other model.
+    `extra` carries the provider, the occurrence id (a body asked twice is two
+    decisions), chunk hashes, and for plan-level sites the task they were about.
+    """
+    if not enabled():
+        return
+    try:
+        env = _environment()
+        ctx = h.locate(Path(run_dir)) if run_dir else dict(run_dir=None, run_id=None, mode=None, task=None, repo=None)
+        if location_refused(ctx.get('repo')):
+            return
+        uid = h.run_uid(ctx['run_dir'], create=False) if ctx.get('run_dir') else None
+        at = time.time()
+        rid = 'jev:' + h.sha256(('%s\0%r\0%d\0%d' % (key, at, os.getpid(), time.perf_counter_ns())).encode())[:24]
+        data = dict(site=site, key=key, ok=ok, reason=reason, latency_s=latency, model=model, usage=usage,
+                    questions=questions, answers=answers, acting=acting, shadow=shadow,
+                    run_dir=str(run_dir) if run_dir else None, blobs=dict(request=put_blob(canonical, 'request')))
+        data.update(extra or {})
+        record([dict(rid=rid, kind='jev', ts=at, run=uid, run_id=ctx.get('run_id'), mode=ctx.get('mode'),
+                     task=ctx.get('task') or (extra or {}).get('task'), parent=env['parent'], inv=env['inv'],
+                     data=data)],
+               repo=ctx.get('repo'), where='jev:' + site)
+    except Exception as error:
+        log_error('jev:' + str(site), error)
+
+
+def fractal_step(task_dir, node: dict, step_dir, *, phase: str, iteration, rc, cost, resolved) -> None:
+    """One Fractal step, keyed by its own step uuid.
+
+    node.json is mutable (a retry resets `iteration` to 0), so a step is recorded by
+    the uuid of the dir it ran in rather than by (node, iteration), which can repeat.
+    Called from worker threads: no signals, a connection per call.
+    """
+    if not enabled():
+        return
+    try:
+        task_dir, step_dir = Path(task_dir), Path(step_dir)
+        ctx = h.fractal_context(task_dir, create=True)
+        if location_refused(ctx['repo']):
+            return
+        record([h.fractal_step_event(task_dir, node, step_dir, ctx, phase=phase, iteration=iteration, rc=rc,
+                                     cost=cost, resolved=resolved)], repo=ctx['repo'], where='fractal_step')
+    except Exception as error:
+        log_error('fractal_step', error)
+
+
+def fractal_outcome(task_dir) -> None:
+    """Every node's final state and the task outcome, once per distinct state."""
+    if not enabled():
+        return
+    try:
+        task_dir = Path(task_dir)
+        ctx = h.fractal_context(task_dir, create=True)
+        if location_refused(ctx['repo']):
+            return
+        record(h.fractal_task_events(task_dir, ctx), repo=ctx['repo'], where='fractal_outcome')
+    except Exception as error:
+        log_error('fractal_outcome', error)
+
+
+def plan_snapshot(plan: str) -> None:
+    """Every routing, decomposition and scheduling decision made before the first dispatch."""
+    if not enabled():
+        return
+    try:
+        plan_dir = Path(plan)
+        if not (plan_dir / 'tasks.tsv').exists():
+            return
+        ctx = h.locate(plan_dir)
+        if location_refused(ctx['repo']):
+            return
+        prov = dict(run=h.run_uid(plan_dir, create=True), run_id=ctx['run_id'],
+                    inv=_environment()['inv'])
+        record([h.plan_event(plan_dir, prov)], repo=ctx['repo'], where='plan')
+    except Exception as error:
+        log_error('plan', error)
+
+
+def invocation(command: str, directory: str | None, rc, started: float | None, argv: list,
+               pid: str | None = None) -> None:
+    """One forge-parallel.sh subcommand: what was asked, how it ended, and what it left.
+
+    Artifacts a subcommand writes into a dir named after its own pid (final-review-*-PID,
+    integrate-*-PID) are read here, after they exist and before anything deletes them.
+    """
+    if not enabled():
+        return
+    try:
+        env = _environment()
+        plan = Path(directory) if directory and Path(directory).is_dir() else None
+        ctx = h.locate(plan) if plan else dict(run_dir=None, run_id=None, mode=None, repo=None)
+        if location_refused(ctx.get('repo')):
+            return
+        # `plan` is what makes a plan dir a run, so it may mint the id; every other command
+        # finds the one plan (or a dispatch's begin) already wrote.
+        uid = h.run_uid(plan, create=command == 'plan') if plan and (plan / 'tasks.tsv').exists() else None
+        data = dict(command=command, argv=argv, exit=h.as_int(rc), plan=str(plan) if plan else None,
+                    duration_s=round(time.time() - float(started), 3) if started else None)
+        refs = {}
+        if plan and pid:
+            produced = []
+            for path in sorted(plan.glob('*-%s' % pid)):
+                if not path.is_dir():
+                    continue
+                entry = dict(dir=path.name)
+                for name in ('verdict', 'verification.status', 'verification.exit', 'verification.command'):
+                    value = h.first_line(path / name)
+                    if value is not None:
+                        entry[name] = value
+                inner = path / 'final-review'
+                if inner.is_dir():
+                    entry['final_review_verdict'] = h.first_line(inner / 'verdict')
+                    entry['final_review_meta'] = h.kv(inner / 'review.meta') or None
+                if (path / 'review.meta').exists():
+                    entry['review_meta'] = h.kv(path / 'review.meta')
+                    ref = put_file(path / 'qa.last', 'message')
+                    if ref:
+                        refs['final_review_message'] = ref
+                    ref = put_file(path / 'combined.diff', 'diff')
+                    if ref:
+                        refs['final_review_diff'] = ref
+                produced.append(entry)
+            data['produced'] = produced
+            data['final_review_verdict'] = h.first_line(plan / 'final-review.verdict')
+        if command == 'accept' and plan and len(argv) > 0:
+            task = next((a for a in argv if not a.startswith('-') and (plan / 'tasks' / a).is_dir()), None)
+            if task:
+                data['task'] = task
+                data['accepted_by'] = h.text(plan / 'tasks' / task / 'accepted.by')
+                data['status_after'] = h.first_line(plan / 'tasks' / task / 'status')
+                ref = put_file(plan / 'tasks' / task / 'known_issues.md')
+                if ref:
+                    refs['known_issues'] = ref
+        if command == 'retry' and plan and len(argv) > 0:
+            data['task'] = next((a for a in argv if (plan / 'tasks' / a).is_dir()), None)
+        data['blobs'] = refs
+        record([dict(rid='invocation:%s' % (env['inv'] or h.sha256(repr((command, argv, started)).encode())[:24]),
+                     kind='invocation', ts=time.time(), run=uid, run_id=ctx.get('run_id'), mode=ctx.get('mode'),
+                     task=data.get('task'), inv=env['inv'], data=data)],
+               repo=ctx.get('repo'), where='invocation:' + command)
+        if command == 'plan' and plan:
+            plan_snapshot(str(plan))
+    except Exception as error:
+        log_error('invocation:' + command, error)

package/scripts/forge_dataset/checks.py

@@ -0,0 +1,109 @@
+"""Completeness checks for `forge dataset status`.
+
+Each check is specific to a mode, because each mode legitimately lacks different
+things: a solo run has no separate verification, and a final review's QA dispatch has
+no task attempt. A check reports what it expected and did not find. It never repairs
+anything, since the run dir that could fill the gap is usually gone.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from . import dataset_dir
+
+RUNNING_GRACE_S = 6 * 3600   # a start this recent may simply still be running
+
+
+def _events(db: sqlite3.Connection, where: str = '', params: tuple = ()) -> list[dict]:
+    cursor = db.execute('SELECT rid, kind, ts, src, run, mode, task, parent, data FROM events %s' % where, params)
+    names = [d[0] for d in cursor.description]
+    out = []
+    for row in cursor:
+        event = dict(zip(names, row))
+        event['data'] = json.loads(event['data'])
+        out.append(event)
+    return out
+
+
+def _refs(value) -> list[str]:
+    found = []
+    if isinstance(value, dict):
+        if set(value) >= {'sha', 'n', 'kept'} and isinstance(value.get('sha'), str):
+            found.append(value['sha'])
+        for item in value.values():
+            found.extend(_refs(item))
+    elif isinstance(value, list):
+        for item in value:
+            found.extend(_refs(item))
+    return found
+
+
+def run(db: sqlite3.Connection, verbose: bool = False) -> dict:
+    now = time.time()
+    events = _events(db)
+    by_rid = {e['rid'] for e in events}
+    results = {}
+
+    unfinished = [e for e in events if e['kind'] == 'start' and e['rid'][:-len(':start')] not in by_rid]
+    results['incomplete'] = dict(
+        what='executions that started but never recorded an end (killed, or still running)',
+        items=sorted(e['rid'][:-len(':start')] for e in unfinished if now - e['ts'] > RUNNING_GRACE_S),
+        running=sum(1 for e in unfinished if now - e['ts'] <= RUNNING_GRACE_S))
+
+    attempts = {e['rid'] for e in events if e['kind'] == 'attempt'}
+    orphan_qa = [e['rid'] for e in events if e['kind'] == 'dispatch' and e['data'].get('role') == 'qa'
+                 and e['data'].get('scope') == 'task' and e['src'] == 'live'
+                 and e.get('parent') and e['parent'] not in attempts and now - e['ts'] > RUNNING_GRACE_S]
+    results['qa_without_attempt'] = dict(what='task QA dispatches whose task attempt was never recorded',
+                                         items=sorted(orphan_qa))
+
+    ended = {e['run'] for e in events if e['kind'] == 'run_end'}
+    merges = {(e['run'], e['task']) for e in events if e['kind'] == 'event' and e['data'].get('name') == 'merge'}
+    unmerged = sorted('%s/%s' % (e['run'], e['task']) for e in events
+                      if e['kind'] == 'attempt' and e['mode'] == 'parallel' and e['src'] == 'live'
+                      and e['data'].get('status') == 'PASS' and e['run'] in ended
+                      and (e['run'], e['task']) not in merges)
+    results['pass_without_merge'] = dict(what='parallel PASS attempts with no merge outcome in a finished run',
+                                         items=unmerged)
+
+    last_seen = {}
+    for e in events:
+        if e['mode'] == 'parallel' and e['kind'] == 'attempt' and e['src'] == 'live':
+            last_seen[e['run']] = max(last_seen.get(e['run'], 0), e['ts'])
+    results['run_without_end'] = dict(what='parallel runs with task attempts but no run end',
+                                      items=sorted(r for r, ts in last_seen.items()
+                                                   if r not in ended and now - ts > RUNNING_GRACE_S))
+
+    blobs = dataset_dir() / 'blobs'
+    missing = sorted({sha for e in events for sha in _refs(e['data'])
+                      if not (blobs / sha[:2] / (sha + '.gz')).exists()})
+    results['missing_blobs'] = dict(what='blob references with no stored blob', items=missing)
+
+    if not verbose:
+        for check in results.values():
+            check['count'] = len(check['items'])
+            check['items'] = check['items'][:5]
+    else:
+        for check in results.values():
+            check['count'] = len(check['items'])
+    return results
+
+
+def report(results: dict) -> list[str]:
+    lines = []
+    problems = {name: c for name, c in results.items() if c['count']}
+    running = results.get('incomplete', {}).get('running')
+    if not problems:
+        lines.append('checks: complete' + (' (%d execution(s) still running)' % running if running else ''))
+        return lines
+    lines.append('checks: %d issue(s)' % sum(c['count'] for c in problems.values()))
+    for name, check in problems.items():
+        lines.append('  %s: %d — %s' % (name, check['count'], check['what']))
+        for item in check['items']:
+            lines.append('    %s' % item)
+        if check['count'] > len(check['items']):
+            lines.append('    … (--verbose lists all)')
+    return lines

package/scripts/forge_dataset/cli.py

@@ -0,0 +1,233 @@
+"""`forge dataset ...`: inspect the run dataset, import old runs, and the shell's capture hooks.
+
+User-facing: status, dump, import, export, outcomes. Internal (called by forge's shell scripts, fail-open,
+silent): event, invocation, plan.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from . import connect, data_home, dataset_dir, enabled, read_blob
+
+
+def _size(path: Path) -> int:
+    if path.is_file():
+        return path.stat().st_size
+    return sum(p.stat().st_size for p in path.rglob('*') if p.is_file()) if path.is_dir() else 0
+
+
+def _human(n: int) -> str:
+    for unit in ('B', 'KB', 'MB', 'GB'):
+        if n < 1024 or unit == 'GB':
+            return ('%d %s' % (n, unit)) if unit == 'B' else ('%.1f %s' % (n, unit))
+        n /= 1024.0
+    return str(n)
+
+
+def status(args) -> int:
+    from . import checks
+    directory = dataset_dir()
+    summary = dict(path=str(directory), enabled=enabled(), exists=(directory / 'dataset.sqlite').exists())
+    if summary['exists']:
+        db = connect()
+        try:
+            summary['events'] = dict(db.execute('SELECT kind, COUNT(*) FROM events GROUP BY kind ORDER BY kind'))
+            summary['by_source'] = dict(db.execute('SELECT src, COUNT(*) FROM events GROUP BY src'))
+            summary['repos'] = [dict(repo=r, path=p, origin=o) for r, p, o in
+                                db.execute('SELECT repo, path, origin FROM repos ORDER BY path')]
+            summary['runs'] = db.execute('SELECT COUNT(DISTINCT run) FROM events WHERE run IS NOT NULL').fetchone()[0]
+            last = db.execute('SELECT MAX(ts) FROM events').fetchone()[0]
+            summary['last_event'] = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(last)) if last else None
+            summary['checks'] = checks.run(db, verbose=args.verbose)
+            if summary['events'].get('dispatch'):
+                from . import export
+                if db.execute("SELECT 1 FROM events WHERE kind = 'dispatch' AND data LIKE '%qa_shadow%' LIMIT 1").fetchone():
+                    summary['shadow'] = export.agreement(export.Runs(export.Store(db)))
+        finally:
+            db.close()
+        summary['size'] = dict(database=_size(directory / 'dataset.sqlite') + _size(directory / 'dataset.sqlite-wal'),
+                               blobs=_size(directory / 'blobs'))
+    errors = directory / 'errors.log'
+    summary['errors'] = len(errors.read_text(errors='replace').splitlines()) if errors.exists() else 0
+    legacy = data_home() / 'legacy'
+    summary['legacy_archives'] = len(list(legacy.glob('*.tar.gz'))) if legacy.is_dir() else 0
+    if args.json:
+        print(json.dumps(summary, indent=2, sort_keys=True))
+        return 0
+    print('forge dataset: %s (%s)' % (summary['path'], 'capturing' if summary['enabled'] else 'off: FORGE_DATASET=off'))
+    if not summary['exists']:
+        print('  nothing captured yet')
+    else:
+        print('  size:   database %s, blobs %s' % (_human(summary['size']['database']), _human(summary['size']['blobs'])))
+        print('  events: %d in %d run(s) across %d repo(s); last %s'
+              % (sum(summary['events'].values()), summary['runs'], len(summary['repos']), summary['last_event']))
+        print('          ' + ', '.join('%s %d' % kv for kv in summary['events'].items()))
+        if summary['by_source'].get('import'):
+            print('          %d imported from old run dirs' % summary['by_source']['import'])
+        for line in checks.report(summary['checks']):
+            print('  ' + line)
+        shadow = summary.get('shadow')
+        if shadow:
+            rate = ' (%.0f%% agree)' % (100.0 * shadow['agree'] / shadow['pairs']) if shadow['pairs'] else ''
+            print('  shadow: %d second review(s), %d usable pair(s), %d agree%s'
+                  % (shadow['shadow_reviews'], shadow['pairs'], shadow['agree'], rate))
+            for pair, n in shadow['by_pair'].items():
+                print('          %s: %d of %d agree' % (pair, n['agree'], n['pairs']))
+    if summary['legacy_archives']:
+        print('  legacy: %d archived run dir(s) kept in %s (`forge dataset import %s` re-reads them;'
+              ' events already stored are skipped)' % (summary['legacy_archives'], legacy, legacy))
+    if summary['errors']:
+        print('  errors: %d capture failure(s) logged in %s' % (summary['errors'], errors))
+    return 0
+
+
+def dump(args) -> int:
+    if not (dataset_dir() / 'dataset.sqlite').exists():
+        return 0
+    db = connect()
+    try:
+        where, params = [], []
+        for column in ('kind', 'run', 'repo', 'task', 'src'):
+            value = getattr(args, column)
+            if value:
+                where.append('%s = ?' % column)
+                params.append(value)
+        if args.since:
+            where.append('ts >= ?')
+            params.append(args.since)
+        query = 'SELECT * FROM events%s ORDER BY ts, rid' % (' WHERE ' + ' AND '.join(where) if where else '')
+        cursor = db.execute(query, params)
+        names = [d[0] for d in cursor.description]
+        for row in cursor:
+            event = dict(zip(names, row))
+            event['data'] = json.loads(event['data'])
+            print(json.dumps(event, sort_keys=True))
+    finally:
+        db.close()
+    return 0
+
+
+def blob(args) -> int:
+    sys.stdout.buffer.write(read_blob(args.sha))
+    return 0
+
+
+def _pairs(items: list | None) -> dict:
+    out = {}
+    for item in items or []:
+        key, _, value = item.partition('=')
+        if key:
+            out[key] = value
+    return out
+
+
+def event(args) -> int:
+    from .capture import point
+    point(args.name, args.dir, args.task, _pairs(args.set), _pairs(args.file), repo=args.repo)
+    return 0
+
+
+def invocation(args) -> int:
+    from .capture import invocation as record_invocation
+    record_invocation(args.command, args.dir, args.rc, args.started, args.argv, args.pid)
+    return 0
+
+
+def plan(args) -> int:
+    from .capture import plan_snapshot
+    plan_snapshot(args.dir)
+    return 0
+
+
+def run_import(args) -> int:
+    from . import importer
+    return importer.main(args)
+
+
+def run_export(args) -> int:
+    from . import export
+    return export.main(args)
+
+
+def run_outcomes(args) -> int:
+    from . import outcomes
+    return outcomes.main(args)
+
+
+def run_routing(args) -> int:
+    from . import routing
+    return routing.main(args)
+
+
+def parser() -> argparse.ArgumentParser:
+    top = argparse.ArgumentParser(prog='forge dataset', description='The run dataset: every run\'s inputs and outcomes.')
+    sub = top.add_subparsers(dest='command', required=True)
+    p = sub.add_parser('status', help='where the dataset is, what it holds, and what looks incomplete')
+    p.add_argument('--json', action='store_true')
+    p.add_argument('--verbose', '-v', action='store_true', help='list every incomplete item, not just counts')
+    p.set_defaults(func=status)
+    p = sub.add_parser('dump', help='events as JSON lines')
+    for column in ('kind', 'run', 'repo', 'task', 'src'):
+        p.add_argument('--' + column)
+    p.add_argument('--since', type=float, help='unix time')
+    p.set_defaults(func=dump)
+    p = sub.add_parser('blob', help='print a stored blob by its sha')
+    p.add_argument('sha')
+    p.set_defaults(func=blob)
+    p = sub.add_parser('import', help='capture run dirs, archives and ledgers that predate live capture')
+    p.add_argument('paths', nargs='*', help='run/plan dirs, dirs to scan, or .tar.gz archives')
+    p.add_argument('--registry', action='store_true', help='every run dir listed in the Jev runs registry')
+    p.add_argument('--fractal', action='store_true', help='the Fractal state dir')
+    p.add_argument('--ledger', action='append', default=[], metavar='REPO', help="a repo's .forge/ledger.tsv")
+    p.add_argument('--include-temp', action='store_true', help='also import runs whose repo is a temp dir (test runs)')
+    p.add_argument('--dry-run', action='store_true')
+    p.set_defaults(func=run_import)
+    p = sub.add_parser('export', help='labeled decision cases (System One JSONL) derived from outcomes')
+    p.add_argument('--out', help='output dir (default: <data>/exports/forge-decisions)')
+    p.add_argument('--slice', dest='slices', action='append', choices=('routing', 'retry', 'review', 'drift', 'citation', 'memory'),
+                   help='only this slice; repeatable (default: all)')
+    p.add_argument('--limit', type=int, help='at most this many cases per slice, spread across runs')
+    p.add_argument('--seed', type=int, default=7)
+    p.set_defaults(func=run_export)
+    p = sub.add_parser('outcomes', help='what happened to integrated work afterwards (read-only git)')
+    p.add_argument('--horizon-days', type=int, default=14, help='how long after integrate to look (default 14)')
+    p.add_argument('--repo', help='only this repo')
+    p.add_argument('--include-temp', action='store_true', help='also repos under temp dirs (test runs)')
+    p.add_argument('--dry-run', action='store_true', help='report what would be recorded, write nothing')
+    p.set_defaults(func=run_outcomes)
+    p = sub.add_parser('routing', help='pass rate and runtime per tier and model, and what the --explore draws say')
+    p.add_argument('--repo', help='only this repo')
+    p.add_argument('--since', type=float, metavar='DAYS', help='only tasks first attempted in the last DAYS days')
+    p.add_argument('--json', action='store_true')
+    p.set_defaults(func=run_routing)
+    p = sub.add_parser('event', help=argparse.SUPPRESS)
+    p.add_argument('name')
+    p.add_argument('--dir')
+    p.add_argument('--task')
+    p.add_argument('--repo')
+    p.add_argument('--set', action='append')
+    p.add_argument('--file', action='append')
+    p.set_defaults(func=event)
+    p = sub.add_parser('invocation', help=argparse.SUPPRESS)
+    p.add_argument('command')
+    p.add_argument('--dir')
+    p.add_argument('--rc')
+    p.add_argument('--started')
+    p.add_argument('--pid')
+    p.add_argument('argv', nargs=argparse.REMAINDER)
+    p.set_defaults(func=invocation)
+    p = sub.add_parser('plan', help=argparse.SUPPRESS)
+    p.add_argument('dir')
+    p.set_defaults(func=plan)
+    return top
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    if getattr(args, 'argv', None) and args.argv[:1] == ['--']:
+        args.argv = args.argv[1:]
+    return args.func(args)