@tasksai/install 0.1.38 → 0.1.40

package/runtime/workflows/store.py

@@ -0,0 +1,492 @@
+"""Local single-owner development job store. No network or licensed MCP hooks.
+
+The OS account is the security boundary; owner labels are not authentication.
+SQLite serializes mutations. Only a fully exported revision becomes current.
+"""
+from contextlib import contextmanager
+from datetime import datetime, timezone, timedelta
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sqlite3
+import uuid
+
+
+class JobError(ValueError):
+    pass
+
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+
+
+def digest(value):
+    return hashlib.sha256(canonical(value).encode()).hexdigest()
+
+
+def file_hash(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def label(value, field):
+    if not isinstance(value, str) or not value.strip() or len(value) > 240:
+        raise JobError(f"{field} must be nonempty text of at most 240 characters")
+    return value
+
+
+def identifier(value):
+    if not isinstance(value, str) or not re.fullmatch(r"[a-f0-9]{32}", value):
+        raise JobError("Invalid job or revision ID")
+    return value
+
+
+class JobStore:
+    def __init__(self, root, owner):
+        self.owner = label(owner, "owner")
+        raw = Path(root).expanduser().absolute()
+        if raw.is_symlink():
+            raise JobError("Workspace cannot be a symbolic link")
+        raw.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.root = raw.resolve()
+        self.root.chmod(0o700)
+        self.db_path = self.root / "jobs.sqlite3"
+        self._safe(self.db_path)
+        with self._db() as db:
+            db.executescript("""
+                CREATE TABLE IF NOT EXISTS workspace (owner TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS jobs (
+                  id TEXT PRIMARY KEY, owner TEXT NOT NULL, workflow TEXT NOT NULL,
+                  matter TEXT NOT NULL, current_revision TEXT, created_at TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS revisions (
+                  id TEXT PRIMARY KEY, job_id TEXT NOT NULL, parent TEXT,
+                  created_at TEXT NOT NULL, reason TEXT NOT NULL, manifest_hash TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS requests (
+                  request_id TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, response TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS review_requests (
+                  id TEXT PRIMARY KEY, job_id TEXT NOT NULL, revision_id TEXT NOT NULL,
+                  manifest_hash TEXT NOT NULL, scope TEXT NOT NULL, created_at TEXT NOT NULL,
+                  expires_at TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS review_events (
+                  id TEXT PRIMARY KEY, ticket_id TEXT UNIQUE NOT NULL, job_id TEXT NOT NULL,
+                  revision_id TEXT NOT NULL, manifest_hash TEXT NOT NULL, reviewer TEXT NOT NULL,
+                  scope TEXT NOT NULL, outcome TEXT NOT NULL, evidence_kind TEXT NOT NULL,
+                  recorded_at TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS concerns (
+                  id TEXT PRIMARY KEY, job_id TEXT NOT NULL, revision_id TEXT NOT NULL,
+                  title TEXT NOT NULL, detail TEXT NOT NULL, responsible_role TEXT NOT NULL,
+                  created_at TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS documents (
+                  id TEXT NOT NULL, job_id TEXT NOT NULL, filename TEXT NOT NULL,
+                  sha256 TEXT NOT NULL, extraction_hash TEXT NOT NULL, extension TEXT NOT NULL,
+                  created_at TEXT NOT NULL, PRIMARY KEY(job_id,id));
+                CREATE TABLE IF NOT EXISTS concern_events (
+                  id TEXT PRIMARY KEY, concern_id TEXT NOT NULL, revision_id TEXT NOT NULL,
+                  status TEXT NOT NULL, explanation TEXT NOT NULL, refs TEXT NOT NULL,
+                  created_at TEXT NOT NULL);
+                CREATE TABLE IF NOT EXISTS attention_drafts (
+                  job_id TEXT NOT NULL, concern_id TEXT NOT NULL, base_revision TEXT NOT NULL,
+                  payload TEXT NOT NULL, updated_at TEXT NOT NULL,
+                  PRIMARY KEY(job_id, concern_id));
+            """)
+            db.execute("BEGIN IMMEDIATE")
+            for table in ("review_requests", "review_events"):
+                if "concerns_hash" not in {r[1] for r in db.execute(f"PRAGMA table_info({table})")}:
+                    db.execute(f"ALTER TABLE {table} ADD COLUMN concerns_hash TEXT")
+            row = db.execute("SELECT owner FROM workspace").fetchone()
+            if row is None:
+                db.execute("INSERT INTO workspace VALUES (?)", (self.owner,))
+            elif row[0] != self.owner:
+                raise JobError("This workspace belongs to another owner")
+        self.db_path.chmod(0o600)
+
+    def _safe(self, path):
+        if self.root.is_symlink():
+            raise JobError("Workspace was replaced by a symbolic link")
+        path = Path(path)
+        try:
+            relative = path.relative_to(self.root)
+        except ValueError as exc:
+            raise JobError("Path outside workspace") from exc
+        current = self.root
+        for part in relative.parts:
+            if part in ("..", "."):
+                raise JobError("Invalid workspace path")
+            current = current / part
+            if current.is_symlink():
+                raise JobError("Symbolic links inside the workspace are not supported")
+        return path
+
+    @contextmanager
+    def _db(self):
+        self._safe(self.db_path)
+        for suffix in ("-journal", "-wal", "-shm"):
+            self._safe(Path(str(self.db_path) + suffix))
+        db = sqlite3.connect(self.db_path, timeout=120)
+        db.row_factory = sqlite3.Row
+        try:
+            yield db
+            db.commit()
+        except BaseException:
+            db.rollback()
+            raise
+        finally:
+            db.close()
+
+    def _job(self, db, job_id):
+        identifier(job_id)
+        row = db.execute("SELECT * FROM jobs WHERE id=? AND owner=?", (job_id, self.owner)).fetchone()
+        if row is None:
+            raise JobError("Job not found in this workspace")
+        return dict(row)
+
+    def _retry(self, db, request_id, fingerprint):
+        label(request_id, "request_id")
+        row = db.execute("SELECT * FROM requests WHERE request_id=?", (request_id,)).fetchone()
+        if row:
+            if row["fingerprint"] != fingerprint:
+                raise JobError("Request ID was already used for different work")
+            return json.loads(row["response"])
+
+    def create(self, matter, request_id, workflow="realtor.seller_offer"):
+        label(matter, "matter")
+        if workflow not in ("realtor.seller_offer", "realtor.meeting_plan"):
+            from .released_catalog import registry
+            if workflow not in registry():
+                raise JobError("Unknown workflow")
+        fp = digest(["create", self.owner, matter, workflow])
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            response = self._retry(db, request_id, fp)
+            if response:
+                return response
+            job_id = uuid.uuid4().hex
+            db.execute("INSERT INTO jobs VALUES (?,?,?,?,?,?)", (job_id, self.owner, workflow, matter, None, now()))
+            response = {"job_id": job_id, "current_revision": None}
+            db.execute("INSERT INTO requests VALUES (?,?,?)", (request_id, fp, canonical(response)))
+            return response
+
+    def _revision(self, db, job_id, revision_id):
+        identifier(revision_id)
+        row = db.execute("SELECT * FROM revisions WHERE id=? AND job_id=?", (revision_id, job_id)).fetchone()
+        if row is None:
+            raise JobError("Revision not found for this job")
+        directory = self._safe(self.root / job_id / "revisions" / revision_id)
+        manifest_path = self._safe(directory / "job-manifest.json")
+        if not manifest_path.is_file() or file_hash(manifest_path) != row["manifest_hash"]:
+            raise JobError("Revision manifest changed or is missing")
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        for expected in manifest.get('documents', []):
+            from .documents import read_document
+            document = read_document(self, db, job_id, expected['id'])
+            if any(document[key] != expected[key] for key in ('sha256', 'extraction_hash')):
+                raise JobError('Revision source document changed')
+        for name, expected in manifest["files"].items():
+            p = self._safe(directory / name)
+            if not p.is_file() or file_hash(p) != expected:
+                raise JobError(f"Revision file changed or is missing: {name}")
+        return {**dict(row), "directory": str(directory), "manifest": manifest,
+                "input": json.loads((directory / "input.json").read_text(encoding="utf-8")),
+                "result": json.loads((directory / "package" / "result.json").read_text(encoding="utf-8"))}
+
+    def read(self, job_id):
+        with self._db() as db:
+            db.execute("BEGIN")
+            job = self._job(db, job_id)
+            history = [dict(r) for r in db.execute("SELECT id,parent,created_at,reason FROM revisions WHERE job_id=? ORDER BY rowid", (job_id,))]
+            current = self._revision(db, job_id, job["current_revision"]) if job["current_revision"] else None
+            known = {r["id"] for r in history}
+            orphaned = []
+            for group in ("attempts", "revisions"):
+                folder = self._safe(self.root / job_id / group)
+                if folder.exists():
+                    for p in folder.iterdir():
+                        self._safe(p)
+                        if group == "attempts" or p.name not in known:
+                            orphaned.append(str(p))
+            reviews = [dict(r) for r in db.execute("SELECT * FROM review_events WHERE job_id=? ORDER BY rowid", (job_id,))]
+            concerns = self._concerns(db, job_id, job["current_revision"])
+            concerns_hash = digest(concerns)
+            current_reviews = [r for r in reviews if r["revision_id"] == job["current_revision"]]
+            pending = [dict(r) for r in db.execute("SELECT * FROM review_requests WHERE job_id=? AND revision_id=? AND id NOT IN (SELECT ticket_id FROM review_events) AND expires_at>?", (job_id, job["current_revision"], now()))]
+            pending = [r for r in pending if r["concerns_hash"] == concerns_hash or (r["concerns_hash"] is None and not concerns)]
+            review_status = "review_required" if reviews else "not_reviewed"
+            if current_reviews:
+                review_status = "simulated_review" if current_reviews[-1]["evidence_kind"] == "simulated_test" else current_reviews[-1]["outcome"]
+                if current_reviews[-1]["concerns_hash"] != concerns_hash and not (current_reviews[-1]["concerns_hash"] is None and not concerns):
+                    review_status = "review_required"
+            elif pending:
+                review_status = "review_pending"
+            if pending and review_status == "review_required":
+                review_status = "review_pending"
+            return {**job, "history": history, "current": current,
+                    "incomplete_attempts": orphaned, "review_status": review_status,
+                    "review_events": reviews, "pending_reviews": pending,
+                    "concerns": concerns, "concerns_hash": concerns_hash,
+                    "external_actions": [], "next_step": "Resolve open questions and review the prepared files" if current else "Supply offer records"}
+
+    def list_jobs(self, limit=100, offset=0):
+        if type(limit) is not int or not 1 <= limit <= 200 or type(offset) is not int or offset < 0:
+            raise JobError("Invalid project page")
+        with self._db() as db:
+            return [dict(row) for row in db.execute("SELECT id,matter,workflow,current_revision,created_at FROM jobs WHERE owner=? ORDER BY rowid DESC LIMIT ? OFFSET ?", (self.owner,limit,offset))]
+
+    def read_revision(self, job_id, revision_id):
+        with self._db() as db:
+            self._job(db, job_id)
+            return self._revision(db, job_id, revision_id)
+
+    def _concerns(self, db, job_id, current_revision):
+        concerns = []
+        for row in db.execute("SELECT * FROM concerns WHERE job_id=? ORDER BY rowid", (job_id,)):
+            concern = dict(row)
+            events = []
+            for event in db.execute("SELECT * FROM concern_events WHERE concern_id=? ORDER BY rowid", (row["id"],)):
+                event = dict(event)
+                event["references"] = json.loads(event.pop("refs"))
+                events.append(event)
+            last = events[-1]
+            status = last["status"]
+            if status == "resolution_recorded" and last["revision_id"] != current_revision:
+                status = "needs_recheck"
+            concern.update(status=status, last_event_id=last["id"], events=events,
+                           resolution_is_professional_review=False)
+            concerns.append(concern)
+        return concerns
+
+    def record_concern(self, job_id, revision_id, request_id, title, detail, responsible_role, references):
+        for key, value in (("title", title), ("detail", detail), ("responsible_role", responsible_role)):
+            label(value, key)
+        return self._change_concern(job_id, revision_id, request_id, "open", detail, references,
+                                    new=(title, detail, responsible_role))
+
+    def update_concern(self, job_id, revision_id, request_id, concern_id, expected_event_id, status, explanation, references):
+        identifier(concern_id)
+        identifier(expected_event_id)
+        if status not in ("open", "resolution_recorded"):
+            raise JobError("Concern status must be open or resolution_recorded")
+        label(explanation, "explanation")
+        return self._change_concern(job_id, revision_id, request_id, status, explanation, references,
+                                    concern_id=concern_id, expected_event_id=expected_event_id)
+
+    def _change_concern(self, job_id, revision_id, request_id, status, explanation, references, *, new=None, concern_id=None, expected_event_id=None):
+        if not isinstance(references, list) or not 1 <= len(references) <= 20:
+            raise JobError("Supply 1 to 20 source references")
+        for ref in references:
+            if not isinstance(ref, dict) or set(ref) != {"source_id", "locator"}:
+                raise JobError("Each reference requires source_id and locator")
+            label(ref["source_id"], "source_id")
+            label(ref["locator"], "locator")
+        if len({canonical(r) for r in references}) != len(references):
+            raise JobError("Duplicate concern reference")
+        fp = digest(["concern", job_id, revision_id, new, concern_id, expected_event_id, status, explanation, references])
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            job = self._job(db, job_id)
+            retried = self._retry(db, request_id, fp)
+            if retried:
+                self._revision(db, job_id, revision_id)
+                return retried
+            if revision_id != job["current_revision"]:
+                raise JobError("Job changed; reopen before recording a concern or resolution")
+            revision = self._revision(db, job_id, revision_id)
+            sources = {s["id"]: s for s in revision["input"].get("sources", [])}
+            refs = []
+            for ref in references:
+                if ref["source_id"] not in sources:
+                    raise JobError("Concern references an unknown source in this revision")
+                refs.append({**ref, "source_hash": digest(sources[ref["source_id"]])})
+            if new:
+                # Exact duplicate observations reuse the saved concern even with a new request ID.
+                for existing in self._concerns(db, job_id, revision_id):
+                    first = existing["events"][0]
+                    if (existing["title"], existing["detail"], existing["responsible_role"], first["references"]) == (*new, refs):
+                        if existing["status"] == "resolution_recorded":
+                            raise JobError("Concern already has a resolution; use update_concern to reopen it")
+                        response = {"concern_id": existing["id"], "event_id": existing["last_event_id"], "duplicate": True}
+                        db.execute("INSERT INTO requests VALUES (?,?,?)", (request_id, fp, canonical(response)))
+                        return response
+                concern_id = uuid.uuid4().hex
+                db.execute("INSERT INTO concerns VALUES (?,?,?,?,?,?,?)", (concern_id, job_id, revision_id, *new, now()))
+            else:
+                existing = next((c for c in self._concerns(db, job_id, revision_id) if c["id"] == concern_id), None)
+                if existing is None:
+                    raise JobError("Concern not found for this job")
+                if existing["last_event_id"] != expected_event_id:
+                    raise JobError("Concern changed; reopen before updating it")
+            event_id = uuid.uuid4().hex
+            db.execute("INSERT INTO concern_events VALUES (?,?,?,?,?,?,?)", (event_id, concern_id, revision_id, status, explanation, canonical(refs), now()))
+            response = {"concern_id": concern_id, "event_id": event_id, "duplicate": False}
+            db.execute("INSERT INTO requests VALUES (?,?,?)", (request_id, fp, canonical(response)))
+            return response
+
+    def request_review(self, job_id, revision_id, request_id, scope):
+        label(scope, "scope")
+        fp = digest(["request_review", job_id, revision_id, scope])
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            job = self._job(db, job_id)
+            if revision_id != job["current_revision"]:
+                raise JobError("Only the current revision can be submitted for review")
+            revision = self._revision(db, job_id, revision_id)
+            retried = self._retry(db, request_id, fp)
+            if retried:
+                return retried
+            ticket = {"id": uuid.uuid4().hex, "job_id": job_id, "revision_id": revision_id,
+                      "manifest_hash": revision["manifest_hash"], "scope": scope, "created_at": now(),
+                      "expires_at": (datetime.now(timezone.utc) + timedelta(hours=24)).isoformat(),
+                      "concerns_hash": digest(self._concerns(db, job_id, revision_id))}
+            db.execute("INSERT INTO review_requests VALUES (?,?,?,?,?,?,?,?)", tuple(ticket.values()))
+            db.execute("INSERT INTO requests VALUES (?,?,?)", (request_id, fp, canonical(ticket)))
+            return ticket
+
+    def review_ticket(self, ticket_id):
+        identifier(ticket_id)
+        with self._db() as db:
+            row = db.execute("SELECT * FROM review_requests WHERE id=?", (ticket_id,)).fetchone()
+            if row is None:
+                raise JobError("Review request not found")
+            self._job(db, row["job_id"])
+            return dict(row)
+
+    @staticmethod
+    def review_attestation(ticket, outcome):
+        return f"I personally reviewed revision {ticket['revision_id']} and concerns {ticket.get('concerns_hash') or 'none (legacy request)'} for {ticket['scope']}; outcome {outcome}"
+
+    def record_local_review(self, ticket_id, reviewer, outcome, attestation, *, evidence_kind="local_attestation"):
+        """Review attestation entry point; not exposed as a model-callable tool.
+
+        The CLI requires an interactive terminal; the private card requires explicit confirmation. This is a recorded self-attestation,
+        not identity verification or independent proof that review was performed.
+        """
+        identifier(ticket_id)
+        label(reviewer, "reviewer")
+        if outcome not in ("review_recorded", "changes_requested") or evidence_kind not in ("local_attestation", "card_attestation", "simulated_test"):
+            raise JobError("Invalid review outcome or evidence kind")
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute("SELECT * FROM review_requests WHERE id=?", (ticket_id,)).fetchone()
+            if row is None:
+                raise JobError("Review request not found")
+            ticket = dict(row)
+            job = self._job(db, ticket["job_id"])
+            if job["current_revision"] != ticket["revision_id"]:
+                raise JobError("Package changed; review the current revision")
+            revision = self._revision(db, ticket["job_id"], ticket["revision_id"])
+            if revision["manifest_hash"] != ticket["manifest_hash"]:
+                raise JobError("Package hash changed")
+            concerns = self._concerns(db, ticket["job_id"], ticket["revision_id"])
+            if ticket["concerns_hash"] != digest(concerns) and not (ticket["concerns_hash"] is None and not concerns):
+                raise JobError("Review concerns changed; request a new review")
+            if attestation != self.review_attestation(ticket, outcome):
+                raise JobError("The exact review attestation is required")
+            previous = db.execute("SELECT * FROM review_events WHERE ticket_id=?", (ticket_id,)).fetchone()
+            if previous:
+                event = dict(previous)
+                if (event["reviewer"],event["outcome"],event["evidence_kind"]) != (reviewer,outcome,evidence_kind):
+                    raise JobError("Review request already has a different outcome")
+                return event
+            if datetime.fromisoformat(ticket["expires_at"]) <= datetime.now(timezone.utc):
+                raise JobError("Review request expired; request a new review")
+            event = {"id": uuid.uuid4().hex, "ticket_id": ticket_id, "job_id": ticket["job_id"],
+                     "revision_id": ticket["revision_id"], "manifest_hash": ticket["manifest_hash"],
+                     "reviewer": reviewer, "scope": ticket["scope"], "outcome": outcome,
+                     "evidence_kind": evidence_kind, "recorded_at": now(), "concerns_hash": digest(concerns)}
+            db.execute("INSERT INTO review_events VALUES (?,?,?,?,?,?,?,?,?,?,?)", tuple(event.values()))
+            return event
+
+    def prepare(self, job_id, packet, expected_parent, request_id, reason, adapter, *, node=None, concern_note=None):
+        label(reason, "reason")
+        raw = canonical(packet)
+        if len(raw.encode()) > 2_000_000:
+            raise JobError("Structured input exceeds 2 MB")
+        fp = digest(["prepare", job_id, expected_parent, packet, reason, adapter.version] + ([concern_note] if concern_note is not None else []))
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            job = self._job(db, job_id)
+            if job["workflow"] != adapter.workflow_id:
+                raise JobError("Wrong workflow adapter")
+            response = self._retry(db, request_id, fp)
+            if response:
+                revision = self._revision(db, job_id, response["revision_id"])
+                # A restored workspace can have a different root. Resolve the
+                # verified revision here instead of replaying its old address.
+                return {**response, "directory": revision["directory"]}
+            if expected_parent != job["current_revision"]:
+                raise JobError("Job changed; reopen it before preparing another revision")
+            parent = self._revision(db, job_id, expected_parent) if expected_parent else None
+            supplied = json.loads(raw)
+            from .documents import bind_documents
+            documents = bind_documents(self, db, job_id, supplied)
+            normalized, result, changes = adapter.prepare(supplied, parent)
+            revision_id = uuid.uuid4().hex
+            if concern_note is not None:
+                # Save the explanation and the exported snapshot in one transaction.
+                # A user clarification stays open for review; it cannot certify itself.
+                if not isinstance(concern_note, dict) or set(concern_note) != {"concern_id", "expected_event_id", "explanation", "source_id", "locator"}:
+                    raise JobError("Invalid concern note")
+                for field, value in concern_note.items():
+                    label(value, field)
+                existing = next((c for c in self._concerns(db, job_id, expected_parent) if c["id"] == concern_note["concern_id"]), None)
+                if existing is None or existing["last_event_id"] != concern_note["expected_event_id"]:
+                    raise JobError("Concern changed; reopen the project before saving")
+                source = next((s for s in normalized.get("sources", []) if s["id"] == concern_note["source_id"]), None)
+                if source is None:
+                    raise JobError("Clarification source is missing")
+                refs = [{"source_id": source["id"], "locator": concern_note["locator"], "source_hash": digest(source)}]
+                db.execute("INSERT INTO concern_events VALUES (?,?,?,?,?,?,?)", (uuid.uuid4().hex, existing["id"], revision_id, "open", concern_note["explanation"], canonical(refs), now()))
+                db.execute("DELETE FROM attention_drafts WHERE job_id=? AND concern_id=?", (job_id, existing["id"]))
+            staging = self._safe(self.root / job_id / "attempts" / revision_id)
+            staging.mkdir(parents=True, mode=0o700)
+            context = {"job_id": job_id, "revision_id": revision_id, "parent_revision": expected_parent,
+                       "reason": reason, "changes": changes, "review_status": "not_reviewed",
+                       "concerns": self._concerns(db, job_id, revision_id)}
+            try:
+                (staging / "input.json").write_text(canonical(normalized) + "\n", encoding="utf-8")
+                (staging / "changes.json").write_text(canonical(context) + "\n", encoding="utf-8")
+                adapter.export(staging / "input.json", staging / "package", context, node=node)
+                adapter.validate(staging / "package", result)
+                (staging / "changes.md").write_text("# Package changes\n\n" + "\n".join("- " + c for c in changes) + "\n", encoding="utf-8")
+                manifest = {**context, "workflow_id": adapter.workflow_id, "workflow_version": adapter.version,
+                            "documents": documents,
+                            "implementation_hashes": adapter.hashes(), "created_at": now(),
+                            "source_versions": [{"id": s["id"], "sha256": digest(s)} for s in normalized.get("sources", [])],
+                            "files": {}}
+                for p in sorted(staging.rglob("*")):
+                    self._safe(p)
+                    if p.is_file():
+                        p.chmod(0o600)
+                        manifest["files"][str(p.relative_to(staging))] = file_hash(p)
+                    elif p.is_dir():
+                        p.chmod(0o700)
+                manifest_path = staging / "job-manifest.json"
+                manifest_path.write_text(canonical(manifest) + "\n", encoding="utf-8")
+                manifest_path.chmod(0o600)
+                # Flush artifacts before publishing the pointer in SQLite.
+                for p in staging.rglob("*"):
+                    if p.is_file():
+                        # Windows _commit requires a writable descriptor. These
+                        # are newly generated staging files, not source files.
+                        with p.open("r+b") as stream:
+                            os.fsync(stream.fileno())
+                manifest_hash = file_hash(manifest_path)
+                final = self._safe(self.root / job_id / "revisions" / revision_id)
+                final.parent.mkdir(exist_ok=True, mode=0o700)
+                staging.rename(final)
+                db.execute("INSERT INTO revisions VALUES (?,?,?,?,?,?)", (revision_id, job_id, expected_parent, manifest["created_at"], reason, manifest_hash))
+                db.execute("UPDATE jobs SET current_revision=? WHERE id=?", (revision_id, job_id))
+                response = {"job_id": job_id, "revision_id": revision_id, "directory": str(final)}
+                db.execute("INSERT INTO requests VALUES (?,?,?)", (request_id, fp, canonical(response)))
+                return response
+            except BaseException:
+                if staging.exists():
+                    (staging / "INCOMPLETE.txt").write_text("Preparation interrupted. Not a current package. Retry with the same request.\n", encoding="utf-8")
+                    for p in staging.rglob("*"):
+                        if p.is_file() and not p.is_symlink():
+                            p.chmod(0o600)
+                raise

package/runtime/workflows/table_calculations.py

@@ -0,0 +1,132 @@
+"""Bounded local arithmetic shared by Word snapshots and Excel formulas."""
+import ast
+from copy import deepcopy
+from datetime import date
+import math
+import re
+from statistics import median
+from .store import JobError
+
+
+def calculated_table(table):
+    rows=deepcopy(table['rows']); specs=table.get('calculations',[])
+    if not isinstance(specs,list) or len(specs)>200:
+        raise JobError('A table supports up to 200 calculated cells')
+    targets={}; parsed={}; compiled={}; visiting=set(); done=set()
+    def coordinate(row,column):
+        if type(row) is not int or type(column) is not int or not 1<=row<=len(rows) or not 1<=column<=len(table['columns']):
+            raise JobError('Calculation cell is outside its table')
+        return (row-1,column-1)
+    def ref(name):
+        match=re.fullmatch(r'R([1-9]\d*)C([1-9]\d*)',name)
+        if not match:raise JobError('Use table references such as R1C2')
+        return coordinate(int(match[1]),int(match[2]))
+    def excel(key):
+        r,c=key;name='';c+=1
+        while c:c,n=divmod(c-1,26);name=chr(65+n)+name
+        return name+str(r+3)
+    for spec in specs:
+        if not isinstance(spec,dict) or set(spec)!={'row','column','expression'}:
+            raise JobError('Calculated cells need row, column and expression')
+        key=coordinate(spec['row'],spec['column'])
+        if key in targets:raise JobError('Calculation target is repeated')
+        expression=spec['expression']
+        if not isinstance(expression,str) or not 1<=len(expression)<=500:raise JobError('Calculation expression exceeds its limit')
+        try:tree=ast.parse(expression,mode='eval')
+        except (SyntaxError,ValueError,RecursionError):raise JobError('Invalid calculation expression') from None
+        if sum(1 for _ in ast.walk(tree))>100:raise JobError('Calculation is too complex')
+        targets[key]=spec;parsed[key]=tree.body
+    def evaluate(key,depth=0):
+        if key in done:return rows[key[0]][key[1]]
+        if depth>100 or key in visiting:raise JobError('Circular or excessively deep table calculation')
+        if key not in targets:return rows[key[0]][key[1]]
+        visiting.add(key);references=set();denominators=[];empty_aggregates=[];date_guards=[]
+        def walk(node,level=0):
+            if level>20:raise JobError('Calculation nesting exceeds its limit')
+            if isinstance(node,ast.Name):
+                cell=ref(node.id);references.add(cell);value=evaluate(cell,depth+1)
+                return value if type(value) in (int,float) else None,excel(cell)
+            if isinstance(node,ast.Constant) and type(node.value) in (int,float):
+                if abs(node.value)>1e15 or not math.isfinite(node.value):raise JobError('Calculation constant is outside the supported range')
+                return node.value,str(node.value)
+            if isinstance(node,ast.Call) and isinstance(node.func,ast.Name) and node.func.id=='COUNT_BETWEEN':
+                if node.keywords or len(node.args)<3 or any(not isinstance(arg,ast.Name) for arg in node.args[2:]):
+                    raise JobError('COUNT_BETWEEN needs two numeric bounds and explicit table cells')
+                bounds=node.args[:2]
+                parts=[walk(arg,level+1) for arg in bounds]
+                (lower,low_text),(upper,high_text)=parts
+                constant_bounds=all(isinstance(arg,ast.Constant) for arg in bounds)
+                if constant_bounds and lower>upper:
+                    raise JobError('COUNT_BETWEEN bounds are invalid')
+                valid=lower is not None and upper is not None and lower<=upper
+                cells=[ref(arg.id) for arg in node.args[2:]]
+                if len(set(cells))!=len(cells):raise JobError('Aggregate cell references must not repeat')
+                values=[evaluate(cell,depth+1) for cell in cells]
+                count=sum(type(v) in (int,float) and lower<=v<=upper for v in values) if valid else None
+                # ISNUMBER excludes empty/text cells, even when zero is in range.
+                terms=[f'IF(ISNUMBER({excel(cell)}),IF(AND({excel(cell)}>={low_text},{excel(cell)}<={high_text}),1,0),0)' for cell in cells]
+                return count,f'IF({low_text}<={high_text},SUM('+','.join(terms)+'),"")'
+            if isinstance(node,ast.Call) and isinstance(node.func,ast.Name) and node.func.id=='DATE':
+                if node.keywords or len(node.args)!=3 or any(not isinstance(arg,ast.Name) for arg in node.args):
+                    raise JobError('DATE needs three table cells containing year, month and day')
+                parts=[walk(arg,level+1) for arg in node.args]
+                values=[value for value,_ in parts];texts=[text for _,text in parts]
+                formula='DATE('+','.join(texts)+')';value=None
+                if all(type(v) in (int,float) and math.isfinite(v) and v==int(v) for v in values):
+                    try:
+                        calendar=date(*(int(v) for v in values))
+                        if calendar>=date(1900,3,1):value=(calendar-date(1899,12,30)).days
+                    except (ValueError,OverflowError):pass
+                # Excel DATE normalizes invalid month/day values; require exact
+                # round-trip components so an invalid date cannot shift a deadline.
+                checks=[f'{text}=INT({text})' for text in texts]
+                checks += [f'{part}({formula})={text}' for part,text in zip(('YEAR','MONTH','DAY'),texts)]
+                checks.append(f'{formula}>=61')
+                date_guards.append('AND('+','.join(checks)+')')
+                return value,formula
+            if isinstance(node,ast.Call) and isinstance(node.func,ast.Name) and node.func.id in ('SUM','COUNT','AVERAGE','MEDIAN'):
+                # Explicit cell lists only: no ranges, external references, code,
+                # keyword arguments or arbitrary nested expressions.
+                if node.keywords or not node.args or any(not isinstance(arg,ast.Name) for arg in node.args):
+                    raise JobError('Aggregate calculations need an explicit list of table cells')
+                cells=[ref(arg.id) for arg in node.args]
+                if len(set(cells))!=len(cells):raise JobError('Aggregate cell references must not repeat')
+                values=[evaluate(cell,depth+1) for cell in cells]
+                values=[value for value in values if type(value) in (int,float)]
+                args=','.join(excel(cell) for cell in cells)
+                count=len(values);name=node.func.id
+                if name=='COUNT':return count,f'COUNT({args})'
+                empty_aggregates.append(args)
+                value=(median(values) if name=='MEDIAN' else sum(values)/(count if name=='AVERAGE' else 1)) if count else None
+                if value is not None and (not math.isfinite(value) or abs(value)>1e15):
+                    raise JobError('Calculated result is outside the supported range')
+                # Empty totals stay unknown; averages exclude unknown entries.
+                # Aggregate cells deliberately bypass the scalar all-known guard.
+                return value,f'IF(COUNT({args})=0,"",{name}({args}))'
+            if isinstance(node,ast.UnaryOp) and isinstance(node.op,(ast.UAdd,ast.USub)):
+                value,text=walk(node.operand,level+1);sign='-' if isinstance(node.op,ast.USub) else '+'
+                return (None if value is None else (-value if sign=='-' else value)),f'({sign}{text})'
+            if isinstance(node,ast.BinOp) and isinstance(node.op,(ast.Add,ast.Sub,ast.Mult,ast.Div)):
+                left,a=walk(node.left,level+1);right,b=walk(node.right,level+1)
+                op={ast.Add:'+',ast.Sub:'-',ast.Mult:'*',ast.Div:'/'}[type(node.op)]
+                if op=='/':denominators.append(b)
+                value=None
+                if left is not None and right is not None and not (op=='/' and right==0):
+                    value={'+' : lambda:left+right,'-':lambda:left-right,'*':lambda:left*right,'/':lambda:left/right}[op]()
+                    if not math.isfinite(value) or abs(value)>1e15:raise JobError('Calculated result is outside the supported range')
+                return value,f'({a}{op}{b})'
+            raise JobError('Calculations allow numbers, table cells, +, -, *, /, DATE, COUNT_BETWEEN and SUM, COUNT, AVERAGE or MEDIAN of explicit table cells')
+        value,formula=walk(parsed[key])
+        # Inner divisions are checked before expressions that depend on them.
+        for denominator in reversed(denominators):formula=f'IF({denominator}=0,"",{formula})'
+        for args in empty_aggregates:formula=f'IF(COUNT({args})=0,"",{formula})'
+        for guard in date_guards:formula=f'IF({guard},{formula},"")'
+        if date_guards:formula=f'IFERROR({formula},"")'
+        if references:
+            cells=','.join(excel(k) for k in sorted(references))
+            formula=f'IF(COUNT({cells})={len(references)},{formula},"")'
+        if len(formula)>8000:raise JobError('Compiled calculation exceeds the Excel limit')
+        rows[key[0]][key[1]]=value;compiled[key]='='+formula
+        visiting.remove(key);done.add(key);return value
+    for key in targets:evaluate(key)
+    return {**table,'rows':rows},compiled