stepledger 0.1.0__py3-none-any.whl

stepledger/__init__.py

@@ -0,0 +1,25 @@
+"""Stepledger: a fenced, committed Postgres ledger for LangGraph nodes on Temporal."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = ["JournaledChatModel", "StepledgerPlugin", "__version__", "materialize", "once"]
+
+_LAZY = {
+    "StepledgerPlugin": ("stepledger.plugin", "StepledgerPlugin"),
+    "once": ("stepledger.effects.once", "once"),
+    "materialize": ("stepledger.read.materialize", "materialize"),
+    "JournaledChatModel": ("stepledger.llm.journal", "JournaledChatModel"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        import importlib
+
+        module, attr = _LAZY[name]
+        return getattr(importlib.import_module(module), attr)
+    raise AttributeError(f"module 'stepledger' has no attribute {name!r}")

stepledger/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m stepledger` runs the CLI."""
+
+from stepledger.cli import app
+
+app()

stepledger/_compat.py

@@ -0,0 +1,49 @@
+"""Every private Temporal SDK or LangGraph symbol Stepledger uses, in one place (Hard Rule 5, D2).
+
+Pinned against temporalio 1.33.x and langgraph 1.2.x. tests/unit/test_compat.py fails loudly if
+an upgrade moves or changes any of them. Nothing else in the package imports a private module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import temporalio.activity
+from langgraph._internal._typing import MISSING  # sentinel for channel.from_checkpoint
+from langgraph.pregel._algo import task_path_str  # LangGraph's sortable task-path string
+from temporalio.contrib.langgraph._activity import (  # the plugin's node Activity I/O
+    ActivityInput,
+    ActivityOutput,
+)
+from temporalio.contrib.langgraph._task_cache import get_task_cache as _get_task_cache
+
+__all__ = [
+    "MISSING",
+    "ActivityInput",
+    "ActivityOutput",
+    "activity_name",
+    "langgraph_used_in_this_run",
+    "plugin_activity_names",
+    "task_path_str",
+]
+
+
+def activity_name(fn: Callable[..., Any]) -> str:
+    """The registered name of an @activity.defn function."""
+    name = temporalio.activity._Definition.must_from_callable(fn).name
+    if name is None:
+        raise ValueError(f"{fn!r} is a dynamic activity; it has no fixed name to track")
+    return name
+
+
+def plugin_activity_names(langgraph_plugin: Any) -> frozenset[str]:
+    """Names of every Activity a LangGraphPlugin registered (its node and task Activities)."""
+    return frozenset(activity_name(a) for a in langgraph_plugin.activities)
+
+
+def langgraph_used_in_this_run() -> bool:
+    """True inside workflow code once graph() / entrypoint() ran: both install the plugin's task
+    cache (a context variable), even when every node is then served from it and no Activity is
+    scheduled. Pure in-memory state, so safe to read from the deterministic workflow side."""
+    return _get_task_cache() is not None

stepledger/_hooks.py

@@ -0,0 +1,22 @@
+"""Fault-injection hook points inside Stepledger's own commit path (F3, F4, F5).
+
+A no-op unless `stepledger.testing.faults.install()` registers an injector, which only chaos
+workers do. Production code never imports stepledger.testing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+Injector = Callable[..., Awaitable[None]]
+_injector: Injector | None = None
+
+
+def set_injector(fn: Injector | None) -> None:
+    global _injector
+    _injector = fn
+
+
+async def fault(point: str, **where: object) -> None:
+    if _injector is not None:
+        await _injector(point, **where)

stepledger/canonical.py

