agent-lifecycle-kit 2.9.0__tar.gz → 2.10.0__tar.gz

{agent_lifecycle_kit-2.9.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.9.0
+Version: 2.10.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -43,7 +43,7 @@ ALK provides a verifiable finish for external-agent work with proportionate cont
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.9.0`, and common `agent-lifecycle version` errors.
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.10.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/README.md

@@ -21,7 +21,7 @@ ALK provides a verifiable finish for external-agent work with proportionate cont
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.9.0`, and common `agent-lifecycle version` errors.
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.10.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.9.0"
+version = "2.10.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
@@ -41,9 +41,9 @@ dependencies = []
 
 [dependency-groups]
 quality = [
-  "ruff==0.16.3",
-  "mypy==1.17.1",
-  "coverage==7.10.6",
+  "ruff==0.16.5",
+  "mypy==2.3.1",
+  "coverage==7.15.4",
 ]
 
 [project.scripts]

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.9.0"
+__version__ = "2.10.0"

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/src/agent_lifecycle/cli/dispatch_lifecycle.py

@@ -32,6 +32,7 @@ from agent_lifecycle.workflow import (
     block_run,
     commit_task_result,
     continue_workflow,
+    continue_workflow_batch,
     finalize_run,
     initialize_workflow_state,
     migrate_workflow_state,
@@ -107,22 +108,7 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
         maybe_emit_workflow_progress_hook(args, command="workflow run", state_path=state_path)
         return payload
     if args.workflow_command == "continue":
-        payload = continue_workflow(
-            state_path=state_path,
-            manifest_path=Path(args.manifest),
-            lock_path=Path(args.lock) if args.lock else None,
-            operation_id=args.operation_id,
-            expected_revision=args.expected_revision,
-            source_revision=args.source_revision,
-            reason=args.reason,
-            apply=args.apply,
-            projected_state_revision=args.projected_state_revision,
-            projected_action_digest=args.projected_action_digest,
-            inputs=_continuation_inputs(args),
-        )
-        if args.out:
-            write_json_create(Path(args.out), payload)
-        return payload
+        return _dispatch_workflow_continue(args, state_path)
     if args.workflow_command == "adopt-plan":
         return adopt_plan(
             state_path,
@@ -343,6 +329,82 @@ def _require_args(args: argparse.Namespace, names: list[str], *, mode: str) -> N
         raise LifecycleError("missing-cli-argument", f"{mode} requires arguments", {"missing": missing})
 
 
+def _dispatch_workflow_continue(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
+    batch_options = (args.input_bundle, args.max_transitions, args.max_io_bytes, args.resume_receipt)
+    if not args.until_blocked:
+        if any(value is not None for value in batch_options):
+            raise LifecycleError(
+                "continuation-batch-option-conflict",
+                "bounded continuation options require --until-blocked",
+            )
+        if not args.operation_id:
+            raise LifecycleError(
+                "continuation-one-step-operation-id-required",
+                "one-step continuation requires --operation-id",
+            )
+        payload = continue_workflow(
+            state_path=state_path,
+            manifest_path=Path(args.manifest),
+            lock_path=Path(args.lock) if args.lock else None,
+            operation_id=args.operation_id,
+            expected_revision=args.expected_revision,
+            source_revision=args.source_revision,
+            reason=args.reason,
+            apply=args.apply,
+            projected_state_revision=args.projected_state_revision,
+            projected_action_digest=args.projected_action_digest,
+            inputs=_continuation_inputs(args),
+        )
+        if args.out:
+            write_json_create(Path(args.out), payload)
+        return payload
+    if not args.apply:
+        raise LifecycleError(
+            "continuation-batch-apply-required",
+            "bounded continuation requires --apply",
+        )
+    if (
+        args.operation_id is not None
+        or args.projected_state_revision is not None
+        or args.projected_action_digest is not None
+    ):
+        raise LifecycleError(
+            "continuation-batch-option-conflict",
+            "bounded continuation cannot use singular operation or projection options",
+        )
+    if _continuation_inputs(args):
+        raise LifecycleError(
+            "continuation-batch-option-conflict",
+            "bounded continuation inputs must come from --input-bundle",
+        )
+    required = ("lock", "input_bundle", "max_transitions", "max_io_bytes", "out")
+    missing = [name.replace("_", "-") for name in required if getattr(args, name) is None or getattr(args, name) == ""]
+    if missing:
+        raise LifecycleError(
+            "continuation-batch-arguments-required",
+            "bounded continuation requires explicit lock, bundle, caps and output",
+            {"missing": missing},
+        )
+    if args.max_transitions <= 0 or args.max_io_bytes <= 0:
+        raise LifecycleError(
+            "continuation-batch-cap-invalid",
+            "bounded continuation caps must be positive",
+        )
+    return continue_workflow_batch(
+        state_path=state_path,
+        manifest_path=Path(args.manifest),
+        lock_path=Path(args.lock),
+        input_bundle_path=args.input_bundle,
+        output_path=args.out,
+        max_transitions=args.max_transitions,
+        max_io_bytes=args.max_io_bytes,
+        expected_revision=args.expected_revision,
+        source_revision=args.source_revision,
+        reason=args.reason,
+        resume_receipt_path=args.resume_receipt,
+    )
+
+
 def _continuation_inputs(args: argparse.Namespace) -> dict[str, Any]:
     singular = {
         "taskId": args.task,

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/src/agent_lifecycle/cli/lifecycle_parsers.py

@@ -511,55 +511,26 @@ def _add_task_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPar
     small_compile.add_argument("--write", action="store_true")
 
 
-def _add_workflow_state_parsers(
+def _add_workflow_continue_parser(
     workflow_sub: argparse._SubParsersAction[argparse.ArgumentParser],
 ) -> None:
-    workflow_init = workflow_sub.add_parser("init")
-    workflow_init.add_argument("--state", required=True)
-    workflow_init.add_argument("--run-id", required=True)
-    workflow_init.add_argument("--package-id", required=True)
-    workflow_init.add_argument("--package-root", default=".")
-    workflow_init.add_argument("--event-log", default="events.jsonl")
-    workflow_migrate = workflow_sub.add_parser("state-migrate")
-    workflow_migrate.add_argument("--state", required=True)
-    workflow_migrate.add_argument("--operation-id", required=True)
-    workflow_migrate.add_argument("--expected-revision", required=True, type=int)
-    workflow_migrate.add_argument("--source-revision", required=True)
-    workflow_legacy = workflow_sub.add_parser(
-        "migrate-runner-artifact",
-        help="convert one legacy runner artifact into a non-authoritative archival record",
-    )
-    workflow_legacy.add_argument("--input", required=True)
-    workflow_legacy.add_argument("--output", "--out", dest="output", required=True)
-    workflow_legacy.add_argument("--expected-sha256")
-    workflow_legacy.add_argument("--max-input-bytes", type=int, default=1_048_576)
-    workflow_status = workflow_sub.add_parser("status")
-    workflow_status.add_argument("--state", required=True)
-    workflow_status.add_argument("--full", action="store_true")
-    workflow_next = workflow_sub.add_parser("next")
-    workflow_next.add_argument("--state", required=True)
-    workflow_run = workflow_sub.add_parser("run")
-    workflow_run.add_argument("--state", required=True)
-    workflow_run.add_argument("--manifest", required=True)
-    workflow_run.add_argument("--lock")
-    workflow_run.add_argument("--operation-id", required=True)
-    workflow_run.add_argument("--expected-revision", required=True, type=int)
-    workflow_run.add_argument("--source-revision", required=True)
-    workflow_run.add_argument("--reason")
-    workflow_run.add_argument("--out")
-    add_progress_hook_args(workflow_run)
     workflow_continue = workflow_sub.add_parser(
         "continue",
-        help="project or explicitly apply one authoritative workflow transition",
+        help="project or explicitly apply existing authoritative workflow transitions",
     )
     workflow_continue.add_argument("--state", required=True)
     workflow_continue.add_argument("--manifest", required=True)
     workflow_continue.add_argument("--lock")
-    workflow_continue.add_argument("--operation-id", required=True)
+    workflow_continue.add_argument("--operation-id")
     workflow_continue.add_argument("--expected-revision", required=True, type=int)
     workflow_continue.add_argument("--source-revision", required=True)
     workflow_continue.add_argument("--reason", required=True)
     workflow_continue.add_argument("--apply", action="store_true")
+    workflow_continue.add_argument("--until-blocked", action="store_true")
+    workflow_continue.add_argument("--input-bundle")
+    workflow_continue.add_argument("--max-transitions", type=int)
+    workflow_continue.add_argument("--max-io-bytes", type=int)
+    workflow_continue.add_argument("--resume-receipt")
     workflow_continue.add_argument("--projected-state-revision", type=int)
     workflow_continue.add_argument("--projected-action-digest")
     workflow_continue.add_argument("--task")
@@ -585,6 +556,46 @@ def _add_workflow_state_parsers(
     workflow_continue.add_argument("--final-implementation-audit")
     workflow_continue.add_argument("--review-mesh-quorum", action="append", default=[])
     workflow_continue.add_argument("--out")
+
+
+def _add_workflow_state_parsers(
+    workflow_sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    workflow_init = workflow_sub.add_parser("init")
+    workflow_init.add_argument("--state", required=True)
+    workflow_init.add_argument("--run-id", required=True)
+    workflow_init.add_argument("--package-id", required=True)
+    workflow_init.add_argument("--package-root", default=".")
+    workflow_init.add_argument("--event-log", default="events.jsonl")
+    workflow_migrate = workflow_sub.add_parser("state-migrate")
+    workflow_migrate.add_argument("--state", required=True)
+    workflow_migrate.add_argument("--operation-id", required=True)
+    workflow_migrate.add_argument("--expected-revision", required=True, type=int)
+    workflow_migrate.add_argument("--source-revision", required=True)
+    workflow_legacy = workflow_sub.add_parser(
+        "migrate-runner-artifact",
+        help="convert one legacy runner artifact into a non-authoritative archival record",
+    )
+    workflow_legacy.add_argument("--input", required=True)
+    workflow_legacy.add_argument("--output", "--out", dest="output", required=True)
+    workflow_legacy.add_argument("--expected-sha256")
+    workflow_legacy.add_argument("--max-input-bytes", type=int, default=1_048_576)
+    workflow_status = workflow_sub.add_parser("status")
+    workflow_status.add_argument("--state", required=True)
+    workflow_status.add_argument("--full", action="store_true")
+    workflow_next = workflow_sub.add_parser("next")
+    workflow_next.add_argument("--state", required=True)
+    workflow_run = workflow_sub.add_parser("run")
+    workflow_run.add_argument("--state", required=True)
+    workflow_run.add_argument("--manifest", required=True)
+    workflow_run.add_argument("--lock")
+    workflow_run.add_argument("--operation-id", required=True)
+    workflow_run.add_argument("--expected-revision", required=True, type=int)
+    workflow_run.add_argument("--source-revision", required=True)
+    workflow_run.add_argument("--reason")
+    workflow_run.add_argument("--out")
+    add_progress_hook_args(workflow_run)
+    _add_workflow_continue_parser(workflow_sub)
     workflow_adopt = workflow_sub.add_parser("adopt-plan")
     workflow_adopt.add_argument("--state", required=True)
     workflow_adopt.add_argument("--manifest", required=True)

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.10.0}/src/agent_lifecycle/contracts/schemas.py

@@ -86,7 +86,9 @@ from agent_lifecycle.contracts.thread_bridge_schemas import THREAD_BRIDGE_SCHEMA
 from agent_lifecycle.contracts.usage_export_schemas import USAGE_EXPORT_SCHEMAS
 from agent_lifecycle.contracts.workflow_artifact_schemas import WORKFLOW_ARTIFACT_SCHEMAS
 from agent_lifecycle.contracts.workflow_authorization_schemas import WORKFLOW_AUTHORIZATION_SCHEMAS
+from agent_lifecycle.contracts.workflow_continuation_batch_schemas import WORKFLOW_CONTINUATION_BATCH_SCHEMAS
 from agent_lifecycle.contracts.workflow_continuation_schemas import WORKFLOW_CONTINUATION_SCHEMAS
+from agent_lifecycle.contracts.workflow_economics_schemas import WORKFLOW_ECONOMICS_SCHEMAS
 from agent_lifecycle.contracts.workflow_run_schemas import WORKFLOW_RUN_SCHEMAS
 from agent_lifecycle.contracts.workflow_state_schemas import WORKFLOW_STATE_SCHEMAS
 
@@ -734,7 +736,9 @@ _SCHEMA_GROUPS = (
     WORKTREE_SUPPORT_SCHEMAS,
     WORKFLOW_ARTIFACT_SCHEMAS,
     WORKFLOW_AUTHORIZATION_SCHEMAS,
+    WORKFLOW_CONTINUATION_BATCH_SCHEMAS,
     WORKFLOW_CONTINUATION_SCHEMAS,
+    WORKFLOW_ECONOMICS_SCHEMAS,
     WORKFLOW_STATE_SCHEMAS,
     BUG_FORENSICS_SCHEMAS,
     SECURITY_ANALYSIS_SCHEMAS,

agent_lifecycle_kit-2.10.0/src/agent_lifecycle/contracts/workflow_continuation_batch_schemas.py

@@ -0,0 +1,297 @@
+"""Schemas for bounded, projection-first workflow continuation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts.canonical import canonical_digest
+from agent_lifecycle.contracts.errors import LifecycleError
+from agent_lifecycle.contracts.paths import normalize_repo_path
+from agent_lifecycle.contracts.schema_builders import open_object_schema
+
+MAX_CONTINUATION_BATCH_STEPS = 128
+CONTINUATION_BATCH_STOP_REASONS = (
+    "TERMINAL",
+    "INPUT_REQUIRED",
+    "WAITING",
+    "BLOCKED",
+    "AUDIT_REQUIRED",
+    "HUMAN_DECISION_REQUIRED",
+    "BUDGET_DECISION_REQUIRED",
+    "EXTERNAL_ACTION_REQUIRED",
+    "PLAN_AUTHORITY_REQUIRED",
+    "CAP_TRANSITIONS",
+    "CAP_BYTES",
+    "STALE_BUNDLE_ENTRY",
+    "RETRY_PROOF_REQUIRED",
+    "RETRY_PROOF_MISMATCH",
+)
+
+_DIGEST = {"type": "string", "minLength": 64, "maxLength": 64}
+_BLOCKERS = {"type": "array", "items": {"type": "object"}, "maxItems": 64}
+_REQUIRED_INPUTS = {"type": "array", "items": {"type": "object"}, "maxItems": 32}
+
+
+def _closed_object_schema(
+    schema_id: str,
+    *,
+    required: list[str],
+    properties: dict[str, Any],
+) -> dict[str, Any]:
+    schema = open_object_schema(schema_id, required=required, properties=properties)
+    schema["additionalProperties"] = False
+    return schema
+
+
+WORKFLOW_CONTINUATION_BATCH_SCHEMAS: dict[str, dict[str, Any]] = {
+    "agent-workflow-continuation-input-bundle.v1": _closed_object_schema(
+        "agent-workflow-continuation-input-bundle.v1",
+        required=["schemaVersion", "runId", "packageId", "planDigest", "sourceRevision", "steps"],
+        properties={
+            "runId": {"type": "string", "minLength": 1, "maxLength": 256},
+            "packageId": {"type": "string", "minLength": 1, "maxLength": 256},
+            "planDigest": _DIGEST,
+            "sourceRevision": {"type": "string", "minLength": 1, "maxLength": 4096},
+            "steps": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": MAX_CONTINUATION_BATCH_STEPS,
+                "items": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "required": ["operationId", "expectedActionType", "inputs"],
+                    "properties": {
+                        "operationId": {"type": "string", "minLength": 1, "maxLength": 256},
+                        "expectedActionType": {"type": "string", "minLength": 1, "maxLength": 128},
+                        "inputs": {"type": "object"},
+                    },
+                },
+            },
+        },
+    ),
+    "agent-workflow-continuation-batch-receipt.v1": open_object_schema(
+        "agent-workflow-continuation-batch-receipt.v1",
+        required=[
+            "schemaVersion",
+            "status",
+            "stopReason",
+            "receiptPath",
+            "bundle",
+            "lineage",
+            "limits",
+            "inputBytes",
+            "outputBytes",
+            "steps",
+            "appliedCount",
+            "alreadyAppliedCount",
+            "lastAppliedOperationId",
+            "finalState",
+            "nextCommand",
+            "requiredInputs",
+            "blockers",
+            "modelCallsStarted",
+            "hostLaunchStarted",
+            "productionPromotionClaimed",
+            "receiptDigest",
+        ],
+        properties={
+            "status": {"enum": ["IN_PROGRESS", "STOPPED", "COMPLETE"]},
+            "stopReason": {"type": ["string", "null"], "enum": [None, *CONTINUATION_BATCH_STOP_REASONS]},
+            "receiptPath": {"type": "string", "minLength": 1, "maxLength": 4096},
+            "bundle": {"type": ["object", "null"]},
+            "lineage": {"type": ["object", "null"]},
+            "limits": {"type": "object"},
+            "inputBytes": {"type": "integer", "minimum": 0},
+            "outputBytes": {"type": "integer", "minimum": 0},
+            "steps": {
+                "type": "array",
+                "maxItems": MAX_CONTINUATION_BATCH_STEPS,
+                "items": {"type": "object"},
+            },
+            "appliedCount": {"type": "integer", "minimum": 0, "maximum": MAX_CONTINUATION_BATCH_STEPS},
+            "alreadyAppliedCount": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": MAX_CONTINUATION_BATCH_STEPS,
+            },
+            "lastAppliedOperationId": {"type": ["string", "null"]},
+            "finalState": {"type": ["object", "null"]},
+            "nextCommand": {"type": ["string", "null"]},
+            "requiredInputs": _REQUIRED_INPUTS,
+            "blockers": _BLOCKERS,
+            "modelCallsStarted": {"const": False},
+            "hostLaunchStarted": {"const": False},
+            "productionPromotionClaimed": {"const": False},
+            "receiptDigest": _DIGEST,
+        },
+    ),
+    "agent-workflow-continuation-batch-summary.v1": open_object_schema(
+        "agent-workflow-continuation-batch-summary.v1",
+        required=[
+            "schemaVersion",
+            "status",
+            "stopReason",
+            "appliedCount",
+            "alreadyAppliedCount",
+            "lastAppliedOperationId",
+            "finalState",
+            "receiptPath",
+            "receiptDigest",
+            "inputBytes",
+            "outputBytes",
+            "nextCommand",
+            "requiredInputs",
+            "blockers",
+            "modelCallsStarted",
+            "hostLaunchStarted",
+            "productionPromotionClaimed",
+            "summaryDigest",
+        ],
+        properties={
+            "status": {"enum": ["STOPPED", "COMPLETE"]},
+            "stopReason": {"enum": list(CONTINUATION_BATCH_STOP_REASONS)},
+            "appliedCount": {"type": "integer", "minimum": 0},
+            "alreadyAppliedCount": {"type": "integer", "minimum": 0},
+            "lastAppliedOperationId": {"type": ["string", "null"]},
+            "finalState": {"type": ["object", "null"]},
+            "receiptPath": {"type": ["string", "null"]},
+            "receiptDigest": {"type": ["string", "null"], "minLength": 64, "maxLength": 64},
+            "inputBytes": {"type": "integer", "minimum": 0},
+            "outputBytes": {"type": "integer", "minimum": 0},
+            "nextCommand": {"type": ["string", "null"]},
+            "requiredInputs": _REQUIRED_INPUTS,
+            "blockers": _BLOCKERS,
+            "modelCallsStarted": {"const": False},
+            "hostLaunchStarted": {"const": False},
+            "productionPromotionClaimed": {"const": False},
+            "summaryDigest": _DIGEST,
+        },
+    ),
+}
+
+
+def build_continuation_batch_summary(receipt: dict[str, Any]) -> dict[str, Any]:
+    """Build the bounded stdout projection of one persisted batch receipt."""
+
+    body = {
+        "schemaVersion": "agent-workflow-continuation-batch-summary.v1",
+        "status": receipt["status"],
+        "stopReason": receipt["stopReason"],
+        "appliedCount": receipt["appliedCount"],
+        "alreadyAppliedCount": receipt["alreadyAppliedCount"],
+        "lastAppliedOperationId": receipt["lastAppliedOperationId"],
+        "finalState": receipt["finalState"],
+        "receiptPath": receipt["receiptPath"],
+        "receiptDigest": receipt["receiptDigest"],
+        "inputBytes": receipt["inputBytes"],
+        "outputBytes": receipt["outputBytes"],
+        "nextCommand": receipt["nextCommand"],
+        "requiredInputs": receipt["requiredInputs"],
+        "blockers": receipt["blockers"],
+        "modelCallsStarted": False,
+        "hostLaunchStarted": False,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "summaryDigest": canonical_digest(body)}
+
+
+def build_unpersisted_continuation_batch_summary(
+    *,
+    stop_reason: str,
+    blockers: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Build a fail-closed summary when no output receipt can be reserved."""
+
+    body = {
+        "schemaVersion": "agent-workflow-continuation-batch-summary.v1",
+        "status": "STOPPED",
+        "stopReason": stop_reason,
+        "appliedCount": 0,
+        "alreadyAppliedCount": 0,
+        "lastAppliedOperationId": None,
+        "finalState": None,
+        "receiptPath": None,
+        "receiptDigest": None,
+        "inputBytes": 0,
+        "outputBytes": 0,
+        "nextCommand": None,
+        "requiredInputs": [],
+        "blockers": blockers,
+        "modelCallsStarted": False,
+        "hostLaunchStarted": False,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "summaryDigest": canonical_digest(body)}
+
+
+def continuation_batch_blocker(exc: LifecycleError) -> dict[str, Any]:
+    """Convert one lifecycle failure into a stable batch blocker."""
+
+    blocker: dict[str, Any] = {"code": exc.code, "message": exc.message}
+    if exc.details:
+        blocker["context"] = exc.details
+    return blocker
+
+
+def continuation_batch_stop_reason(exc: LifecycleError) -> str:
+    """Map preflight failures to the closed batch stop-reason set."""
+
+    if exc.code == "continuation-retry-proof-required":
+        return "RETRY_PROOF_REQUIRED"
+    if exc.code == "continuation-retry-proof-mismatch":
+        return "RETRY_PROOF_MISMATCH"
+    if exc.code == "continuation-input-cap-exceeded":
+        return "CAP_BYTES"
+    return "BLOCKED"
+
+
+def continuation_batch_projection_fields(
+    projection: dict[str, Any] | None,
+) -> tuple[str | None, list[dict[str, Any]], list[dict[str, Any]]]:
+    """Extract bounded operator-facing fields from a one-step projection."""
+
+    if projection is None:
+        return "workflow continue", [], []
+    action = projection.get("action")
+    next_action = projection.get("nextAction")
+    route = action.get("route") if isinstance(action, dict) else None
+    if not isinstance(route, str) and isinstance(next_action, dict):
+        route = next_action.get("type")
+    return (
+        f"workflow {route}" if isinstance(route, str) else None,
+        list(projection.get("requiredInputs", [])),
+        list(projection.get("blockers", [])),
+    )
+
+
+def is_sha256_digest(value: Any) -> bool:
+    """Return whether value is one lowercase SHA-256 hexadecimal digest."""
+
+    return isinstance(value, str) and len(value) == 64 and all(character in "0123456789abcdef" for character in value)
+
+
+def normalize_continuation_input_reference(value: Any, field: str) -> dict[str, str]:
+    """Validate one digest-bound repository-relative artifact reference."""
+
+    if not isinstance(value, dict) or set(value) != {"path", "sha256"}:
+        raise LifecycleError("continuation-input-reference-invalid", f"{field} must be a path and SHA-256 reference")
+    raw_path = value.get("path")
+    digest = value.get("sha256")
+    if not isinstance(raw_path, str) or not isinstance(digest, str) or not is_sha256_digest(digest):
+        raise LifecycleError("continuation-input-reference-invalid", f"{field} sha256 is invalid")
+    path = normalize_repo_path(raw_path, label=field)
+    return {"path": path, "sha256": digest}
+
+
+__all__ = [
+    "CONTINUATION_BATCH_STOP_REASONS",
+    "MAX_CONTINUATION_BATCH_STEPS",
+    "WORKFLOW_CONTINUATION_BATCH_SCHEMAS",
+    "build_continuation_batch_summary",
+    "build_unpersisted_continuation_batch_summary",
+    "continuation_batch_blocker",
+    "continuation_batch_projection_fields",
+    "continuation_batch_stop_reason",
+    "is_sha256_digest",
+    "normalize_continuation_input_reference",
+]