ledgence-worker 0.4.1__tar.gz

ledgence_worker-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ledgence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ledgence_worker-0.4.1/PKG-INFO

@@ -0,0 +1,563 @@
+Metadata-Version: 2.4
+Name: ledgence-worker
+Version: 0.4.1
+Summary: Dependency-free Python authoring helpers for Ledgence tasks and checkpoint workflows
+Author-email: Ledgence <dev@ledgence.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Changelog, https://github.com/Ledgence/ledgence/releases
+Project-URL: Documentation, https://github.com/Ledgence/ledgence/blob/develop/sdk/python/README.md
+Project-URL: Homepage, https://github.com/Ledgence/ledgence
+Project-URL: Issues, https://github.com/Ledgence/ledgence/issues
+Project-URL: Repository, https://github.com/Ledgence/ledgence
+
+# Ledgence Python worker helper
+
+The Rust worker supplies `ledgence.worker` with its Python runner. It supports
+ordinary program handlers, invocation context and logs, and protocol 3 workflows
+with registered entrypoints, durable local results, tasks, subworkflows, forks,
+events, timers, and action approvals. The separately installed
+[`ledgence.client`](../python-client/README.md) submits and observes work.
+
+Use a runtime helper matching your worker. The helper is standard-library-only;
+application integrations and their prepared dependencies belong in the program
+package. No agent framework or model provider is required.
+
+## Install for local development
+
+This package provides `ledgence-worker` version **0.4.1**, requiring Python
+3.11+. For a version published on PyPI, install the version matching your worker
+in your application's existing uv project as a development dependency:
+
+```sh
+uv add --dev "ledgence-worker==0.4.1"
+```
+
+For pip, use `python -m pip install "ledgence-worker==0.4.1"` in the application's
+activated virtual environment. Check
+[registry availability](https://pypi.org/project/ledgence-worker/0.4.1/) before
+using these commands. For an unreleased checkout, use the local source
+installation below. The historical `v0.4.0` source tag does not contain this
+package's `pyproject.toml`.
+
+### Install from source
+
+From your application's existing uv project, add the local package as a normal
+development dependency, substituting your Ledgence checkout's absolute path:
+
+```sh
+uv add --dev /absolute/path/to/ledgence/sdk/python
+uv run python -c "from ledgence.worker.workflow import Workflow; from ledgence.worker import current_invocation; print('worker imports ready')"
+```
+
+This installs the versioned helper into the project's environment and records
+the local source in its dependency configuration. Select that environment in
+your editor. No `PYTHONPATH` change is needed. Keep the checkout available for
+future dependency synchronization, and use a helper version matching the deployed
+worker release; installation does not check the deployed worker's compatibility.
+A local source entry or lockfile does not freeze the directory's contents;
+record and retain the exact checkout commit when sharing or reproducing a
+development setup.
+
+If you contribute to the helper itself, use
+`uv add --dev --editable /absolute/path/to/ledgence/sdk/python` so edits to its
+Python source are reflected directly. Ordinary program authors should use the
+normal installation above. In an existing activated Python virtual environment,
+the pip alternative is:
+
+```sh
+python -m pip install /absolute/path/to/ledgence/sdk/python
+python -c "from ledgence.worker.workflow import Workflow; print('worker imports ready')"
+```
+
+The installed package includes inline type information and a
+`ledgence/worker/py.typed` marker for compatible editor/type-checking tools. It
+shares the native `ledgence` namespace with the independently installed
+`ledgence-client`; neither distribution provides a root `ledgence/__init__.py`.
+
+Use this environment to import your programs, register workflow entrypoints,
+and test ordinary business functions. `current_invocation()` and
+`workflow_context()` still require an active invocation; installing the package
+does not create a local workflow execution harness. The package supplies no CLI,
+server, Python client, or replacement for the worker's `--runner` configuration.
+At execution, the Rust worker keeps supplying its matching bundled helper,
+which the bootstrap loads before a copy vendored in a program artifact.
+
+Keep `ledgence-worker` out of application runtime dependencies: the worker
+supplies it. Prepare all actual application dependencies separately for the
+worker's platform and exact Python major/minor before publishing a program.
+See [Develop Python programs](../../docs-site/src/content/docs/how-to/develop-python-programs.md)
+for a complete authoring example and [program packages](../../docs/program-packages.md)
+for the runtime artifact contract.
+
+## Durable model and tool calls
+
+Protocol 3 workflows can give an application-owned model or tool call an explicit
+durable identity without adopting an agent framework:
+
+```python
+from ledgence.worker.workflow import OperationKind
+
+response = await ctx.operation(
+    f"turn:{round}:model", call_model,
+    kind=OperationKind.MODEL, version="adapter-1",
+    arguments={
+        "model": "demo-model-2026-01",
+        "messages": messages,
+        "temperature": 0,
+        "max_tokens": 256,
+        "tools": tool_schemas,
+    },
+)
+result = await ctx.operation(
+    f"turn:{round}:tool:0", lookup,
+    kind=OperationKind.TOOL, version="lookup-1",
+    arguments={"query": response["query"]},
+)
+```
+
+`kind` requires an `OperationKind` member; plain strings and other enums are
+rejected. `version` identifies the application adapter/tool behavior. Include the
+effective provider/model identifier or snapshot, prompts, settings, tool schemas,
+and other behavior-affecting configuration in `arguments`. A provider's mutable
+model alias does not pin its underlying behavior. A model-generated tool request
+is application input: validate and normalize it before selecting an allowed tool
+and calling `operation`.
+
+Before starting the callable, the helper binds its Python signature, materializes
+keyword defaults, and freezes the effective JSON arguments. The callable receives
+an independent copy as `fn(**effective_arguments)`. Each record binds the explicit
+key, operation kind, original callable module/qualified name, version, and effective
+arguments. Repeating that key in the same activation with the identical binding
+reuses the owned execution or acknowledged result; a changed binding fails before
+another call starts. Object order is ignored, but numbers such as `1`, `1.0`,
+`True`, and positive/negative zero retain distinct bindings. Caller or callable
+mutation cannot change the saved request, and each awaited result is a fresh copy.
+
+Keep clients and credentials outside arguments; JSON requests and results are
+stored as supplied. Sockets, SDK response objects, closures, and process memory
+are not checkpointed. Application adapters convert completed responses to bounded
+JSON. Partial streams, generators, and
+provider exceptions are not successful records. The helper imports no model SDK
+and performs no provider calls itself. Synchronous and asynchronous callables use
+the same execution, cancellation, and acknowledgment rules as `ctx.local`.
+
+The result is returned only after the existing Rust local-result commit is
+acknowledged. An activation retry replays accepted results without deliberately
+executing their callables. If an effect succeeds before its record is accepted,
+it can repeat; pass a stable business idempotency key in the effective arguments
+or reconcile with the external system. A lost or invalid acknowledgment prevents
+successful completion of the original activation, even if the controller catches
+the error. Durable recovery does not guarantee exactly-once provider execution.
+
+Operation keys share the activation-local journal with `ctx.local`; their semantic
+binding keeps them distinct from ordinary local calls. The approval-reserved key
+prefix remains unavailable. Operations have the same limits: 128 records and
+256 KiB combined per activation, 128 KiB per full binding/result record. The
+versioned input envelope counts toward the ordinary JSON depth and byte limits.
+Control flow remains ordinary Python: bound rounds and tool counts, then return
+`ctx.continue_(continuation=..., state=...)` with the round, messages, and results
+needed next. A new activation receives that explicit checkpoint and a new journal;
+Python frames and ordinary locals are not restored. A local operation cannot
+start another durable operation, stage children, or call workflow control APIs.
+
+## Durable approvals
+
+Protocol 3 workflows can return `ctx.request_approval(key, action=...,
+continuation=..., state=..., timeout_ms=...)` to checkpoint an action and release
+their worker slot. `resume=` is an alternative to `continuation=` and
+`ctx.wait_approval(...)` is an alias. Normalize effective arguments before
+requesting approval; optional `proposed_arguments` preserves the original input
+as audit context. Every request has a finite deadline of at most 365 days.
+
+Import `ApprovalAction` and `ApprovalStatus` from `ledgence.worker.workflow`.
+`ApprovalAction.for_callable(fn, version="1", arguments={...})` binds the callable's
+module and qualified name and freezes its keyword arguments, including defaults.
+It performs Python signature binding; application validation and domain-specific
+normalization remain the caller's responsibility. `ApprovalAction(name,
+version="1", arguments={...})` supports actions defined by other adapters.
+
+On the resumed entrypoint, `ctx.approval` is an immutable typed observation.
+Check `ctx.approval.status is ApprovalStatus.APPROVED`, then
+`await ctx.approved_local(fn, version="1")` to execute only the saved effective
+arguments through a durable local step. This helper accepts no replacement
+arguments and verifies the callable identity/version. Copies returned by
+`ctx.wake`, `ctx.approval.action.arguments`, or `ctx.approval.to_dict()` cannot
+change its private execution binding. Rejected and expired requests resume with
+their corresponding status; workflow cancellation closes the request without
+resuming its controller. See the runnable
+[durable approval example](../../examples/durable-approval/README.md).
+
+Execution also checks that signature binding introduces no new effective defaults.
+When constructing an `ApprovalAction` directly, include all effective arguments
+before review; `approved_local` will not add an omitted, unreviewed default.
+
+Approvals are for operator-trusted code. A Python callable remains responsible
+for its behavior and external authorization. Approval does not make an external
+effect exactly once: an effect can succeed before its durable local result is
+acknowledged, so use external idempotency keys or reconciliation as needed.
+
+## Runtime helper
+
+MIT-licensed, standard-library-only program support. The Rust worker starts the
+configured CPython executable with `-I -S -B` and `ledgence/worker/bootstrap.py`. Python
+is a separately installed runtime; Ledgence does not embed or download CPython.
+Programs declare an exact supported Python major/minor (at least 3.11), with code
+and vendored dependencies in their immutable artifact directory.
+
+The worker supplies the `ledgence.worker` context helper alongside the runner;
+applications do not need to vendor that helper. Application dependencies belong
+in the program artifact. The bootstrap loads its own helper first, then adds the
+absolute artifact directory to Python's import path. Bytecode generation is
+explicitly disabled, so ordinary imports do not add `__pycache__` directories to
+an artifact even when filesystem permissions would allow it.
+
+`ledgence` is a native Python namespace package; it has no `__init__.py`.
+Keep the complete `ledgence/worker` directory and its `ledgence` parent together
+when distributing the runner. The separately installed `ledgence-client` SDK
+provides `ledgence.client` in the same namespace without adding client dependencies
+to the worker helper. A program using the client must include that SDK and its
+prepared dependencies in its artifact, just like any other application dependency.
+Do not add a root `ledgence/__init__.py` to either component or the artifact.
+
+The public helper import is `ledgence.worker`, replacing the legacy
+`ledgence_worker` path. Update existing program imports and publish a new immutable
+program version/digest. The old import and runner path are not aliases; protocol
+versions 1, 2, and 3 retain their wire behavior.
+
+The worker sets a separate temporary working directory for each session. Relative
+writes go there and persist across that session's invocations. Confirmed session
+cleanup removes this directory. Read packaged resources relative to the program
+module's `__file__`, not the working directory. Directory separation is file
+lifecycle management and does not change OS access permissions.
+
+Expose a callable as `module:function`; protocols 1/2 require a synchronous
+handler, while protocol 3 also supports `async def`. Its module and package
+parents must originate inside the artifact. Names already loaded by the bootstrap
+(such as `json`, `os`, `ledgence`, and `ledgence.worker`) cannot be handler modules; conflicts
+are rejected before readiness. Use an application-specific module name. Regular
+and namespace packages are supported, and application code may still import the
+standard library normally.
+
+The callable receives the complete
+CloudEvent dictionary and returns a JSON-compatible value. `current_invocation()`
+provides transport execution identifiers when needed. The helper starts a fresh
+`contextvars.Context` for every invocation; process/module globals intentionally
+persist. Programs must clean up other invocation state and background work.
+
+One process handles one invocation at a time. Results support null, booleans,
+Unicode scalar strings, integers from `-2**63` through `2**64 - 1`, finite binary64
+floating-point values, arrays, and objects with string keys. Python tuples are
+encoded as JSON arrays. At most 64 nested containers are permitted; a scalar has
+depth zero. Cycles, non-string keys, lone surrogate characters, out-of-range
+integers, non-finite numbers, unawaited values, and oversized results produce typed
+`invalid_output` failures and leave the process reusable. Rust checks the shared
+wire profile when accepting the response.
+
+The default protocol frame limit is 2 MiB, including result/input envelopes and
+the newline. The worker supplies the configured limits explicitly when starting
+the helper. The delivery submission limit remains 1 MiB of application data;
+the additional frame capacity carries CloudEvent metadata and protocol fields.
+
+Business exceptions produce typed failure results. Error text is shortened by the
+complete frame's encoded UTF-8 byte budget, including event and attempt IDs, JSON
+escaping, and the newline. The handler is not called if those IDs cannot fit even
+an empty failure response. A protocol
+fault terminates the process. Python and native stdout writes are redirected to
+stderr; an isolated descriptor carries bounded JSON-lines responses. Parent-side
+log capture must continue draining stderr even after its retention limit.
+
+This process boundary executes trusted code with the worker's OS permissions.
+The helper is not a sandbox and cannot undo external effects on retries.
+
+## Protocol versions and contextual logs
+
+Existing `runtime.protocol: 1` packages keep the original invoke/result protocol.
+Protocol 2 adds contextual logs; protocol 3 also enables asynchronous handlers and
+workflow control exchanges. The ready version must match the manifest; a mismatch
+fails before calling the handler. Protocols 2/3 pass an invocation-local
+`processing_context` outside the complete, unchanged CloudEvent. It is null when
+worker tracing is disabled. It never replaces the event's origin `traceparent`.
+
+`current_invocation()` provides `event_id`, `attempt_id`, `source`, `tenant_id`,
+`namespace`, `run_id`, `task_id`, `attempt_no`, and the optional frozen W3C
+`processing_context`. Optional `workflow_id` and `activation_id` come from envelope
+extensions. Nested workflow invocations also expose `parent_workflow_id` and
+`root_workflow_id`; root workflow invocations expose a null parent and their own
+workflow ID as the root. Ordinary tasks outside workflows have neither. Protocol 3
+logs include the paired ancestor IDs only for nested workflows, preserving older
+root log shapes. These identifiers never enter user data. Context is reset on
+success, business exception, and invalid
+output. No invocation context is written to process-global environment variables.
+
+```python
+from ledgence.worker import current_invocation, get_logger
+
+log = get_logger(__name__)
+
+def handle(event):
+    log.info("Invoice issued", extra={"attributes": {"invoice.id": event["data"]["invoice_id"]}})
+    return {"task_id": current_invocation().task_id}
+```
+
+`get_logger` returns a normal `logging.Logger`, adding one Ledgence handler while
+preserving existing handlers and root configuration. An unset logger level becomes
+INFO. Each `LogRecord` is handled once by Ledgence, including when it propagates
+through parent loggers configured with `get_logger`. Re-dispatching that same
+record does not emit another Ledgence frame; separate logging calls create
+independent records, even when their messages match. Application and root handlers
+continue to receive records according to normal Python logging rules.
+User attributes occupy a separate map. A record snapshots correlation and
+attributes synchronously at emission; intentionally copied old contexts retain
+their original IDs even if a background thread logs during a later invocation.
+Outside an invocation, records carry process identity only unless the application
+explicitly activates its own OTel span. Raw stdout/stderr remains process-level.
+
+One dedicated writer in protocols 2/3 owns ready, result, log and closing frames. Its optional
+queue is bounded to 64 records and 1 MiB; each log frame is at most 16 KiB or the
+configured output limit, including the newline. Encoding bounds the complete
+attribute tree (64 nodes, four nested levels, shared text budget). Oversized
+optional content is shortened; a record whose correlation cannot fit is dropped.
+Telemetry encoding errors and queue overflow drop logs and increment a saturating
+local counter; they do not replace a handler result. This Python-side count stays
+in the process: it is not carried in result or closing frames, durable task
+history, or a collector export. Worker-side optional-record validation and output
+budget drops have separate bounded diagnostics. Results/control have a
+reserved priority slot. At most one already-writing bounded log precedes a newly
+queued result; IPC itself still has backpressure. Closing discards remaining
+optional records. Telemetry is best effort and may be lost on shutdown or crash.
+
+## Optional OpenTelemetry API bridge
+
+Programs may vendor `opentelemetry-api` and call
+`from ledgence.worker.otel import enable_context; enable_context()` once at module
+initialization. The bridge activates only the invocation's processing carrier
+using the fixed W3C propagator, and attaches an empty context when it is null.
+It resets the OTel context in `finally`. It neither installs a provider nor creates
+a duplicate span for the worker's execution span. Logging inside application
+child spans captures those children's active trace/span IDs.
+
+The default helper imports no OpenTelemetry dependency. To record custom spans,
+the application supplies and owns its SDK/provider and dependencies, with their
+legal notices. Use bounded asynchronous processors for any application exporter.
+Ledgence does not bundle a Python network exporter or serialize Python spans over
+the result channel. The worker exports its own execution spans independently.
+
+`register_shutdown(provider.shutdown)` optionally registers an application-owned
+callback. Each registered callback runs once before the graceful closing ACK;
+exceptions are reported on stderr and other callbacks continue. The parent's
+existing process shutdown deadline bounds callbacks, including a hanging exporter.
+Forced retirement/crashes do not promise a callback or complete flush. There is no
+per-invocation flush or reliance on `atexit`.
+
+The default tests require only the standard library. Optional API/SDK parentage
+tests accept an already prepared dependency directory and make no network calls:
+
+```sh
+LEDGENCE_PYTHON_OTEL_TEST_PACKAGES=/path/to/reviewed-api-sdk-packages \
+  python3 -m unittest discover -s sdk/python/tests -v
+```
+
+The reviewed test set is `opentelemetry-api==1.44.0`,
+`opentelemetry-sdk==1.44.0`, `opentelemetry-semantic-conventions==0.65b0`, and
+`typing_extensions==4.16.0`. The test exporter is in memory. Tests copy prepared
+packages into the temporary artifact to exercise the same isolated import path as
+real programs; nothing is installed at execution time.
+
+## Registered workflow entrypoints (protocol 3)
+
+Register ordinary Python handlers and export the built workflow as the package's
+handler, for example `program:handle`:
+
+```python
+from enum import StrEnum
+from ledgence.worker.workflow import Workflow
+
+class Entry(StrEnum):
+    START = "start"
+    RESUME = "resume"
+
+workflow = Workflow(Entry)
+
+@workflow.entrypoint(Entry.START, default=True)
+def start(event, ctx):
+    return ctx.sleep("delay:0", 1000, continuation=Entry.RESUME,
+                     state={"saved": event["data"]})
+
+@workflow.entrypoint(Entry.RESUME)
+def resume(event, ctx):
+    return ctx.complete(ctx.state["saved"])
+
+handle = workflow.build()
+```
+
+`Workflow` accepts a nonempty `StrEnum` family without aliases. Register every
+member once and choose exactly one default. `build()` validates and freezes that
+registry and returns an async handler; individual entrypoints may be sync or
+async and receive `(event, ctx)`. Public submissions invoke the default. If the
+enum declares the wire value `"start"`, it must be the default.
+
+In a registered workflow, use members of that exact enum for branch and resume
+targets, including approval continuations. `ctx.entrypoint` exposes the selected
+member. No graph declaration or string-routing phase is required; Python code
+chooses the next decision and explicitly saves any state it needs later.
+
+For independent branches of this exact pinned package, `ctx.branch(key,
+entrypoint=..., queue=..., data=...)` builds an immutable specification without
+scheduling. `await ctx.fork(key, branches=[...])` durably registers those owned
+workflows and returns a `ForkRef` while the parent stays in its current activation.
+The parent can continue local work before returning
+`ctx.join(group, resume=..., state=...)` to wait for every branch's terminal
+outcome. Branch execution overlaps only when matching worker capacity is free.
+Fork keys are workflow-wide, branch keys share the child namespace, and exact
+retries reuse the original registration. See
+[entrypoints and forks](../../docs/workflow-entrypoints.md) for a complete example,
+reconciliation, and bounds.
+
+## Explicit checkpoint workflows (protocol 3)
+
+Existing controllers can also use
+`from ledgence.worker.workflow import workflow_context` with string continuations and
+return `ctx.suspend(...)`, `ctx.continue_(...)`, `ctx.wait_event(...)`,
+`ctx.sleep(...)`, `ctx.request_approval(...)`, `ctx.complete(output)`, or
+`ctx.fail(kind, message)`. `ctx.continuation` starts as `"start"`; `ctx.state` is
+explicit JSON state and `ctx.inputs` is the frozen batch of child outcomes.
+The complete CloudEvent, including user-owned `data`, remains the handler argument.
+
+`await ctx.local(key, fn, **json_kwargs)` executes in the current process and
+returns only after the Rust owner acknowledges durable storage of the result.
+Calls sharing an activation-local key and the same callable/input reuse the result.
+The callable does application work and may make ordinary nested Python calls.
+It cannot call workflow control APIs, start another journaled local step, or stage
+distributed tasks or subworkflows; the controller does those after awaiting its result. Otherwise
+replaying the cached result would skip those workflow operations. This boundary
+also applies through asynchronous child tasks and `asyncio.to_thread`.
+Pass all changing inputs explicitly: closure variables and process memory are not
+part of the persisted binding. Ordinary calls have no durable result record. An
+external effect can still repeat after a crash before its commit acknowledgement;
+use an external idempotency key for effects that require deduplication.
+
+`ctx.local(...)` starts an owned operation immediately and returns an awaitable.
+Use `await ctx.gather(ctx.local(...), ctx.local(...))` to overlap asynchronous I/O.
+A synchronous callable retains its normal blocking semantics. The activation
+retains ownership of started local operations and drains them before returning a
+checkpoint, even when an observer stops awaiting one. An unobserved local failure
+fails the activation; explicitly caught local errors remain under controller control.
+A failed commit cannot be
+caught and converted into successful workflow completion.
+
+`ctx.task(key, program=..., version=..., queue=..., data=...)` stages a distributed
+child command. The following checkpoint atomically registers those commands;
+calling `task()` alone makes no network call. Child keys belong to the whole
+workflow, and an identical binding reuses the original child. Use iteration
+suffixes such as `"invoice:3"` to request a new child in a loop. A changed binding
+for an existing key conflicts. `ctx.suspend(continuation=..., state=..., until=[ref])`
+waits until all listed children are terminal; the next activation can read
+`ctx.get_result(ref_or_key)` for successful output or inspect `ctx.inputs` for
+failures. String keys can also refer to children from earlier activations.
+
+`ctx.workflow(key, program=..., version=..., queue=..., data=...)` stages an owned
+subworkflow with the same retry and attempt-timeout options as `ctx.task`. Both
+methods return references that are not awaitable. Return a checkpoint to dispatch
+work, mixing both reference kinds in `until` when needed:
+
+```python
+child = ctx.workflow("invoice-flow", program="invoice-flow", version="1.0.0",
+                     queue="billing", data=event["data"])
+summary = ctx.task("summary", program="summary", version="1.0.0",
+                   queue="billing", data=event["data"])
+return ctx.suspend(continuation="collect", state=None, until=[child, summary])
+```
+
+Tasks and workflows share the parent-wide key namespace. Reusing a key with a
+different kind conflicts, as does changing its program, input, or scheduling
+options. A child workflow wakes the parent only when the whole child workflow is
+terminal. A completed controller activation by itself does not resolve the wait.
+On resume, use the original string keys with `ctx.get_result(...)`, or inspect
+`ctx.inputs[key]`: task results retain `task_id`, while workflow results have
+`kind="workflow"` and `workflow_id`. Failed or cancelled children are inspectable
+outcomes, and `get_result` raises for them.
+
+Parent cancellation or failure drains owned descendants before becoming terminal.
+Completion with unfinished children is rejected. A decision can stage at most 64
+combined child commands and wait on at most 64 children. Each parent may have at
+most 64 live subworkflows; nested depth is capped at 16 (root depth is zero).
+See [`docs/subworkflows.md`](../../docs/subworkflows.md) for the lifecycle,
+lineage, limits, and upgrade requirements.
+
+External events and durable timers also use explicit checkpoint decisions:
+
+```python
+from ledgence.worker.workflow import workflow_context
+
+def handle(event):
+    ctx = workflow_context()
+    if ctx.continuation == "start":
+        return ctx.wait_event(
+            "callback:1", continuation="received", state={}, timeout_ms=60_000,
+        )
+    wake = ctx.wake
+    if wake["kind"] == "event":
+        return ctx.complete(wake["event"]["data"])
+    return ctx.fail("callback_timeout", "No callback arrived before the deadline")
+```
+
+`ctx.wake` is `None` initially and when no external wait resumed the activation.
+An event wake is `{"kind": "event", "key": ..., "event": <full CloudEvent>,
+"accepted_at": <milliseconds>}`. Event timeouts carry `{"kind": "timeout",
+"key": ..., "deadline": <milliseconds>}`; timers use `kind="timer"` with the same
+key/deadline fields. Returned wake/state/input values are independent JSON copies.
+`ctx.inputs` continues to contain only child outcomes. Event `data` and its original
+context envelope are preserved separately from the controller invocation event.
+Generic events provide application input; only `request_approval` and a durable
+review decision grant the action-bound authority used by `approved_local`.
+
+Return `ctx.sleep("retry:1", 5_000, continuation="retry", state={...})` to register
+a durable timer. Both helpers stage the existing child commands in the same
+checkpoint and end this activation; the Rust orchestrator owns the persisted wait
+and later activation. They do not call `asyncio.sleep` or hold a worker slot until
+the deadline. Timeout/delay values are integer milliseconds from zero through
+31,536,000,000 (365 days). `timeout_ms=None` waits for an event without a deadline.
+Timer deadlines are persisted by the orchestrator when the checkpoint is applied.
+
+Wait keys are one-shot across the workflow run, including later activations.
+Use a fresh key such as `"retry:2"` for the next loop iteration. Reusing a closed
+key does not start another wait. Events can be accepted before their wait is
+registered. An event wake carries at most 64 KiB of complete encoded CloudEvent;
+child inputs plus wake share a 256 KiB encoded budget, and the entire activation
+context retains its 640 KiB budget. Application event data retains depth64 while
+workflow envelope metadata has separate room.
+
+External event IDs are limited to 128 UTF-8 bytes and sources to 2,048 UTF-8
+bytes, in addition to the complete event budget. Sources must be valid URI
+references; encode non-ASCII URI characters with percent escapes.
+
+Rust and Python may spell the same finite float differently. Reading a context
+already accepted by Rust therefore allows a bounded encoding expansion: for each
+float, at most `max(0, len(repr(value)) - 3)` additional bytes. Rust's canonical
+float tokens have at least three bytes; CPython JSON uses that float representation
+(and the helper bounds it at 32 bytes). Existing traversal, string, node and depth
+checks still apply. The allowance covers received state, child inputs, event
+wakes, journal records, copied getters and exact committed-step replay.
+
+New decisions, child commands, local inputs/results and added journal entries
+retain the strict Python encoding limits. Copying a near-boundary received value
+into a new write, or adding to a ledger whose Python encoding expanded, can be
+rejected conservatively even when Rust's representation would fit. Pure reading
+and exact committed replay do not spend a new-write budget.
+
+Each protocol 3 invocation uses a fresh event loop inside the reused Python
+process. Create and close loop-bound clients inside the handler, rather than
+saving them in module globals. Started asynchronous work is drained or cancelled
+before the process is reused. While local operations run, the activation holds
+one consumer/process slot; a committed suspension releases it for other tasks.
+
+Unexpected controller exceptions are retryable activation runtime failures.
+`ctx.fail(...)` explicitly requests workflow failure. Ordinary task output is
+never interpreted as a workflow decision, even when it contains a `kind` field.
+
+See [`docs/workflows.md`](../../docs/workflows.md) for the workflow contract,
+checkpoint limits, cancellation, and recovery semantics.
+