ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/storage_adapters/task_document.py

@@ -0,0 +1,484 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Compact on-disk codec for the authoritative task state document."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from dataclasses import MISSING, fields
+from typing import Any
+
+from ww.children import ChildTask
+from ww.contracts import run_is_open
+from ww.errors import ConfigurationError
+from ww.execution_models import (
+    CommandExecution,
+    ExecutionState,
+    PlanItemExecution,
+    StepProgress,
+    TaskRunAggregate,
+)
+from ww.extensions import parse_reference
+from ww.items import WorkItem
+from ww.plan import PlanItem
+from ww.validation import is_strict_int
+
+TASK_STATE_FORMAT = "ww.task-state"
+TASK_STATE_SCHEMA_VERSION = 2
+
+
+def _serialized_defaults(cls: type, **overrides: object) -> dict[str, object]:
+    """Return the serialized default of every defaulted field of a record.
+
+    The compact document omits a field whose value equals this default and
+    restores it on read, so both directions derive from the same table and
+    cannot drift from the dataclass.  Tuples serialize as lists; fields whose
+    serialized form differs from their Python default are named explicitly.
+    """
+    defaults: dict[str, object] = {}
+    for field in fields(cls):
+        if field.default is not MISSING:
+            value: object = field.default
+        elif field.default_factory is not MISSING:
+            value = field.default_factory()
+        else:
+            continue
+        defaults[field.name] = list(value) if isinstance(value, tuple) else value
+    defaults.update(overrides)
+    return defaults
+
+
+_RUN_DEFAULTS = _serialized_defaults(TaskRunAggregate)
+_PLAN_ITEM_DEFAULTS = _serialized_defaults(PlanItem)
+_ITEM_EXECUTION_DEFAULTS = _serialized_defaults(
+    PlanItemExecution, supplied_values={}, output_values={}
+)
+_COMMAND_DEFAULTS = _serialized_defaults(CommandExecution)
+_STEP_DEFAULTS = _serialized_defaults(StepProgress)
+# ``modes`` and ``active_item_id`` have no dataclass default, yet the writer
+# has always omitted an empty mode list and a missing active item.
+_STATE_DEFAULTS = _serialized_defaults(
+    ExecutionState,
+    modes=[],
+    active_item_id=None,
+    workflow_values={},
+    loop_iterations={},
+    pending_task_metadata={},
+)
+_WORK_ITEM_DEFAULTS = _serialized_defaults(WorkItem)
+_CHILD_DEFAULTS = _serialized_defaults(ChildTask, fields={})
+_LEDGER_EVENT_DEFAULTS: dict[str, object] = {"summary": None}
+
+_EXTENSION_SNAPSHOT_FIELDS = (
+    "version",
+    "api_version",
+    "source",
+    "fingerprint",
+    "settings",
+)
+
+
+def encode_task_document(
+    task_id: str,
+    runs: tuple[TaskRunAggregate, ...],
+    handoff: str | None,
+    revision: int,
+    ledger: dict[str, list[dict[str, object]]],
+) -> dict[str, object]:
+    """Encode expanded domain records without mutating them."""
+    snapshots: dict[str, dict[str, object]] = {}
+    encoded_runs = [
+        _compact_run(copy.deepcopy(run.to_dict()), snapshots) for run in runs
+    ]
+    active = [run.run_id for run in runs if run_is_open(run.state.status)]
+    if len(active) > 1:
+        raise ValueError("task state has multiple active runs")
+    result: dict[str, object] = {
+        "format": TASK_STATE_FORMAT,
+        "schema_version": TASK_STATE_SCHEMA_VERSION,
+        "task_id": task_id,
+        "revision": revision,
+        "active_run": active[0] if active else None,
+        "runs": encoded_runs,
+    }
+    if snapshots:
+        result["extension_snapshots"] = snapshots
+    if handoff is not None:
+        result["handoff"] = handoff
+    if ledger:
+        result["ledger"] = _compact_ledger(copy.deepcopy(ledger))
+    return result
+
+
+def decode_task_document(
+    data: object, task_id: str
+) -> tuple[
+    tuple[TaskRunAggregate, ...],
+    str | None,
+    int,
+    dict[str, list[dict[str, object]]],
+]:
+    """Expand a compact task document and invoke the strict domain decoders."""
+    if not isinstance(data, dict):
+        raise ValueError("task state must be a mapping")
+    if data.get("format") != TASK_STATE_FORMAT:
+        raise ValueError(f"unsupported task state format: {data.get('format')!r}")
+    version = data.get("schema_version")
+    if not is_strict_int(version) or version != TASK_STATE_SCHEMA_VERSION:
+        raise ValueError("unsupported task state schema")
+    if data.get("task_id") != task_id:
+        raise ValueError("task state task ID does not match its path")
+    revision = data.get("revision")
+    if not is_strict_int(revision) or revision < 0:
+        raise ValueError("task state revision must be non-negative")
+    if "active_run" not in data:
+        raise ValueError("task state missing field: active_run")
+    active_run = data["active_run"]
+    if active_run is not None and not isinstance(active_run, str):
+        raise ValueError("task state active_run must be a string or null")
+    raw_runs = data.get("runs")
+    if not isinstance(raw_runs, list):
+        raise ValueError("task state runs must be a list")
+    raw_snapshots = data.get("extension_snapshots", {})
+    snapshots = _validate_extension_snapshots(raw_snapshots)
+    runs = tuple(
+        TaskRunAggregate.from_dict(_expand_run(copy.deepcopy(run), snapshots))
+        for run in raw_runs
+    )
+    actual_active = [run.run_id for run in runs if run_is_open(run.state.status)]
+    if len(actual_active) > 1:
+        raise ValueError("task state has multiple active runs")
+    expected_active = actual_active[0] if actual_active else None
+    if active_run != expected_active:
+        raise ValueError("task state active_run does not match the non-completed run")
+    handoff = data.get("handoff")
+    if handoff is not None and not isinstance(handoff, str):
+        raise ValueError("task state handoff must be a string or null")
+    ledger = data.get("ledger", {})
+    if not isinstance(ledger, dict):
+        raise ValueError("task state ledger must be a mapping")
+    return runs, handoff, revision, _expand_ledger(copy.deepcopy(ledger))
+
+
+def _compact_run(
+    run: dict[str, Any], snapshots: dict[str, dict[str, object]]
+) -> dict[str, Any]:
+    snapshot = run["snapshot"]
+    _compact_snapshot(snapshot, snapshots)
+    _compact_state(run["state"])
+    for item in run.get("items", []):
+        _omit_defaults(item, _WORK_ITEM_DEFAULTS)
+    for child in run.get("children", []):
+        _omit_defaults(child, _CHILD_DEFAULTS)
+    _omit_defaults(run, _RUN_DEFAULTS)
+    return run
+
+
+def _compact_snapshot(
+    snapshot: dict[str, Any], snapshots: dict[str, dict[str, object]]
+) -> None:
+    plan = snapshot["plan"]
+    if snapshot.get("template_plan") == plan:
+        snapshot.pop("template_plan", None)
+    _compact_plan(plan, snapshots)
+    template = snapshot.get("template_plan")
+    if template is not None:
+        _compact_plan(template, snapshots)
+        _diff_against_templates(plan, template)
+
+
+def _compact_plan(
+    plan: dict[str, Any], snapshots: dict[str, dict[str, object]]
+) -> None:
+    for item in plan["items"]:
+        operation = item["operation"]
+        if operation["type"] == "action" and operation["identifier"] == "extension":
+            payload = operation["payload"]
+            reference = payload.get("reference")
+            if not isinstance(reference, str):
+                raise ValueError("extension plan item requires a reference")
+            identifier = _extension_identifier(reference)
+            entry: dict[str, object] = {"identifier": identifier}
+            for field in _EXTENSION_SNAPSHOT_FIELDS:
+                entry[field] = copy.deepcopy(payload.pop(field))
+            snapshot_id = _snapshot_id(entry)
+            existing = snapshots.get(snapshot_id)
+            if existing is not None and existing != entry:
+                raise ValueError("extension snapshot hash collision")
+            snapshots[snapshot_id] = entry
+            payload["snapshot"] = snapshot_id
+        _omit_defaults(item, _PLAN_ITEM_DEFAULTS)
+
+
+def _diff_against_templates(plan: dict[str, Any], template: dict[str, Any]) -> None:
+    """Store each plan item as the fields that differ from its template item.
+
+    The diff runs on items already compacted, so a field equal in both is
+    omitted either way.  A field the item leaves at its default while the
+    template sets it is written out with the default, since the reader starts
+    from the template item.  An item with no template item is stored in full.
+    """
+    templates = {item["id"]: item for item in template["items"]}
+    compacted: list[dict[str, Any]] = []
+    for item in plan["items"]:
+        template_id = _template_id(item["id"], templates)
+        if template_id is None:
+            compacted.append(item)
+            continue
+        source = templates[template_id]
+        diff: dict[str, Any] = {"id": item["id"], "template": template_id}
+        for name, value in item.items():
+            if name != "id" and source.get(name, MISSING) != value:
+                diff[name] = value
+        for name in source:
+            if name not in item:
+                diff[name] = copy.deepcopy(_PLAN_ITEM_DEFAULTS[name])
+        compacted.append(diff)
+    plan["items"] = compacted
+
+
+def _template_id(item_id: str, templates: dict[str, Any]) -> str | None:
+    """Return the template item an item was expanded from, if any.
+
+    An item keeps its template item's ID, or extends it with a suffix such
+    as ``:item:<item id>`` or ``:child:<number>``; the longest such prefix
+    wins, so an expansion of an expansion finds its nearest template item.
+    """
+    if item_id in templates:
+        return item_id
+    prefixes = [
+        template_id
+        for template_id in templates
+        if item_id.startswith(template_id + ":")
+    ]
+    return max(prefixes, key=len, default=None)
+
+
+def _compact_state(state: dict[str, Any]) -> None:
+    for item in [*state["item_executions"], *state["execution_history"]]:
+        for command in item["commands"]:
+            _omit_defaults(command, _COMMAND_DEFAULTS)
+        _omit_defaults(item, _ITEM_EXECUTION_DEFAULTS)
+    for step in state["steps"]:
+        _compact_step(step)
+    _omit_defaults(state, _STATE_DEFAULTS)
+
+
+def _compact_step(step: dict[str, Any]) -> None:
+    for child in step["children"]:
+        _compact_step(child)
+    _omit_defaults(step, _STEP_DEFAULTS)
+
+
+def _expand_run(run: object, snapshots: dict[str, dict[str, object]]) -> dict[str, Any]:
+    if not isinstance(run, dict):
+        raise ValueError("run must be a mapping")
+    _add_defaults(run, _RUN_DEFAULTS)
+    snapshot = run.get("snapshot")
+    if not isinstance(snapshot, dict):
+        raise ValueError("run.snapshot must be a mapping")
+    _expand_snapshot(snapshot, snapshots)
+    state = run.get("state")
+    if not isinstance(state, dict):
+        raise ValueError("run.state must be a mapping")
+    _expand_state(state)
+    for item in _list(run["items"], "run.items"):
+        if not isinstance(item, dict):
+            raise ValueError("run.items entries must be mappings")
+        _add_defaults(item, _WORK_ITEM_DEFAULTS)
+    for child in _list(run["children"], "run.children"):
+        if not isinstance(child, dict):
+            raise ValueError("run.children entries must be mappings")
+        _add_defaults(child, _CHILD_DEFAULTS)
+    return run
+
+
+def _expand_snapshot(
+    snapshot: dict[str, Any], snapshots: dict[str, dict[str, object]]
+) -> None:
+    plan = snapshot.get("plan")
+    if not isinstance(plan, dict):
+        raise ValueError("plan snapshot.plan must be a mapping")
+    template = snapshot.get("template_plan")
+    if template is not None and not isinstance(template, dict):
+        raise ValueError("plan snapshot.template_plan must be a mapping")
+    _restore_from_templates(plan, template)
+    _expand_plan(plan, snapshots)
+    if template is None:
+        snapshot["template_plan"] = copy.deepcopy(plan)
+    else:
+        _expand_plan(template, snapshots)
+
+
+def _restore_from_templates(
+    plan: dict[str, Any], template: dict[str, Any] | None
+) -> None:
+    """Rebuild each plan item stored as a diff against its template item."""
+    templates: dict[str, dict[str, Any]] = {}
+    if template is not None:
+        for item in _list(template.get("items"), "template_plan.items"):
+            if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+                raise ValueError("template_plan.items entries must be mappings")
+            templates[item["id"]] = item
+    restored: list[Any] = []
+    for item in _list(plan.get("items"), "plan.items"):
+        if not isinstance(item, dict) or "template" not in item:
+            restored.append(item)
+            continue
+        template_id = item.pop("template")
+        source = templates.get(template_id) if isinstance(template_id, str) else None
+        if source is None:
+            raise ValueError(f"plan item names an unknown template: {template_id!r}")
+        restored.append({**copy.deepcopy(source), **item})
+    plan["items"] = restored
+
+
+def _expand_plan(plan: dict[str, Any], snapshots: dict[str, dict[str, object]]) -> None:
+    for item in _list(plan.get("items"), "plan.items"):
+        if not isinstance(item, dict):
+            raise ValueError("plan.items entries must be mappings")
+        _add_defaults(item, _PLAN_ITEM_DEFAULTS)
+        operation = item.get("operation")
+        if not isinstance(operation, dict):
+            raise ValueError("plan item operation must be a mapping")
+        if operation.get("type") != "action":
+            continue
+        payload = operation.get("payload")
+        if not isinstance(payload, dict):
+            raise ValueError("plan action payload must be a mapping")
+        # Snapshot indirection belongs exclusively to extension payloads.
+        # Other registered actions may freely use a field named ``snapshot``.
+        if operation.get("identifier") != "extension":
+            continue
+        inline = set(payload) & set(_EXTENSION_SNAPSHOT_FIELDS)
+        has_snapshot = "snapshot" in payload
+        snapshot_id = payload.pop("snapshot", None)
+        if inline and has_snapshot:
+            raise ValueError("extension item has conflicting inline snapshot fields")
+        if not has_snapshot:
+            raise ValueError("extension plan item missing extension_snapshot")
+        if not isinstance(snapshot_id, str):
+            raise ValueError("extension_snapshot must be a string")
+        entry = snapshots.get(snapshot_id)
+        if entry is None:
+            raise ValueError(f"unknown extension snapshot: {snapshot_id!r}")
+        reference = payload.get("reference")
+        if not isinstance(reference, str):
+            raise ValueError("extension plan item requires a reference")
+        if _extension_identifier(reference) != entry["identifier"]:
+            raise ValueError("extension snapshot identifier does not match reference")
+        for field in _EXTENSION_SNAPSHOT_FIELDS:
+            payload[field] = copy.deepcopy(entry[field])
+
+
+def _expand_state(state: dict[str, Any]) -> None:
+    _add_defaults(state, _STATE_DEFAULTS)
+    for field in ("item_executions", "execution_history"):
+        for item in _list(state.get(field), f"state.{field}"):
+            if not isinstance(item, dict):
+                raise ValueError(f"state.{field} entries must be mappings")
+            _add_defaults(item, _ITEM_EXECUTION_DEFAULTS)
+            for command in _list(item["commands"], f"{field}.commands"):
+                if not isinstance(command, dict):
+                    raise ValueError("command execution must be a mapping")
+                _add_defaults(command, _COMMAND_DEFAULTS)
+    for step in _list(state.get("steps"), "state.steps"):
+        _expand_step(step)
+
+
+def _expand_step(step: object) -> None:
+    if not isinstance(step, dict):
+        raise ValueError("step progress must be a mapping")
+    _add_defaults(step, _STEP_DEFAULTS)
+    for child in _list(step["children"], "step.children"):
+        _expand_step(child)
+
+
+def _validate_extension_snapshots(value: object) -> dict[str, dict[str, object]]:
+    if not isinstance(value, dict):
+        raise ValueError("extension_snapshots must be a mapping")
+    result: dict[str, dict[str, object]] = {}
+    required = {
+        "identifier",
+        "version",
+        "api_version",
+        "source",
+        "fingerprint",
+        "settings",
+    }
+    for snapshot_id, raw in value.items():
+        if not isinstance(snapshot_id, str) or not isinstance(raw, dict):
+            raise ValueError("extension snapshot entries are invalid")
+        if not required <= set(raw):
+            raise ValueError("extension snapshot has invalid fields")
+        if not isinstance(raw["identifier"], str):
+            raise ValueError("extension snapshot identifier must be a string")
+        for name in ("version", "source", "fingerprint"):
+            if raw[name] is not None and not isinstance(raw[name], str):
+                raise ValueError(f"extension snapshot {name} must be a string or null")
+        if raw["api_version"] is not None and not is_strict_int(raw["api_version"]):
+            raise ValueError(
+                "extension snapshot api_version must be an integer or null"
+            )
+        if raw["settings"] is not None and not isinstance(raw["settings"], dict):
+            raise ValueError("extension snapshot settings must be a mapping or null")
+        entry = copy.deepcopy(raw)
+        if _snapshot_id(entry) != snapshot_id:
+            raise ValueError("extension snapshot content hash does not match its ID")
+        result[snapshot_id] = entry
+    return result
+
+
+def _compact_ledger(
+    ledger: dict[str, list[dict[str, object]]],
+) -> dict[str, list[dict[str, object]]]:
+    for events in ledger.values():
+        for event in events:
+            _omit_defaults(event, _LEDGER_EVENT_DEFAULTS)
+    return ledger
+
+
+def _expand_ledger(value: dict[object, object]) -> dict[str, list[dict[str, object]]]:
+    result: dict[str, list[dict[str, object]]] = {}
+    for run_id, events in value.items():
+        if not isinstance(run_id, str) or not isinstance(events, list):
+            raise ValueError("task state ledger entries are invalid")
+        expanded: list[dict[str, object]] = []
+        for event in events:
+            if not isinstance(event, dict):
+                raise ValueError("task state ledger events must be mappings")
+            _add_defaults(event, _LEDGER_EVENT_DEFAULTS)
+            expanded.append(event)
+        result[run_id] = expanded
+    return result
+
+
+def _snapshot_id(entry: dict[str, object]) -> str:
+    canonical = json.dumps(entry, sort_keys=True, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _extension_identifier(reference: str) -> str:
+    try:
+        return parse_reference(reference).identifier
+    except ConfigurationError as error:
+        raise ValueError(str(error)) from error
+
+
+def _omit_defaults(mapping: dict[str, Any], defaults: dict[str, object]) -> None:
+    for name, default in defaults.items():
+        if name in mapping and mapping[name] == default:
+            mapping.pop(name)
+
+
+def _add_defaults(mapping: dict[str, Any], defaults: dict[str, object]) -> None:
+    for name, default in defaults.items():
+        if name not in mapping:
+            mapping[name] = copy.deepcopy(default)
+
+
+def _list(value: object, context: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise ValueError(f"{context} must be a list")
+    return value

ww/task_ids.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Task identity policy: validation, generation, and claim checks."""
+
+from __future__ import annotations
+
+import itertools
+import re
+import uuid
+from collections.abc import Iterator
+from datetime import datetime, timezone
+
+from ww.contracts import BOOTSTRAP_REQUEST_PREFIX
+from ww.errors import StateError
+from ww.extensions import ExtensionRegistry
+from ww.project_config import EXPLICIT_TASK_FORMAT
+from ww.storage_adapters import TaskStorageAdapter
+
+GENERATED_TASK_PREFIX = "TASK-"
+# A task ID is ``parent`` or ``parent/child``; deeper nesting is unsupported.
+MAX_TASK_ID_SEGMENTS = 2
+# Suffixed candidates tried for a template without a ``{{digit}}`` counter.
+ID_ATTEMPT_LIMIT = 50
+# One task ID segment, e.g. "TASK-12" or "FOOBAR_1.2"; "TASK 12" does not match.
+_SEGMENT = re.compile(r"[A-Za-z0-9._-]+")
+
+
+def validate_task_id(task_id: str) -> None:
+    segments = task_id.split("/")
+    if (
+        not task_id
+        or len(segments) > MAX_TASK_ID_SEGMENTS
+        or any(
+            segment in {".", ".."} or not _SEGMENT.fullmatch(segment)
+            for segment in segments
+        )
+    ):
+        raise StateError(
+            "invalid task ID; use one or two slash-separated normalized names"
+        )
+
+
+def validate_child_id(child_id: str) -> None:
+    validate_task_id(child_id)
+    if "/" in child_id:
+        raise StateError("child ID must be a single normalized name")
+
+
+def is_bootstrap_request(task_id: str) -> bool:
+    return task_id.startswith(BOOTSTRAP_REQUEST_PREFIX)
+
+
+def generated_task_id(task_format: str | None = None) -> str:
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+    if task_format is None:
+        return GENERATED_TASK_PREFIX + timestamp
+    return task_format.replace("{{timestamp}}", timestamp).replace(
+        "{{uuid}}", str(uuid.uuid4())
+    )
+
+
+def generated_bootstrap_id() -> str:
+    return BOOTSTRAP_REQUEST_PREFIX + datetime.now(timezone.utc).strftime(
+        "%Y%m%d%H%M%S%f"
+    )
+
+
+def candidate_task_ids(task_format: str | None) -> Iterator[str]:
+    """Yield IDs to try, in order, for a generated task.
+
+    Generated IDs are second-resolution, so two starts in the same second
+    would otherwise collide.  A template with ``{{digit}}`` counts upward
+    without limit; any other template tries the base name and then a bounded
+    number of numeric suffixes.  The ``explicit`` format yields nothing.
+    """
+    if task_format == EXPLICIT_TASK_FORMAT:
+        raise StateError(
+            "this project requires an explicit task ID (task_format: explicit); "
+            "pass the external key, such as the tracker issue key, to start"
+        )
+    base = generated_task_id(task_format)
+    if task_format is not None and "{{digit}}" in task_format:
+        for attempt in itertools.count(1):
+            yield base.replace("{{digit}}", str(attempt))
+        return
+    yield base
+    for attempt in range(2, ID_ATTEMPT_LIMIT + 1):
+        yield f"{base}-{attempt}"
+
+
+def task_id_claimed(
+    task_id: str,
+    *,
+    tasks: TaskStorageAdapter,
+    extensions: ExtensionRegistry,
+    workflow_name: str | None = None,
+    project: str | None = None,
+    lane: str | None = None,
+) -> bool:
+    """Return whether task state or an extension already claims ``task_id``.
+
+    An extension's artefact (for example a Git worktree) or record (for
+    example a Git branch record) can outlive the task state it belonged to.
+    Extensions report such paths and claims themselves, so core needs no
+    knowledge of any one extension's settings; a task starting in a
+    configured project asks under that project's settings.
+    """
+    if tasks.task_exists(task_id):
+        return True
+    if any(
+        path.exists()
+        for path in extensions.reserved_paths(task_id, workflow_name, project, lane)
+    ):
+        return True
+    return extensions.claims_task(task_id, workflow_name, project, lane)