stasima 0.1.4__py3-none-any.whl

stasima/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Stasima — a server letting multiple AI instances share one durable, version-controlled
+body of knowledge, with a human practitioner as the gate to shared truth."""
+__version__ = "0.1.4"

stasima/admin.py

@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Admin CLI — practitioner-side maintenance + promotion. NOT model-facing: these are operator ops,
+and `land` (promotion to canon) IS the human gate, performed here out of band.
+
+    stasima-admin --config stasima.toml <command>
+
+      bootstrap <dir>     seed an EMPTY canon from a folder of .md entries (one-time)
+      totp-provision      generate the airlock TOTP secret (prints the otpauth:// URI)
+      totp-check <code>   verify a code from your app (consumes nothing; diagnoses clock skew)
+      inbox [--all] [--read PATH]   the practitioner's mail, from the cockpit (pull)
+      backup <dest>       full LOCAL backup of everything that is truth: git mirror (all refs+tags),
+                          consistent audit snapshot, config, TOTP secret. For a same-trust machine
+                          move — carries the secret. Run it anywhere: synced folder, external drive.
+      mirror <url>        off-machine backup to a git REMOTE (e.g. a private repo): content refs +
+                          a consistent audit snapshot on refs/backup/audit, verified. The TOTP secret
+                          is NEVER pushed. Run on a cadence for durable, off-box state.
+      status              canon head, perspectives, proposals, audit health
+      reindex             rebuild the MAP index from git
+      reconcile           backfill audit events for committed ops missing one
+      verify              check the audit chain (+ the git-anchored checkpoint)
+      anchor              write the audit head into git now
+      preview <id>        dry-run a proposal merge (conflicts / changed paths)
+      land <id> [--by X]  approve + land a proposal to canon (audit + reindex + anchor)
+      proposals           every proposal's lifecycle: open / landed / closed (+ lands_behind, raw)
+      close <id> <reason> close a lingering proposal (tombstone; terminal for seats; the gate's own
+                          duty to clear what will not land — nothing is deleted)
+"""
+import argparse
+import json
+import os
+import subprocess as sp
+import sys
+import time
+
+from .config import Config
+from .entries import compose_entry
+from .cap_server import components_from_config
+from .canon import (reindex_from_git, land_and_record, canon_seq, seq_display, LOG_DIR,
+                    proposal_statuses, close_proposal)
+from .audit_log import reconcile_from_git, anchor_audit_head, verify_against_anchor
+from .local_capstore import Approval, MergeConflict, CanonAppendOnly, PERSP_PREFIX as PERSP, PROP_PREFIX as PROP
+from .airlock import generate_secret, otpauth_uri, verify_code, totp_at, STEP
+
+
+def _first_heading(text: str):
+    for line in text.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return None
+
+
+def _qr_ascii(data: str):
+    """ASCII QR of `data`, or None if the optional qrcode package isn't installed."""
+    try:
+        import qrcode
+    except ImportError:
+        return None
+    import io
+    qr = qrcode.QRCode(border=2)
+    qr.add_data(data)
+    qr.make(fit=True)
+    buf = io.StringIO()
+    qr.print_ascii(out=buf, invert=True)   # dark-terminal polarity; the URI below is the fallback
+    return buf.getvalue()
+
+
+def run(args) -> dict:
+    cfg = Config.load(args.config)
+    store, index, embedder, audit, authz, airlock = components_from_config(cfg)
+
+    if args.cmd == "totp-provision":
+        issuer = cfg.deployment_name or "Stasima"
+        uri = lambda s: otpauth_uri(s, label=f"{issuer}:practitioner", issuer=issuer)
+        path = cfg.resolved_airlock_secret()
+        if os.path.exists(path) and not args.force:
+            if args.qr:   # re-display the EXISTING secret's QR — no rotation
+                with open(path, encoding="utf-8") as f:
+                    secret = f.read().strip()
+                qr = _qr_ascii(uri(secret))
+                print(qr if qr else "(pip install qrcode for a scannable QR)")
+                return {"secret_path": path, "otpauth_uri": uri(secret), "rotated": False,
+                        "note": "existing secret re-displayed; scan the QR or enter the secret= value manually"}
+            raise SystemExit(f"secret already exists at {path} — pass --force to rotate "
+                             f"(rotating invalidates the practitioner's current authenticator entry), "
+                             f"or --qr to re-display it")
+        secret = generate_secret()
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(secret + "\n")
+        if args.qr:
+            qr = _qr_ascii(uri(secret))
+            print(qr if qr else "(pip install qrcode for a scannable QR)")
+        return {"secret_path": path, "otpauth_uri": uri(secret),
+                "note": "scan the QR (or enter the secret= value manually); the secret stays "
+                        "server-side, never in git — if the QR won't scan, terminal polarity is the "
+                        "usual culprit; the manual key always works"}
+
+    if args.cmd == "totp-check":
+        # verification only — consumes no windows, approves nothing; safe to run as often as you like
+        spath = cfg.resolved_airlock_secret()
+        if not os.path.exists(spath):
+            raise SystemExit(f"no secret at {spath} — run totp-provision first")
+        with open(spath, encoding="utf-8") as f:
+            secret = f.read().strip()
+        now = time.time()
+        w = verify_code(secret, args.code, now)
+        if w is not None:
+            return {"valid": True, "matched_window": w, "current_window": int(now // STEP),
+                    "note": "your authenticator and the server agree — the airlock will accept codes"}
+        cur = int(now // STEP)
+        for delta in range(-10, 11):                       # diagnose clock skew beyond the ±1 acceptance
+            if totp_at(secret, cur + delta) == str(args.code).strip():
+                return {"valid": False, "matched_window": cur + delta,
+                        "skew": f"{delta:+d} windows (≈ {delta * STEP:+d}s)",
+                        "note": "code is from the right secret but outside the ±1-window acceptance — "
+                                "sync the server or phone clock"}
+        return {"valid": False,
+                "note": "no match within ±10 windows — mistyped code, or the app holds a different/old secret "
+                        "(re-provision with --force and re-add to the app)"}
+
+    if args.cmd == "bootstrap":
+        if not os.path.isdir(os.path.join(cfg.git_dir, "objects")):
+            sp.run(["git", "init", "--bare", "-q", cfg.git_dir], check=True)   # create the bare repo if missing
+        if store.resolve_ref(cfg.canon_ref) is not None:
+            raise SystemExit("canon already exists — add entries via propose + land, not bootstrap")
+        changes = {}
+        for root, _, files in os.walk(args.seed_dir):
+            for fn in sorted(files):
+                if not fn.endswith(".md"):
+                    continue
+                rel = os.path.relpath(os.path.join(root, fn), args.seed_dir).replace(os.sep, "/")
+                with open(os.path.join(root, fn), encoding="utf-8") as f:
+                    text = f.read()
+                if not text.lstrip().startswith("---"):    # plain markdown -> wrap with a sensible envelope
+                    title = _first_heading(text) or os.path.splitext(fn)[0].replace("-", " ").title()
+                    etype = "ori" if rel.startswith("technical/orientation/") else "kno"
+                    text = compose_entry({"type": etype, "title": title, "status": "active"}, text)
+                changes[rel] = text.encode()
+        if not changes:
+            raise SystemExit(f"no .md files found under {args.seed_dir!r}")
+        r = store.bootstrap_canon(changes, "Bootstrap canon")
+        return {"bootstrapped": r.oid, "entries": sorted(changes), "indexed": reindex_from_git(store, index, embedder)}
+
+    if args.cmd == "status":
+        ok, bad = audit.verify()
+        unread = [m for m in index.inbox("practitioner") if not audit.is_read("practitioner", m.path)]
+        return {"canon_head": store.resolve_ref(cfg.canon_ref),
+                "canon_seq": seq_display(canon_seq(store, cfg.seq_origin)),
+                "perspectives": [r.name[len(PERSP):] for r in store.list_refs(PERSP)],
+                "proposals": [r.name[len(PROP):] for r in store.list_refs(PROP)],
+                "staged": airlock.staged(),
+                "practitioner_unread": len(unread),
+                "audit_events": audit.count(), "audit_verify_ok": ok,
+                "audit_vs_anchor": verify_against_anchor(store, audit)}
+
+    if args.cmd == "inbox":
+        if args.read:
+            audit.append_read("practitioner", args.read)
+            return {"marked_read": args.read}
+        msgs = index.inbox("practitioner")
+        if not args.all:
+            msgs = [m for m in msgs if not audit.is_read("practitioner", m.path)]
+        return {"unread" if not args.all else "all":
+                [{"path": m.path, "from": m.authoring_instance, "subject": m.subject,
+                  "coordinates": m.links} for m in msgs],
+                "note": "read a message body with: kip_get equivalent -> git show <perspective>:<path>; "
+                        "mark handled with: inbox --read <path>"}
+
+    if args.cmd == "backup":
+        # everything that is TRUTH, in one destination: full-ref git mirror (consistent by nature),
+        # a consistent audit snapshot (sqlite backup API, safe against a live server), config + secret.
+        # The map index is a derived cache and is deliberately not backed up.
+        import shutil
+        import sqlite3 as _sq
+        os.makedirs(args.dest, exist_ok=True)
+        mirror = os.path.join(args.dest, "stasima-mirror.git")
+        if not os.path.isdir(os.path.join(mirror, "objects")):
+            sp.run(["git", "init", "--bare", "-q", mirror], check=True)
+        store.set_remote("backup", mirror)
+        sync = store.push_all("backup")
+        audit_copy = os.path.join(args.dest, "audit.sqlite")
+        dst = _sq.connect(audit_copy)
+        audit.conn.backup(dst)
+        dst.close()
+        copied = ["stasima-mirror.git", "audit.sqlite"]
+        for src in (args.config, cfg.resolved_airlock_secret()):
+            if src and os.path.exists(src):
+                shutil.copy2(src, args.dest)
+                copied.append(os.path.basename(src))
+        ok = not sync["missing_on_remote"] and not sync["oid_mismatch"]
+        return {"dest": args.dest, "git_sync_ok": ok, "synced_refs": len(sync["synced"]),
+                "audit_events": audit.count(), "copied": copied}
+
+    if args.cmd == "mirror":
+        # off-machine backup to a GIT REMOTE (e.g. a PRIVATE repo) in one command: content refs +
+        # a consistent audit snapshot on a dedicated ref (refs/backup/audit), both verified.
+        # The TOTP secret is deliberately NEVER pushed — it is the airlock key and is re-provisionable;
+        # keep it out of any remote, even a private one. (Use `backup <dest>` for a local bundle that
+        # DOES carry the secret, for a same-trust machine move.)
+        import sqlite3 as _sq
+        import tempfile
+        fd, snap = tempfile.mkstemp(suffix=".sqlite")
+        os.close(fd)
+        try:
+            dst = _sq.connect(snap)          # consistent snapshot, safe against a live server
+            audit.conn.backup(dst)
+            dst.close()
+            with open(snap, "rb") as f:
+                store.commit_file("refs/backup/audit", "audit.sqlite", f.read(),
+                                  f"audit snapshot ({audit.count()} events)")
+        finally:
+            os.remove(snap)
+        sync = store.mirror_push("mirror", args.url,
+                                 extra_refspecs=["refs/backup/audit:refs/backup/audit"])
+        ok = not sync["missing_on_remote"] and not sync["oid_mismatch"]
+        return {"remote": args.url, "git_sync_ok": ok, "synced_refs": len(sync["synced"]),
+                "audit_events": audit.count(),
+                "note": "content refs + audit snapshot pushed; TOTP secret NOT sent (re-provision on restore)"}
+
+    if args.cmd == "reindex":
+        return {"reindexed": reindex_from_git(store, index, embedder)}
+
+    if args.cmd == "proposals":
+        return {"proposals": proposal_statuses(store)}
+
+    if args.cmd == "close":
+        return close_proposal(store, audit, args.proposal_id, args.reason, "practitioner")
+
+    if args.cmd == "reconcile":
+        return {"backfilled": reconcile_from_git(store, audit)}
+
+    if args.cmd == "verify":
+        ok, bad = audit.verify()
+        return {"audit_verify_ok": ok, "first_bad_seq": bad,
+                "audit_vs_anchor": verify_against_anchor(store, audit)}
+
+    if args.cmd == "anchor":
+        return {"anchored": anchor_audit_head(store, audit)}
+
+    if args.cmd == "preview":
+        s = store.preview_merge(PROP + args.proposal_id, cfg.canon_ref)
+        logs = [p for p in (s.added + s.modified) if p.startswith(LOG_DIR)]
+        return {"conflicts": s.conflicts, "authors": s.authoring_instances,
+                "adds": s.added, "removes": s.removed, "modifies": s.modified,
+                "would_remove_canon": s.removed,          # non-empty -> `land` will REFUSE (append-only)
+                "log_entries": logs, "log_entry_ok": len(logs) == 1,
+                "expected_seq": format(canon_seq(store, cfg.seq_origin) + 1, "x")}
+
+    if args.cmd == "land":
+        approver = args.by or sorted(cfg.approvers)[0]
+        if approver not in cfg.approvers:
+            raise SystemExit(f"{approver!r} is not a configured approver ({sorted(cfg.approvers)})")
+        try:
+            prepared = store.prepare_merge(PROP + args.proposal_id, cfg.canon_ref)
+        except MergeConflict as e:
+            raise SystemExit(f"conflict — not landing: {e}")
+        except CanonAppendOnly as e:
+            raise SystemExit(f"append-only — not landing: {e}")
+        try:
+            return land_and_record(store, index, embedder, audit, prepared,
+                                   Approval(prepared.candidate_oid, approver, "cli-confirm"),
+                                   origin=cfg.seq_origin)
+        except ValueError as e:
+            raise SystemExit(f"not landing: {e}")
+
+    raise SystemExit(f"unknown command {args.cmd!r}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="stasima-admin", description="Stasima maintenance + promotion")
+    ap.add_argument("--config", default=os.environ.get("STASIMA_CONFIG"))
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for c in ("status", "reindex", "reconcile", "verify", "anchor", "proposals"):
+        sub.add_parser(c)
+    cl = sub.add_parser("close")
+    cl.add_argument("proposal_id")
+    cl.add_argument("reason", help="why this proposal will not land (recorded in the tombstone + audit)")
+    sub.add_parser("bootstrap").add_argument("seed_dir", help="folder of .md entries to seed an empty canon")
+    tp = sub.add_parser("totp-provision")
+    tp.add_argument("--force", action="store_true", help="rotate an existing secret")
+    tp.add_argument("--qr", action="store_true", help="render a scannable ASCII QR (re-displays if the secret exists)")
+    sub.add_parser("totp-check").add_argument("code", help="a code from your authenticator app")
+    sub.add_parser("backup").add_argument("dest", help="destination folder for the full backup (carries the secret)")
+    sub.add_parser("mirror").add_argument("url", help="git remote URL (e.g. a PRIVATE repo) — content + audit, no secret")
+    ib = sub.add_parser("inbox")
+    ib.add_argument("--all", action="store_true", help="include already-read messages")
+    ib.add_argument("--read", default=None, metavar="PATH", help="mark a message path as read")
+    sub.add_parser("preview").add_argument("proposal_id")
+    land = sub.add_parser("land")
+    land.add_argument("proposal_id")
+    land.add_argument("--by", default=None, help="approver (defaults to the first configured)")
+    return ap
+
+
+def main(argv=None) -> dict:
+    try:   # Windows consoles default to cp1252, which can't print the QR block chars (or em dashes)
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+    result = run(build_parser().parse_args(argv))
+    print(json.dumps(result, indent=2, default=str))
+    return result
+
+
+if __name__ == "__main__":
+    main()

stasima/airlock.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Airlock — TOTP two-phase remote approval (the mediated-channel counterpart of console `land`).
+
+At the console, the console itself is the out-of-band channel, so admin `land` stays a single
+approval. When the practitioner approves *through an instance conversation* (phone, relay), the
+channel is the thing to defend against: the airlock binds presence-proofs (TOTP codes) to the
+existing prepare/land two-phase gate so no single code — harvested, relayed, or replayed — can
+both stage and land, and nothing can land unreviewed.
+
+    open --code 1--> staged --(review: floor..ceiling)--code 2--> landed
+      ^                |
+      +---- revert ----+    (abort: FREE, no code; TTL expiry: lazy auto-revert)
+
+Why the 120s floor: a TOTP code lives at most ~90s (30s step, +/-1 window acceptance), so any code
+visible at staging time is arithmetically dead by the earliest legal landing moment. Strict window
+ordering (code 2 strictly later than code 1) and consume-once (a window number is never accepted
+twice for one purpose) close the same-window and replay paths as defense in depth. Content-binding
+(landing names the staged oid) means what lands is exactly what was staged — a swap fails closed.
+
+Abort is free by design: charging presence-proof to *decline* would incentivize landing.
+
+Honest residual: the practitioner's view of what was staged flows through the relaying instance.
+Content-binding makes swap-after-stage impossible and the audit trail makes deception detectable
+after the fact; it does NOT make the relay's display trustworthy in the moment. The console remains
+the stronger channel.
+
+State (open | staged | landed, with revert folding back to open) is derived from the audit log —
+staging is operational, not content; nothing here touches the storage spine. The clock is
+injectable for tests; server time is authoritative for every gate.
+"""
+import base64
+import hashlib
+import hmac
+import os
+import struct
+import time
+
+from .local_capstore import MergePreparation, MergeSummary, Approval, PROP_PREFIX as PROP
+
+STEP = 30                      # RFC 6238 time step (seconds)
+DIGITS = 6
+
+
+class AirlockError(Exception):
+    """A gate refused. The message names the failed gate and both values where applicable."""
+
+
+# ---------------------------------------------------------------- TOTP (RFC 6238, stdlib only)
+def generate_secret() -> str:
+    return base64.b32encode(os.urandom(20)).decode()
+
+
+def otpauth_uri(secret: str, label: str = "Stasima:practitioner", issuer: str = "Stasima") -> str:
+    return (f"otpauth://totp/{label}?secret={secret}&issuer={issuer}"
+            f"&algorithm=SHA1&digits={DIGITS}&period={STEP}")
+
+
+def totp_at(secret: str, window: int) -> str:
+    """The code for an absolute window number (window = unix_time // STEP)."""
+    key = base64.b32decode(secret.strip(), casefold=True)
+    mac = hmac.new(key, struct.pack(">Q", window), hashlib.sha1).digest()
+    off = mac[-1] & 0x0F
+    code = (struct.unpack(">I", mac[off:off + 4])[0] & 0x7FFFFFFF) % (10 ** DIGITS)
+    return f"{code:0{DIGITS}d}"
+
+
+def verify_code(secret: str, code: str, now: float):
+    """Accept the current window +/-1 (clock skew). Returns the MATCHED window number, else None."""
+    w = int(now // STEP)
+    for cand in (w, w - 1, w + 1):
+        if hmac.compare_digest(totp_at(secret, cand), str(code).strip()):
+            return cand
+    return None
+
+
+# ---------------------------------------------------------------- the gate
+class Airlock:
+    def __init__(self, store, audit, *, secret_path, land_fn, validate_fn, approver,
+                 floor_s: int = 120, ceiling_s: int = 7200, clock=time.time, prop_prefix: str = PROP):
+        # floor must exceed worst-case code lifetime (STEP + one window of skew acceptance ~= 90s)
+        # so that no code obtained at staging survives to the landing moment.
+        self.store = store
+        self.audit = audit
+        self.secret_path = secret_path
+        self.land_fn = land_fn          # (prepared, approval) -> land_and_record result
+        self.validate_fn = validate_fn  # (prepared) -> log-entry seq (early feedback; land re-validates)
+        self.approver = approver
+        self.floor_s = floor_s
+        self.ceiling_s = ceiling_s
+        self.clock = clock
+        self.prop_prefix = prop_prefix
+
+    # ---- secret + code consumption ----
+    def _secret(self) -> str:
+        if not os.path.exists(self.secret_path):
+            raise AirlockError("airlock not provisioned — run: admin totp-provision")
+        with open(self.secret_path, encoding="utf-8") as f:
+            return f.read().strip()
+
+    def _consume(self, code, purpose, obj, min_window=None) -> int:
+        """Verify a code and burn its window for this purpose. Codes are never logged — windows are."""
+        w = verify_code(self._secret(), code, self.clock())
+        if w is None:
+            self.audit.append("system", "totp_reject", detail={"purpose": purpose, "object": obj,
+                                                               "reason": "invalid"})
+            raise AirlockError("invalid code")
+        if min_window is not None and w <= min_window:
+            self.audit.append("system", "totp_reject", detail={"purpose": purpose, "object": obj,
+                                                               "window": w, "min_window": min_window,
+                                                               "reason": "not strictly later"})
+            raise AirlockError(f"code is from window {w}, which is not strictly later than the staging "
+                               f"window {min_window} — wait for a fresh code")
+        for e in self.audit.events(op="totp_accept"):
+            if e["detail"].get("window") == w and e["detail"].get("purpose") == purpose:
+                self.audit.append("system", "totp_reject", detail={"purpose": purpose, "object": obj,
+                                                                   "window": w, "reason": "replay"})
+                raise AirlockError(f"a code from window {w} was already used for {purpose} (consume-once)")
+        self.audit.append("practitioner", "totp_accept", detail={"window": w, "purpose": purpose, "object": obj})
+        return w
+
+    # ---- state machine (derived from the audit log; TTL is lazy) ----
+    def _fold(self, proposal_id):
+        cur, ev = "open", None
+        full_ref = self.prop_prefix + proposal_id
+        for e in self.audit.events():
+            d = e["detail"]
+            if e["op"] == "airlock_stage" and d.get("proposal") == proposal_id:
+                cur, ev = "staged", e
+            elif e["op"] == "airlock_revert" and d.get("proposal") == proposal_id:
+                cur, ev = "open", e
+            elif e["op"] == "land_merge" and d.get("proposal") == full_ref:
+                cur, ev = "landed", e
+        return cur, ev
+
+    def state(self, proposal_id) -> dict:
+        st, e = self._fold(proposal_id)
+        if st == "staged":
+            d = e["detail"]
+            if self.clock() - d["staged_at"] > self.ceiling_s:   # lazy TTL: observed -> reverted
+                self.audit.append("system", "airlock_revert", target_ref=self.prop_prefix + proposal_id,
+                                  detail={"proposal": proposal_id, "reason": "ttl",
+                                          "staged_oid": d["staged_oid"]})
+                return {"state": "open", "reverted": "ttl"}
+            return {"state": "staged", "staged_oid": d["staged_oid"], "staged_at": d["staged_at"],
+                    "window": d["window"], "changed_paths": d.get("changed_paths", []),
+                    "lands_after": d["staged_at"] + self.floor_s,
+                    "expires_at": d["staged_at"] + self.ceiling_s}
+        return {"state": st}
+
+    def staged(self) -> list:
+        """Currently staged proposals (cockpit view)."""
+        return [{"proposal_id": pid, "staged_oid": st["staged_oid"],
+                 "lands_after": st["lands_after"], "expires_at": st["expires_at"]}
+                for pid, st in self._staged_proposals()]
+
+    def _staged_proposals(self):
+        seen, out = set(), []
+        for e in self.audit.events(op="airlock_stage"):
+            pid = e["detail"]["proposal"]
+            if pid in seen:
+                continue
+            seen.add(pid)
+            st = self.state(pid)
+            if st["state"] == "staged":
+                out.append((pid, st))
+        return out
+
+    # ---- the three ops ----
+    def stage(self, proposal_id, code) -> dict:
+        """Code 1: freeze the proposal, prepare the merge, start the review clock."""
+        if self.state(proposal_id)["state"] == "staged":
+            raise AirlockError(f"{proposal_id} is already staged")
+        # prove the proposal stageable BEFORE consuming the code — failures must not burn windows
+        prepared = self.store.prepare_merge(self.prop_prefix + proposal_id, self.store.canon_ref)
+        seq = self.validate_fn(prepared)
+        w = self._consume(code, "stage", proposal_id)
+        staged_at = self.clock()
+        self.audit.append("practitioner", "airlock_stage", target_ref=self.prop_prefix + proposal_id,
+                          result_oid=prepared.candidate_oid,
+                          detail={"proposal": proposal_id, "staged_oid": prepared.candidate_oid,
+                                  "window": w, "staged_at": staged_at, "seq": seq,
+                                  "changed_paths": prepared.summary.changed_paths})
+        return {"proposal_id": proposal_id, "staged_oid": prepared.candidate_oid,
+                "staged_at": staged_at, "lands_after": staged_at + self.floor_s,
+                "expires_at": staged_at + self.ceiling_s,
+                "changed_paths": prepared.summary.changed_paths, "log_seq": seq}
+
+    def land(self, staged_oid_prefix, code) -> dict:
+        """Code 2: after the review floor, strictly later window, bound to the staged content."""
+        if len(str(staged_oid_prefix)) < 8:
+            raise AirlockError("staged oid prefix too short — give at least 8 hex characters")
+        matches = [(pid, st) for pid, st in self._staged_proposals()
+                   if st["staged_oid"].startswith(staged_oid_prefix)]
+        if not matches:
+            raise AirlockError(f"no staged proposal matches oid prefix {staged_oid_prefix!r} (content-binding)")
+        if len(matches) > 1:
+            raise AirlockError(f"oid prefix {staged_oid_prefix!r} is ambiguous across staged proposals")
+        pid, st = matches[0]
+        elapsed = self.clock() - st["staged_at"]
+        if elapsed < self.floor_s:   # gates before code verification — a floor miss must not burn a window
+            raise AirlockError(f"review floor not met: {elapsed:.0f}s since staging, floor is "
+                               f"{self.floor_s}s — review, then retry with a fresh code")
+        w2 = self._consume(code, "land", pid, min_window=st["window"])
+        prepared = MergePreparation(candidate_oid=st["staged_oid"], into=self.store.canon_ref,
+                                    proposal_ref=self.prop_prefix + pid,
+                                    summary=MergeSummary(st.get("changed_paths", []), [], []))
+        return self.land_fn(prepared, Approval(st["staged_oid"], self.approver, f"airlock-totp-w{w2}"))
+
+    def revert(self, proposal_id) -> dict:
+        """Abort a staged review. FREE — never requires a code (charging for decline would
+        incentivize landing). Returns the proposal to open with its entries intact."""
+        if self.state(proposal_id)["state"] != "staged":
+            raise AirlockError(f"{proposal_id} is not staged")
+        self.audit.append("system", "airlock_revert", target_ref=self.prop_prefix + proposal_id,
+                          detail={"proposal": proposal_id, "reason": "manual"})
+        return {"proposal_id": proposal_id, "state": "open"}