@@ -0,0 +1,53 @@
+"""Canonical JSON and content hashes, used only for hashing and equality.
+
+Values are first turned into plain JSON by the worker's own payload converter, so a hash here
+equals the hash of what Temporal recorded for the same value.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from temporalio.api.common.v1 import Payload
+from temporalio.converter import PayloadConverter
+
+JSON_PLAIN = b"json/plain"
+
+
+def canonical_json(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def chash(obj: Any) -> str:
+    """sha256 hex of the canonical JSON of a plain-JSON value."""
+    return hashlib.sha256(canonical_json(obj).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class Serialized:
+    """A value as the payload converter serialized it."""
+
+    encoding: str
+    data: bytes
+    plain: Any  # the decoded JSON value when encoding is json/plain, else None
+    is_json: bool
+
+    @property
+    def hash(self) -> str:
+        if self.is_json:
+            return chash(self.plain)
+        return hashlib.sha256(self.data).hexdigest()
+
+
+def serialize(value: Any, converter: PayloadConverter) -> Serialized:
+    return from_payload(converter.to_payload(value))
+
+
+def from_payload(payload: Payload) -> Serialized:
+    encoding = payload.metadata.get("encoding", b"").decode()
+    if encoding == JSON_PLAIN.decode():
+        return Serialized(encoding, payload.data, json.loads(payload.data), True)
+    return Serialized(encoding, payload.data, None, False)

stepledger/cli.py

@@ -0,0 +1,261 @@
+"""The `stepledger` command line."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from stepledger import __version__
+from stepledger.config import resolve_dsn
+
+app = typer.Typer(
+    name="stepledger",
+    help="Stepledger: a fenced, committed Postgres ledger for LangGraph nodes on Temporal.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"stepledger {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Print the version and exit."
+    ),
+) -> None:
+    """Stepledger command line."""
+
+
+DsnOption = typer.Option(None, "--dsn", envvar="STEPLEDGER_DSN", help="Postgres DSN.")
+
+
+@app.command("init-db")
+def init_db_cmd(dsn: str | None = DsnOption) -> None:
+    """Create the Stepledger tables and views. Safe to run repeatedly."""
+    from stepledger.ledger.store import init_db
+
+    init_db(resolve_dsn(dsn))
+    typer.echo("stepledger schema applied")
+
+
+AddressOption = typer.Option("localhost:7233", "--address", envvar="TEMPORAL_ADDRESS")
+NamespaceOption = typer.Option("default", "--namespace", "-n", envvar="TEMPORAL_NAMESPACE")
+
+
+def _run(coro: Any) -> Any:
+    import asyncio
+
+    return asyncio.run(coro)
+
+
+@app.command("reconcile")
+def reconcile_cmd(
+    workflow_id: str | None = typer.Argument(None, help="Reconcile every run of this workflow."),
+    all_open: bool = typer.Option(False, "--all-open", help="Every run the ledger has not sealed."),
+    dsn: str | None = DsnOption,
+    address: str = AddressOption,
+    namespace: str = NamespaceOption,
+) -> None:
+    """Repair the ledger from Temporal's history (terminations, timeouts, degraded runs)."""
+    if not workflow_id and not all_open:
+        raise typer.BadParameter("give a workflow id or --all-open")
+
+    async def go() -> None:
+        from temporalio.client import Client
+
+        from stepledger.ledger.reconcile import reconcile
+        from stepledger.ledger.store import LedgerStore
+
+        client = await Client.connect(address, namespace=namespace)
+        store = LedgerStore(resolve_dsn(dsn))
+        try:
+            reports = await reconcile(client, store, workflow_id, all_open=all_open)
+        finally:
+            await store.close()
+        if not reports:
+            typer.echo("nothing to reconcile")
+        for r in reports:
+            typer.echo(
+                f"{r.workflow_id} {r.run_id} {r.run_status}: {r.action}"
+                f" committed={r.committed} abandoned={r.abandoned} inserted={r.inserted}"
+                f" divergence_repaired={r.divergence_repaired}"
+            )
+
+    _run(go())
+
+
+@app.command("resolve")
+def resolve_cmd(
+    key: str = typer.Argument(..., help="The effect key from the UnknownEffectOutcome error."),
+    outcome: str = typer.Option(..., "--outcome", help="done | not-done"),
+    result: str | None = typer.Option(None, "--result", help="JSON result when done."),
+    dsn: str | None = DsnOption,
+) -> None:
+    """Record a human's verdict on an effect whose outcome is unknown."""
+    import json
+
+    async def go() -> None:
+        from stepledger.effects.once import resolve
+        from stepledger.ledger.store import LedgerStore
+
+        store = LedgerStore(resolve_dsn(dsn))
+        try:
+            state = await resolve(store, key, outcome, json.loads(result) if result else None)
+        finally:
+            await store.close()
+        typer.echo(f"{key}: {state}")
+
+    _run(go())
+
+
+@app.command("ledger")
+def ledger_cmd(
+    workflow_id: str = typer.Argument(...),
+    run_id: str | None = typer.Option(None, "--run-id"),
+    dsn: str | None = DsnOption,
+) -> None:
+    """Print the run ledger: one line per node execution, with attempts, effects and waste."""
+    from stepledger.read.ledger import run_ledger
+
+    typer.echo(run_ledger(resolve_dsn(dsn), workflow_id, run_id))
+
+
+@app.command("status")
+def status_cmd(
+    limit: int = typer.Option(20, "--limit"),
+    dsn: str | None = DsnOption,
+) -> None:
+    """Recent runs in the ledger."""
+    import psycopg
+
+    with psycopg.connect(resolve_dsn(dsn)) as conn:
+        rows = conn.execute(
+            "SELECT workflow_id, left(run_id, 12), status, sealed_at IS NOT NULL, committed_count,"
+            " abandoned_count, degraded FROM sl_runs ORDER BY first_seen_at DESC LIMIT %s",
+            (limit,),
+        ).fetchall()
+    typer.echo(f"{'workflow_id':<36} {'run':<13} {'status':<17} sealed  committed abandoned")
+    for wf, run, status, sealed, c, a, degraded in rows:
+        flag = "  DEGRADED" if degraded else ""
+        typer.echo(
+            f"{wf:<36} {run:<13} {status:<17} {'yes' if sealed else 'no ':<6} {c or 0:>9}"
+            f" {a or 0:>9}{flag}"
+        )
+
+
+@app.command("gc")
+def gc_cmd(
+    execute: bool = typer.Option(False, "--execute", help="Delete for real (default: dry run)."),
+    retention_days: float | None = typer.Option(None, "--retention-days"),
+    margin_days: float | None = typer.Option(None, "--margin-days"),
+    grace_hours: float | None = typer.Option(None, "--grace-hours"),
+    orphan_ref_days: float | None = typer.Option(None, "--orphan-ref-days"),
+    dsn: str | None = DsnOption,
+    address: str = AddressOption,
+    namespace: str = NamespaceOption,
+) -> None:
+    """Mark and sweep the dedup store. Dry run unless --execute."""
+    from datetime import timedelta
+
+    from stepledger.config import load_settings
+
+    cfg = load_settings().gc
+    retention = timedelta(days=retention_days if retention_days is not None else cfg.retention_days)
+    margin = timedelta(days=margin_days if margin_days is not None else cfg.margin_days)
+    grace = timedelta(hours=grace_hours if grace_hours is not None else cfg.grace_hours)
+    orphan = timedelta(days=orphan_ref_days if orphan_ref_days is not None else cfg.orphan_ref_days)
+
+    async def go() -> None:
+        from temporalio.client import Client
+
+        from stepledger.storage.gc import check_retention, namespace_retention, summary, sweep
+
+        client = await Client.connect(address, namespace=namespace)
+        problem = check_retention(retention, await namespace_retention(client))
+        if problem:
+            typer.echo(f"refusing to run: {problem}", err=True)
+            raise typer.Exit(2)
+        report = await sweep(
+            client,
+            resolve_dsn(dsn),
+            retention=retention,
+            margin=margin,
+            grace=grace,
+            orphan_ref_age=orphan,
+            dry_run=not execute,
+        )
+        for k, v in summary(report).items():
+            if k != "details":
+                typer.echo(f"{k}: {v}")
+
+    _run(go())
+
+
+@app.command("materialize")
+def materialize_cmd(
+    workflow_id: str = typer.Argument(...),
+    graph: str = typer.Option(
+        ..., "--graph", help="module:attr of a StateGraph, a compiled graph, or a factory for one"
+    ),
+    run_id: str | None = typer.Option(None, "--run-id"),
+    chain: bool = typer.Option(False, "--chain", help="Fill task-cache gaps from earlier runs."),
+    include_provisional: bool = typer.Option(False, "--include-provisional"),
+    show_state: bool = typer.Option(False, "--state", help="Print the rebuilt state as JSON."),
+    dsn: str | None = DsnOption,
+) -> None:
+    """Rebuild a run's graph state from the ledger and say whether it is EXACT."""
+    import importlib
+    import json
+    import os
+    import sys
+
+    from stepledger.read.materialize import materialize
+
+    if os.getcwd() not in sys.path:  # like uvicorn: --graph resolves from the working directory
+        sys.path.insert(0, os.getcwd())
+    module, _, attr = graph.partition(":")
+    obj: Any = getattr(importlib.import_module(module), attr)
+    if callable(obj) and not hasattr(obj, "compile") and not hasattr(obj, "channels"):
+        obj = obj()
+    compiled = obj.compile() if hasattr(obj, "compile") else obj
+    result = _run(
+        materialize(
+            resolve_dsn(dsn),
+            compiled,
+            workflow_id,
+            run_id,
+            include_provisional=include_provisional,
+            chain=chain,
+        )
+    )
+    typer.echo(f"{result.completeness}: {result.reason}")
+    typer.echo(f"rows used: {result.rows_used}  chain rows used: {result.chain_rows_used}")
+    for p in result.positions:
+        typer.echo(f"  gap: {p}")
+    if show_state:
+        typer.echo(json.dumps(result.state, indent=1, default=str))
+
+
+@app.command("bench")
+def bench_cmd(
+    demo: str = typer.Argument(..., help="cliff | chaos | growth | materialize | cost"),
+) -> None:
+    """Run a demo from a repository checkout (the bench is not part of the wheel)."""
+    import subprocess
+    import sys
+    from pathlib import Path
+
+    if not Path("bench/demo.py").is_file():
+        typer.echo("run this from a stepledger repository checkout (bench/ is not installed)")
+        raise typer.Exit(2)
+    raise typer.Exit(subprocess.call([sys.executable, "bench/demo.py", "--demo", demo]))
+
+
+if __name__ == "__main__":
+    app()

