Release Samsarix Routine Engine 0.2

.github/workflows/ci.yml

@@ -32,6 +32,8 @@ jobs:
           /tmp/routine-wheel/bin/python -m pip install dist/*.whl
           /tmp/routine-wheel/bin/python -c "from routine_engine import RoutineEngine; print(RoutineEngine)"
           /tmp/routine-wheel/bin/routine-engine demo --name CI
+          /tmp/routine-wheel/bin/routine-engine schema | /tmp/routine-wheel/bin/python -m json.tool >/dev/null
+          PYTHONPATH=. /tmp/routine-wheel/bin/routine-engine run examples/release-readiness.json --plugin examples.release_actions
 
   test:
     runs-on: ${{ matrix.os }}

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes will be documented here. The format follows [Keep a Changelo
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-08
+
 ### Changed
 
 - Reframed the repository as Samsarix Routine Engine, a focused local-first Python workflow component.
@@ -14,11 +16,24 @@ All notable changes will be documented here. The format follows [Keep a Changelo
 
 ### Added
 
+- Deterministic execution plans through `RoutineEngine.plan()` and the `routine-engine plan` command.
+- A distributable workflow v1 JSON Schema and `routine-engine schema` discovery command.
+- Atomic per-step checkpoints and `resume()` / `aresume()` recovery that reuses successful work.
+- `routine-engine history`, `show`, and `resume` commands for persisted local runs.
+- An explicit workflow `schema_version` contract, currently pinned to version 1.
 - Validated acyclic workflow and step models with explicit resource limits.
 - Trusted sync/async action registration, bounded concurrency/retries, references, and exact terminal results.
 - Atomic local JSON workflow/run persistence with bounded history.
 - `routine-engine` CLI for validation, execution, explicit plugins, and a built-in demo.
 - Behavioral unit/integration tests, coverage gate, linting, typing, package checks, wheel smoke test, and CI matrix.
 - Productization decision record, security policy, API guide, and runnable examples.
+- A tested release-readiness consumer fixture plus use-case and competitive-position guidance.
+
+### Security
+
+- Bounded workflow definitions, run inputs, step outputs, JSON nesting, and persisted error text.
+- Synchronous actions now run in bounded worker threads so they cannot serialize or block the async scheduler.
+- State storage is capped at 64 MiB and migrates version 1 history forward to the resumable version 2 format.
 
-[Unreleased]: https://github.com/Deathcharge/routine-engine/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Deathcharge/routine-engine/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Deathcharge/routine-engine/compare/v0.1.0...v0.2.0

README.md

@@ -4,7 +4,7 @@ Routine Engine is a small, local-first Python library and CLI for deterministic
 
 The focused use case is application-owned routines: import jobs, report generation, release checks, data preparation, and other bounded workflows that should stay inside an existing Python process or CI job.
 
-> Maturity: **0.1 release candidate.** The supported core is implemented, behaviorally tested, and ready for release review. It has not been published by this repository update.
+> Maturity: **0.2 release candidate.** The supported core, bounded execution contract, and local recovery path are implemented and under release verification. It has not been published by this repository update.
 
 ## Why this exists
 
@@ -78,9 +78,14 @@ The CLI includes three side-effect-free actions: `identity`, `merge`, and `forma
 
 ```bash
 routine-engine demo --name Ada
+routine-engine schema
 routine-engine validate examples/workflow.json
+routine-engine plan examples/workflow.json
 routine-engine run examples/workflow.json --input '{"name":"Ada"}'
 routine-engine run examples/workflow.json --input @input.json --state .routine-state.json
+routine-engine history --state .routine-state.json
+routine-engine show RUN_ID --state .routine-state.json
+routine-engine resume RUN_ID --state .routine-state.json --plugin my_actions
 ```
 
 Application actions can be loaded only from an explicit trusted module:
@@ -101,6 +106,7 @@ Workflow data cannot choose the module that gets imported.
 
 ```json
 {
+  "schema_version": 1,
   "id": "welcome",
   "description": "Prepare a greeting",
   "max_concurrency": 4,
@@ -124,7 +130,11 @@ Workflow data cannot choose the module that gets imported.
 
 References must occupy the complete string. Supported forms are `{{ input.path.to.value }}`, `{{ steps.step_id.output }}`, and `{{ steps.step_id.output.path }}`. Missing references fail the affected step; downstream steps are skipped.
 
-Resource limits are part of the public contract: 256 steps, 32 concurrent actions, 10 retries per step, and 60 seconds maximum configured retry delay. Registered actions are trusted application code; Routine Engine does not sandbox them.
+Resource limits are part of the public contract: 256 steps, 32 concurrent actions, 10 retries per step, 60 seconds maximum configured retry delay, 1 MiB definitions and inputs, 4 MiB step outputs, 32 JSON nesting levels, and 4,096-character errors. Data crossing a workflow boundary must be finite, portable JSON with string object keys.
+
+Synchronous actions run in a bounded worker-thread pool so one blocking action does not freeze the asynchronous scheduler. Cancellation cannot forcibly terminate Python code already executing in a thread. Registered actions remain trusted application code; Routine Engine does not sandbox them.
+
+When `--state` or `JsonStore` is used, the engine writes the run snapshot before starting work and atomically checkpoints every terminal step. If the process is interrupted, `engine.resume(run_id)` (or the CLI `resume` command) reuses successful checkpoints and runs only unfinished steps. Actions with external side effects should still be idempotent: a process can stop after the side effect occurs but before its success checkpoint reaches disk.
 
 ## Development
 
@@ -136,9 +146,10 @@ mypy src
 pytest --cov --cov-report=term-missing
 python -m build
 python -m twine check dist/*
+python benchmarks/benchmark_engine.py --steps 256 --runs 20
 ```
 
-See [Getting Started](docs/GETTING_STARTED.md), [API Reference](docs/API_REFERENCE.md), [Productization](docs/PRODUCTIZATION.md), [Security Policy](SECURITY.md), and [Contributing](CONTRIBUTING.md).
+See [Getting Started](docs/GETTING_STARTED.md), [API Reference](docs/API_REFERENCE.md), [Use Cases](docs/USE_CASES.md), [Competitive Position](docs/COMPETITIVE_ANALYSIS.md), [Security Policy](SECURITY.md), and [Contributing](CONTRIBUTING.md).
 
 ## Scope and legacy source
 

ROADMAP.md

@@ -1,49 +1,54 @@
 # Samsarix Routine Engine roadmap
 
-This roadmap separates four gates: merge, release, publication, and flagship adoption. Passing one does not imply the next.
+This roadmap separates repository readiness, package publication, and portfolio adoption. Passing one gate does not imply the next.
 
 ## Product boundary
 
-Portfolio role: **reusable library or sdk**. Keep this as a small, independently versioned package. Samsarix Unified should consume it only through a public API adapter; private monorepo imports and copied implementations are out of scope.
+Routine Engine is a reusable, independently versioned SDK for bounded application-owned workflows. It is not a hosted orchestrator. Consumers integrate through the exported Python API, workflow schema v1, CLI behavior, and portable result records—not private repository imports.
 
-Current disposition: Merge the productization branch after exact-head verification and rollback-ref creation; release and adoption remain separate decisions.
+## Version 0.2 release candidate
 
-## Stabilize the productized default
+Implemented on the 0.2 branch:
 
-- Keep the default branch buildable from a clean checkout and preserve exact-head CI evidence.
-- Keep Samsarix LLC branding, package identity, license metadata, and compatibility aliases internally consistent.
-- Preserve the pre-productization default under a rollback ref before merging; do not delete legacy history.
-- The productization work is now committed, pushed, clean, and green in hosted checks.
-- Next: prove one consumer, enforce payload and storage limits, and pin the supported release contract.
-- Review priority: Capture dirty work deliberately.
-- Review priority: fix license and payload/storage limits.
-- Review priority: pin CI.
-- Review priority: green tests/build.
-- Review priority: prove one consumer or freeze.
+- Explicit workflow schema v1 and a distributable JSON Schema.
+- Deterministic execution plans and a CI-friendly `plan` command.
+- Bounded definitions, inputs, outputs, JSON depth, errors, retries, and concurrency.
+- Non-blocking synchronous actions under bounded local concurrency.
+- Atomic run creation, per-step checkpoints, history inspection, and crash-safe resume of successful work.
+- State schema v2 with version 1 migration and a 64 MiB cap.
+- A release-readiness consumer fixture and evidence-backed competitive boundary.
 
-## Release candidate
+Release gates still required:
 
-- Build and install the wheel in a clean environment.
-- Prove one real consumer and a versioned compatibility fixture.
-- Publish only after package-name ownership, licensing, provenance, and rollback are recorded.
+- Build and inspect both sdist and wheel from a clean tree.
+- Install the wheel into a clean environment and run API, CLI, schema, and consumer smoke tests.
+- Pass the supported Python matrix, lint, formatting, strict typing, branch coverage, dependency audit, and source security scan.
+- Record the exact commit, artifact digests, hosted checks, and rollback ref in the release pull request.
 
-Current hardening backlog:
+## Publication
 
-- The entire candidate is uncommitted and absent remotely.
-- No total workflow-file, nesting, persisted-record, output, or error-message size cap.
-- Sync actions can block the event loop; actions have no timeout, isolation, idempotency key, compensation, or durable queue.
-- Local JSON persistence is single-process and may retain secrets in plaintext.
-- The market already has many DAG/workflow libraries; differentiation is weak without a portfolio consumer.
-- License metadata is stale and internally risky: the BSL names Helix Collective and “Helix Licensing System,” has no Additional Use Grant, and does not clearly identify this package.
-- Untracked CI and all static implementation claims remain unverified.
+Publication is a separate owner decision. Before publishing to a package index:
 
-## Samsarix adoption
+- Confirm package-name ownership and Samsarix LLC publishing credentials.
+- Confirm that the Business Source License terms and metadata are the intended commercial policy.
+- Tag an immutable version and attach artifact hashes and release notes.
+- Document the supported compatibility window and vulnerability response process.
 
-- Define a public API, event, schema, artifact, or deployment contract before connecting to Samsarix Unified.
-- Add a consumer-owned contract fixture covering authentication, privacy, limits, errors, and version compatibility.
-- Make one implementation canonical; remove or freeze duplicate behavior only after parity and rollback are proven.
-- Record an owner, support level, compatibility window, and measurable adoption signal.
+## Portfolio adoption
+
+- Integrate one Samsarix application through workflow schema v1 or the public Python API.
+- Keep consumer-owned fixtures covering limits, failures, resume behavior, privacy, and version compatibility.
+- Measure whether the engine removes bespoke orchestration code or improves restart/audit behavior.
+- Add adapters only when a real consumer proves the need; do not grow into a generic control plane speculatively.
+
+## Candidate follow-ups
+
+- Optional per-step timeouts with clearly documented thread-cancellation limits.
+- Pluggable persistence behind a small checkpoint protocol for applications needing database-backed coordination.
+- First-class idempotency metadata and application-defined compensation hooks.
+- Structured lifecycle events for observability adapters.
+- A documented schema/version deprecation policy before 1.0.
 
 ## Completion evidence
 
-A milestone is complete only when its exact commit, commands and results, artifact digest, consumer or deployment, and rollback path are recorded in a pull request or release record. README claims must not exceed that evidence.
+A milestone is complete only when its exact commit, commands and results, artifact digest, consumer or deployment, and rollback path are recorded. README claims must not exceed that evidence.

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes are currently made on the latest `0.1.x` release candidate and the default branch. The archived top-level `routine_engine/` extraction is not a supported public API and is excluded from distributions.
+Security fixes are currently made on the latest `0.2.x` release candidate and the default branch. The archived top-level `routine_engine/` extraction is not a supported public API and is excluded from distributions.
 
 ## Report a vulnerability
 
@@ -20,4 +20,6 @@ Please do not open a public issue for an undisclosed vulnerability. Samsarix LLC
 
 Workflow definitions are untrusted data; registered actions are trusted application code. Routine Engine validates graph and resource bounds and never evaluates definition-supplied code, commands, imports, SQL, paths, or URLs. It is not a sandbox. Applications are responsible for authorization and validation inside every action they register.
 
-The JSON store is intended for a trusted local filesystem. It provides atomic replacement and in-process locking, not encryption, access control, tamper evidence, or multi-process transactions. Do not persist secrets or sensitive action outputs unless the surrounding filesystem and application controls are appropriate.
+The JSON store is intended for a trusted local filesystem. It provides bounded atomic replacement and in-process locking, not encryption, access control, tamper evidence, or multi-process transactions. Do not persist secrets or sensitive action outputs unless the surrounding filesystem and application controls are appropriate.
+
+Resume provides at-least-once execution. A process may stop after an action performs an external side effect and before its success checkpoint is durable. Side-effecting actions must implement application-level idempotency, normally using the stable run and step IDs supplied in `ActionContext`.

benchmarks/benchmark_engine.py

@@ -0,0 +1,41 @@
+"""Reproducible local scheduler benchmark; not a CI timing gate."""
+
+from __future__ import annotations
+
+import argparse
+import statistics
+import time
+
+from routine_engine import RoutineEngine
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--steps", type=int, default=256, choices=range(1, 257))
+    parser.add_argument("--runs", type=int, default=20)
+    args = parser.parse_args()
+    if args.runs < 1:
+        parser.error("--runs must be positive")
+
+    engine = RoutineEngine()
+    engine.register("noop", lambda _: None)
+    workflow = {
+        "id": "scheduler-benchmark",
+        "max_concurrency": 32,
+        "steps": [{"id": f"step-{index}", "action": "noop"} for index in range(args.steps)],
+    }
+    engine.plan(workflow)
+    durations = []
+    for _ in range(args.runs):
+        started = time.perf_counter()
+        result = engine.run(workflow)
+        assert result.succeeded
+        durations.append(time.perf_counter() - started)
+
+    median = statistics.median(durations)
+    p95 = sorted(durations)[max(0, int(len(durations) * 0.95) - 1)]
+    print(f"steps={args.steps} runs={args.runs} median_ms={median * 1000:.2f} p95_ms={p95 * 1000:.2f}")
+
+
+if __name__ == "__main__":
+    main()

docs/API_REFERENCE.md

@@ -10,8 +10,10 @@ RoutineEngine(*, store: JsonStore | None = None)
 
 - `register(name, action, *, replace=False)`: add a trusted sync or async callable. Duplicate names fail unless replacement is explicit.
 - `validate(workflow) -> Workflow`: validate shape, bounds, graph, references to registered action names, and return an immutable definition.
+- `plan(workflow) -> ExecutionPlan`: return deterministic topological layers without executing actions.
 - `run(workflow, inputs=None) -> RunResult`: synchronous execution. It cannot be nested inside an active event loop.
 - `await arun(workflow, inputs=None) -> RunResult`: asynchronous execution with bounded parallelism.
+- `resume(run_id) -> RunResult` / `await aresume(run_id)`: continue a persisted active run, reusing its successful step checkpoints.
 - `actions`: sorted tuple of registered names.
 
 ## `ActionContext`
@@ -39,6 +41,11 @@ Limits:
 | Retries per step | 10 |
 | Retry delay | 60 seconds |
 | Description | 1,000 characters |
+| Workflow definition | 1 MiB |
+| Run inputs | 1 MiB |
+| Step output | 4 MiB |
+| JSON depth | 32 levels |
+| Error text | 4,096 characters |
 
 IDs and action names start with a letter and may contain letters, numbers, `.`, `_`, and `-`.
 
@@ -54,9 +61,9 @@ Actions exhausting their retries make the run fail. Steps depending on anything
 JsonStore(path, *, history_limit=100)
 ```
 
-The store atomically replaces one versioned JSON file. `snapshot()` returns a detached mapping. Invalid/corrupt data and non-JSON action outputs raise `StorageError`; existing state is not silently discarded.
+The store atomically replaces one versioned JSON file, capped at 64 MiB. `snapshot()` returns a detached mapping; `get_run()` and `list_runs()` inspect history. `begin_run()`, `record_step()`, and `finish_run()` form the checkpoint lifecycle used by the engine. Invalid/corrupt data raises `StorageError`; existing state is not silently discarded.
 
-This is local persistence, not a transactional multi-process database.
+State schema v2 reads version 1 definition/history files and migrates them on the next write. Only v2 runs started with a workflow and input snapshot are resumable. This is local persistence, not a transactional multi-process database, and it stores data in plaintext.
 
 ## Exceptions