stepledger/config.py

@@ -0,0 +1,108 @@
+"""Configuration: `stepledger.yaml`, then environment variables (`STEPLEDGER_DSN`, ...)."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+DEFAULT_DSN = "postgresql://stepledger:stepledger@localhost:5432/stepledger"
+SCHEMA_VERSION = 1
+
+_ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class LedgerConfig(BaseModel):
+    store_outputs: Literal["full", "hash_only"] = "full"
+    on_ledger_error: Literal["fail", "warn"] = "fail"
+    snapshot_first_input: bool = True
+
+
+class ChunkConfig(BaseModel):
+    min: int = 4096
+    avg: int = 16384
+    max: int = 65536
+
+
+class StorageConfig(BaseModel):
+    enabled: bool = True
+    payload_size_threshold: int = 64 * 1024
+    dedupe: bool = True
+    chunk: ChunkConfig = Field(default_factory=ChunkConfig)
+
+
+class GcConfig(BaseModel):
+    retention_days: int = 30
+    margin_days: int = 7
+    grace_hours: float = 1.0
+    orphan_ref_days: int = 90
+
+
+class Price(BaseModel):
+    input: float
+    output: float
+
+
+def _default_prices() -> dict[str, Price]:
+    # USD per 1M tokens, Anthropic first-party API rates as published at
+    # https://platform.claude.com/docs/en/about-claude/pricing (checked 2026-09-26).
+    # Prices change: set `prices:` in stepledger.yaml for the models you actually use.
+    return {
+        "claude-haiku-4-5": Price(input=1.0, output=5.0),
+        "claude-sonnet-5": Price(input=2.0, output=10.0),
+    }
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="STEPLEDGER_", env_nested_delimiter="__", extra="ignore"
+    )
+
+    schema_version: int = SCHEMA_VERSION
+    dsn: str = DEFAULT_DSN
+    ledger: LedgerConfig = Field(default_factory=LedgerConfig)
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    gc: GcConfig = Field(default_factory=GcConfig)
+    prices: dict[str, Price] = Field(default_factory=_default_prices)
+
+
+def _expand(value: Any) -> Any:
+    if isinstance(value, str):
+        return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand(v) for v in value]
+    return value
+
+
+def load_settings(path: str | Path | None = None) -> Settings:
+    """Load `stepledger.yaml` (or `$STEPLEDGER_CONFIG`), then let environment variables win."""
+    candidate = Path(path or os.environ.get("STEPLEDGER_CONFIG", "stepledger.yaml"))
+    file_values: dict[str, Any] = {}
+    if candidate.is_file():
+        loaded = yaml.safe_load(candidate.read_text()) or {}
+        if not isinstance(loaded, dict):
+            raise ValueError(f"{candidate}: expected a mapping at the top level")
+        file_values = _expand(loaded)
+        version = file_values.get("schema_version", SCHEMA_VERSION)
+        if version != SCHEMA_VERSION:
+            raise ValueError(f"{candidate}: schema_version {version} != {SCHEMA_VERSION}")
+        if not file_values.get("dsn"):
+            file_values.pop("dsn", None)
+    env = Settings()
+    merged = Settings.model_validate(file_values).model_dump()
+    # Environment variables override the file, field by field.
+    for name in Settings.model_fields:
+        if env.model_fields_set and name in env.model_fields_set:
+            merged[name] = env.model_dump()[name]
+    return Settings.model_validate(merged)
+
+
+def resolve_dsn(dsn: str | None = None) -> str:
+    return dsn or load_settings().dsn

stepledger/effects/__init__.py

@@ -0,0 +1 @@
+"""External side effects with a stable idempotency key and a journal: once()."""

stepledger/effects/once.py

@@ -0,0 +1,159 @@
+"""once(): at-least-once external effects with dedupe, never silently repeated.
+
+    ticket = await once("open_ticket", lambda key: jira.create(req, idempotency_key=key),
+                        request=req)
+
+Inside a tracked node Activity, the key is sha256(namespace, workflow, run, seq, name, idx), where
+idx counts once() calls with this name in this node execution, so it is stable across retries
+of the node. `fn` receives the key so the tool can pass it upstream as its own idempotency key.
+
+    no journal row      -> record STARTED, call fn(key), record DONE with the result
+    DONE, same request  -> return the recorded result (a duplicate prevented, counted)
+    other request       -> EffectDivergence (non-retryable)
+    STARTED / UNKNOWN   -> the outcome is unknown: ask `reconcile(key)`. It returns the effect's
+                           result if the tool shows it happened, NOT_DONE if the tool shows it did
+                           not (then fn is called again), or None if it cannot tell: then mark
+                           UNKNOWN and raise UnknownEffectOutcome, which waits (retrying slowly)
+                           for `stepledger resolve <key> --outcome done|not-done`
+    RESOLVED not-done   -> the effect did not happen: claim it again and call fn(key)
+
+Results are stored as JSON, so fn must return a JSON-serializable value. This is at-least-once
+delivery with dedupe, not exactly-once: an effect whose tool ignores the key can repeat if the
+worker dies between the call and the DONE write, which is why that case stops for a human.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from datetime import timedelta
+from typing import Any, TypeVar
+
+from psycopg.types.json import Jsonb
+
+from stepledger._hooks import fault
+from stepledger.canonical import chash
+from stepledger.errors import EffectDivergence, NotInTrackedNode, UnknownEffectOutcome
+from stepledger.ledger.context import current_node
+
+T = TypeVar("T")
+
+
+class _NotDone:
+    def __repr__(self) -> str:
+        return "NOT_DONE"
+
+
+NOT_DONE: Any = _NotDone()
+"""Returned by a reconcile callback when the tool shows the effect did not happen."""
+
+UNKNOWN_RETRY_DELAY = timedelta(seconds=30)
+
+
+async def once(
+    name: str,
+    fn: Callable[[str], Awaitable[T]],
+    *,
+    request: Any,
+    reconcile: Callable[[str], Awaitable[T | None]] | None = None,
+) -> T:
+    node = current_node()
+    if node is None:
+        raise NotInTrackedNode("once() must be called inside a node Activity tracked by Stepledger")
+    idx = node.next_effect_idx(name)
+    key = node.key.effect_key(name, idx)
+    request_hash = chash(request)
+    k = node.key
+
+    async with node.store.tx() as tx:
+        cur = await tx.conn.execute(
+            "SELECT status, request_hash, result, resolution FROM sl_effects WHERE key = %s"
+            " FOR UPDATE",
+            (key,),
+        )
+        row = await cur.fetchone()
+        if row is None:
+            await tx.conn.execute(
+                "INSERT INTO sl_effects (key, namespace, workflow_id, run_id, seq, name, idx,"
+                " request_hash, status) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, 'STARTED')",
+                (key, k.namespace, k.workflow_id, k.run_id, k.seq, name, idx, request_hash),
+            )
+            claimed = True
+        else:
+            status, stored_hash, result, resolution = row
+            if stored_hash != request_hash:
+                raise EffectDivergence(key, name)
+            if status == "DONE":
+                await tx.conn.execute(
+                    "UPDATE sl_effects SET duplicates_prevented = duplicates_prevented + 1,"
+                    " attempts = attempts + 1 WHERE key = %s",
+                    (key,),
+                )
+                return result  # type: ignore[no-any-return]
+            if status == "RESOLVED" and resolution == "not-done":
+                await tx.conn.execute(
+                    "UPDATE sl_effects SET status = 'STARTED', attempts = attempts + 1,"
+                    " resolution = NULL WHERE key = %s",
+                    (key,),
+                )
+                claimed = True
+            else:
+                claimed = False  # STARTED or UNKNOWN: an earlier attempt's outcome is unknown
+
+    if claimed:
+        result = await fn(key)
+        await fault("FE", effect=name)  # chaos only: a crash between the call and its record
+        await _done(node.store, key, result)
+        return result
+
+    if reconcile is not None:
+        found = await reconcile(key)
+        if found is NOT_DONE:
+            result = await fn(key)
+            await _done(node.store, key, result, resolution="reconciled:not-done")
+            return result
+        if found is not None:
+            await _done(node.store, key, found, resolution="reconciled:done")
+            return found
+    async with node.store.tx() as tx:
+        await tx.conn.execute(
+            "UPDATE sl_effects SET status = 'UNKNOWN', attempts = attempts + 1 WHERE key = %s"
+            " AND status IN ('STARTED', 'UNKNOWN')",
+            (key,),
+        )
+    raise UnknownEffectOutcome(key, name, next_retry_delay=UNKNOWN_RETRY_DELAY)
+
+
+async def _done(store: Any, key: str, result: Any, resolution: str | None = None) -> None:
+    async with store.tx() as tx:
+        await tx.conn.execute(
+            "UPDATE sl_effects SET status = 'DONE', result = %s, done_at = now(),"
+            " resolution = coalesce(%s, resolution) WHERE key = %s",
+            (Jsonb(result), resolution, key),
+        )
+
+
+async def resolve(store: Any, key: str, outcome: str, result: Any = None) -> str:
+    """Record a human's verdict on an effect with an unknown outcome."""
+    if outcome not in ("done", "not-done"):
+        raise ValueError("outcome must be 'done' or 'not-done'")
+    async with store.tx() as tx:
+        cur = await tx.conn.execute(
+            "SELECT status FROM sl_effects WHERE key = %s FOR UPDATE", (key,)
+        )
+        row = await cur.fetchone()
+        if row is None:
+            raise KeyError(f"no effect with key {key}")
+        if row[0] == "DONE":
+            return "already DONE"
+        if outcome == "done":
+            await tx.conn.execute(
+                "UPDATE sl_effects SET status = 'DONE', result = %s, done_at = now(),"
+                " resolution = 'manual:done' WHERE key = %s",
+                (Jsonb(result), key),
+            )
+            return "DONE"
+        await tx.conn.execute(
+            "UPDATE sl_effects SET status = 'RESOLVED', resolution = 'not-done' WHERE key = %s",
+            (key,),
+        )
+        return "RESOLVED not-done"