lda.chat/lda-wf
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: publish structured runtime context

Browse Source
This commit is contained in:
lda
2026-09-05 00:34:58 +07:00 Verified
parent 71dc5ba8e8
commit c389590a9c
17 changed files with 431 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/authoring/test_builder.py
+3 -7
View File
@@ -801,13 +801,9 @@ def test_foreach_reference_treats_dotted_id_as_one_literal_segment() -> None:
state_schema={"type": "object"},
output_schema={"type": "object"},
)
each = builder.foreach(
id="orders.v2", over=state_path("orders"), as_="order"
)
each = builder.foreach(id="orders.v2", over=state_path("orders"), as_="order")
assert each.item == GraphSourcePath(
"context", ("foreach", "orders.v2", "item")
)
assert each.item == GraphSourcePath("context", ("foreach", "orders.v2", "item"))
assert str(each.item) == 'context.foreach."orders.v2".item'
assert str(each.index) == 'context.foreach."orders.v2".index'
@@ -840,5 +836,5 @@ def test_foreach_ref_works_in_node_input_binding() -> None:
input=[input_from(each.item, "order")],
)
binding = work.input[0]
assert isinstance(binding, object)
assert isinstance(binding, InputPathBinding)
assert str(binding.path) == "context.foreach.orders.item"
tests/authoring/test_subgraph.py
+4 -1
View File
@@ -277,6 +277,7 @@ def test_workflow_builder_subgraph_adds_native_subgraph_node() -> None:
def test_foreach_ref_works_in_subgraph_input_binding() -> None:
from wf_authoring import state_path
from wf_core.models.steps import InputPathBinding
child = build_demo_workflow()
parent = WorkflowBuilder(
@@ -291,4 +292,6 @@ def test_foreach_ref_works_in_subgraph_input_binding() -> None:
id="run_child",
input=[input_from(each.item, "order")],
)
assert str(step.input[0].path) == "context.foreach.orders.item"
binding = step.input[0]
assert isinstance(binding, InputPathBinding)
assert str(binding.path) == "context.foreach.orders.item"
tests/core/test_structured_context_validation.py
+33 -27
View File
@@ -86,11 +86,14 @@ def test_active_structured_foreach_item_path_is_valid() -> None:
workflow = _base_workflow(work_path="context.foreach.orders.item")
report = validate_workflow(workflow)
assert _issue(
report,
ValidationIssueCode.INVALID_CONTEXT_PATH,
"nodes[2].input[0].path",
) is None
assert (
_issue(
report,
ValidationIssueCode.INVALID_CONTEXT_PATH,
"nodes[2].input[0].path",
)
is None
)
def test_nested_body_can_read_outer_and_inner_entries() -> None:
@@ -104,18 +107,21 @@ def test_nested_body_can_read_outer_and_inner_entries() -> None:
):
workflow = _base_workflow(work_path=path)
report = validate_workflow(workflow)
assert _issue(
report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[2].input[0].path"
) is None, path
assert (
_issue(
report,
ValidationIssueCode.INVALID_CONTEXT_PATH,
"nodes[2].input[0].path",
)
is None
), path
def test_inactive_foreach_entry_is_rejected() -> None:
from wf_core.validation import validate_workflow
workflow = _base_workflow()
workflow.nodes[3] = _node_use(
"after_inner", path="context.foreach.orders.item"
)
workflow.nodes[3] = _node_use("after_inner", path="context.foreach.orders.item")
report = validate_workflow(workflow)
issue = _issue(
report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[3].input[0].path"
@@ -172,9 +178,7 @@ def test_workflow_output_cannot_read_completed_foreach_entry() -> None:
)
]
report = validate_workflow(workflow)
issue = _issue(
report, ValidationIssueCode.INVALID_CONTEXT_PATH, "output[0].path"
)
issue = _issue(report, ValidationIssueCode.INVALID_CONTEXT_PATH, "output[0].path")
assert issue is not None
@@ -197,9 +201,7 @@ def test_workflow_output_cannot_read_completed_foreach_entry() -> None:
"work",
expression={
"kind": "array",
"items": [
{"kind": "path", "path": "context.foreach.missing.item"}
],
"items": [{"kind": "path", "path": "context.foreach.missing.item"}],
},
),
"nodes[2].input[0].expression.items[0].path",
@@ -235,7 +237,9 @@ def test_all_model_surfaces_reject_missing_foreach_id() -> None:
)
report = validate_workflow(workflow)
assert (
_issue(report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[2].input[0].path")
_issue(
report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[2].input[0].path"
)
is not None
)
@@ -250,14 +254,14 @@ def test_all_model_surfaces_reject_missing_foreach_id() -> None:
Edge.model_validate({"from": "work", "outcome": "true", "to": "orders"}),
Edge.model_validate({"from": "work", "outcome": "false", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": "after_inner"}),
Edge.model_validate({"from": "after_inner", "outcome": "ok", "to": "customers"}),
Edge.model_validate(
{"from": "after_inner", "outcome": "ok", "to": "customers"}
),
Edge.model_validate({"from": "customers", "outcome": "done", "to": END}),
]
report = validate_workflow(workflow)
assert (
_issue(
report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[2].check.path"
)
_issue(report, ValidationIssueCode.INVALID_CONTEXT_PATH, "nodes[2].check.path")
is not None
)
@@ -289,7 +293,9 @@ def test_all_model_surfaces_reject_missing_foreach_id() -> None:
Edge.model_validate({"from": "orders", "outcome": "loop", "to": "work"}),
Edge.model_validate({"from": "work", "outcome": "submitted", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": "after_inner"}),
Edge.model_validate({"from": "after_inner", "outcome": "ok", "to": "customers"}),
Edge.model_validate(
{"from": "after_inner", "outcome": "ok", "to": "customers"}
),
Edge.model_validate({"from": "customers", "outcome": "done", "to": END}),
]
report = validate_workflow(workflow)
@@ -306,9 +312,7 @@ def test_all_model_surfaces_reject_missing_foreach_id() -> None:
from wf_core.models.steps import InputPathBinding as _IPB
workflow = _base_workflow()
workflow.output = [
_IPB.model_validate({"target": "result", "path": bad})
]
workflow.output = [_IPB.model_validate({"target": "result", "path": bad})]
report = validate_workflow(workflow)
assert (
_issue(report, ValidationIssueCode.INVALID_CONTEXT_PATH, "output[0].path")
@@ -381,7 +385,9 @@ def test_sibling_foreach_aliases_may_match_when_never_active_together() -> None:
Edge.model_validate({"from": "left", "outcome": "loop", "to": "left_body"}),
Edge.model_validate({"from": "left_body", "outcome": "ok", "to": "left"}),
Edge.model_validate({"from": "left", "outcome": "done", "to": "right"}),
Edge.model_validate({"from": "right", "outcome": "loop", "to": "right_body"}),
Edge.model_validate(
{"from": "right", "outcome": "loop", "to": "right_body"}
),
Edge.model_validate({"from": "right_body", "outcome": "ok", "to": "right"}),
Edge.model_validate({"from": "right", "outcome": "done", "to": "join"}),
Edge.model_validate({"from": "join", "outcome": "ok", "to": END}),
tests/core/test_structured_runtime_context.py
+141 -14
View File
@@ -68,7 +68,9 @@ def test_root_frame_has_empty_structured_foreach_context() -> None:
def test_nested_same_scope_frames_expose_outermost_to_innermost_context() -> None:
run = _run_with_frames(
[
ExecutionFrame(id="root", kind="root", node_id="customers", scope_id="root"),
ExecutionFrame(
id="root", kind="root", node_id="customers", scope_id="root"
),
_item_frame(
frame_id="outer-item",
parent_id="root",
@@ -119,7 +121,9 @@ def test_nested_same_scope_frames_expose_outermost_to_innermost_context() -> Non
def test_graph_context_values_keep_all_aliases_and_innermost_loop_keys() -> None:
run = _run_with_frames(
[
ExecutionFrame(id="root", kind="root", node_id="customers", scope_id="root"),
ExecutionFrame(
id="root", kind="root", node_id="customers", scope_id="root"
),
_item_frame(
frame_id="outer-item",
parent_id="root",
@@ -158,7 +162,9 @@ def test_graph_context_values_keep_all_aliases_and_innermost_loop_keys() -> None
def test_context_ancestry_stops_at_runtime_scope_boundary() -> None:
run = _run_with_frames(
[
ExecutionFrame(id="root", kind="root", node_id="customers", scope_id="root"),
ExecutionFrame(
id="root", kind="root", node_id="customers", scope_id="root"
),
_item_frame(
frame_id="outer-item",
parent_id="root",
@@ -290,7 +296,9 @@ def test_structured_context_rejects_duplicate_active_alias() -> None:
def test_context_read_does_not_mutate_run_state() -> None:
run = _run_with_frames(
[
ExecutionFrame(id="root", kind="root", node_id="customers", scope_id="root"),
ExecutionFrame(
id="root", kind="root", node_id="customers", scope_id="root"
),
_item_frame(
frame_id="outer-item",
parent_id="root",
@@ -369,7 +377,9 @@ def _nested_workflow(*, inner_over: str = "state.orders_list"):
),
Edge.model_validate({"from": "orders", "outcome": "loop", "to": "work"}),
Edge.model_validate({"from": "work", "outcome": "ok", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": "customers"}),
Edge.model_validate(
{"from": "orders", "outcome": "done", "to": "customers"}
),
Edge.model_validate({"from": "customers", "outcome": "done", "to": END}),
],
)
@@ -398,9 +408,7 @@ def test_nested_handler_receives_outer_and_inner_typed_entries() -> None:
{"record": record},
)
assert run.status == RunStatus.COMPLETED
assert seen == [
(("customers", "orders"), {"name": "Ada"}, {"sku": "A-17"}, 0)
]
assert seen == [(("customers", "orders"), {"name": "Ada"}, {"sku": "A-17"}, 0)]
def test_nested_graph_bindings_resolve_outer_and_inner_items() -> None:
@@ -672,9 +680,7 @@ def test_concurrent_items_receive_distinct_frame_and_lineage_context() -> None:
contexts.append(ctx.foreach["each"])
return {"outcome": "ok", "output": {}}
run = execute_workflow(
workflow, {"items": ["a", "b"]}, {"record": record}
)
run = execute_workflow(workflow, {"items": ["a", "b"]}, {"record": record})
assert run.status == RunStatus.COMPLETED
assert len(contexts) == 2
assert contexts[0].activation_id == contexts[1].activation_id
@@ -686,9 +692,7 @@ def test_concurrent_items_receive_distinct_frame_and_lineage_context() -> None:
def test_nested_foreach_over_resolves_structured_outer_item_path() -> None:
from wf_core import execute_workflow
workflow = _nested_workflow(
inner_over="context.foreach.customers.item.orders"
)
workflow = _nested_workflow(inner_over="context.foreach.customers.item.orders")
captured: list[object] = []
def record(payload: dict[str, object], _ctx: RuntimeContext) -> dict[str, object]:
@@ -705,3 +709,126 @@ def test_nested_foreach_over_resolves_structured_outer_item_path() -> None:
)
assert run.status == RunStatus.COMPLETED
assert captured == [{"sku": "A-17"}]
def test_interrupt_resume_recreates_structured_context_identities() -> None:
from wf_core import (
END,
Edge,
ForeachNode,
InterruptNode,
NodeDef,
NodeUse,
SchemaRef,
Workflow,
execute_workflow,
resume_workflow,
)
from wf_core.models.schemas import StateField, StateSchema
from wf_core.run_codec import dump_run_state, load_run_state
workflow = Workflow(
name="nested_interrupt_resume",
input_schema=SchemaRef(type="object", properties={}),
state_schema=StateSchema.from_field_map(
{
"customers": StateField(type="array"),
"orders_list": StateField(type="array"),
}
),
output_schema=SchemaRef(type="object", properties={}),
node_defs=[
NodeDef(
name="record",
input_schema=SchemaRef(type="object", properties={"value": {}}),
output_schema=SchemaRef(type="object", properties={}),
outcomes=["ok"],
)
],
start="outer",
nodes=[
ForeachNode.model_validate(
{
"id": "outer",
"type": "foreach",
"over": "state.customers",
"as": "customer",
"mode": "serial",
}
),
ForeachNode.model_validate(
{
"id": "inner",
"type": "foreach",
"over": "state.orders_list",
"as": "order",
"mode": "serial",
}
),
NodeUse.model_validate(
{
"id": "pre",
"type": "node",
"node": "record",
"input": [{"target": "value", "path": "context.order"}],
"output": [],
}
),
InterruptNode.model_validate(
{"id": "ask", "type": "interrupt", "kind": "approval", "request": []}
),
NodeUse.model_validate(
{
"id": "post",
"type": "node",
"node": "record",
"input": [{"target": "value", "path": "context.order"}],
"output": [],
}
),
],
edges=[
Edge.model_validate({"from": "outer", "outcome": "loop", "to": "inner"}),
Edge.model_validate({"from": "inner", "outcome": "loop", "to": "pre"}),
Edge.model_validate({"from": "pre", "outcome": "ok", "to": "ask"}),
Edge.model_validate({"from": "ask", "outcome": "submitted", "to": "post"}),
Edge.model_validate({"from": "post", "outcome": "ok", "to": "inner"}),
Edge.model_validate({"from": "inner", "outcome": "done", "to": "outer"}),
Edge.model_validate({"from": "outer", "outcome": "done", "to": END}),
],
)
before: list[dict[str, ForeachContext]] = []
after: list[dict[str, ForeachContext]] = []
phase = {"value": "before"}
def record(_payload: dict[str, object], ctx: RuntimeContext) -> dict[str, object]:
snapshot = dict(ctx.foreach)
if phase["value"] == "before":
before.append(snapshot)
else:
after.append(snapshot)
return {"outcome": "ok", "output": {}}
run = execute_workflow(
workflow,
{"customers": [{"name": "Ada"}], "orders_list": [{"sku": "A-17"}]},
{"record": record},
)
assert run.status == RunStatus.INTERRUPTED
assert len(before) == 1
# Genuinely test reconstruction: dump, reload, resume from loaded state.
payload = dump_run_state(run)
reloaded = load_run_state(payload)
phase["value"] = "after"
resumed = resume_workflow(workflow, reloaded, {"record": record}, resume_payload={})
assert resumed.status == RunStatus.COMPLETED
assert len(after) == 1
before_outer = before[0]["outer"]
after_outer = after[0]["outer"]
before_inner = before[0]["inner"]
after_inner = after[0]["inner"]
assert after_outer.activation_id == before_outer.activation_id
assert after_inner.activation_id == before_inner.activation_id
assert after_inner.frame_id == before_inner.frame_id
assert after_inner.lineage_id == before_inner.lineage_id
assert after_inner.item == before_inner.item
tests/core/test_subgraph_step.py
+141
View File
@@ -11,6 +11,7 @@ from wf_core import (
NodeUse,
PreparedSubgraph,
RunState,
RunStatus,
SchemaRef,
StateField,
StateSchema,
@@ -425,3 +426,143 @@ def _interrupting_child_workflow() -> Workflow:
def _schema(properties: dict[str, object]) -> SchemaRef:
return SchemaRef.model_validate({"type": "object", "properties": properties})
def test_subgraph_does_not_inherit_caller_foreach_context() -> None:
from wf_core import ForeachNode, RuntimeContext
child_seen: dict[str, object] = {}
pre_seen: dict[str, object] = {}
def probe(payload: dict[str, object], ctx: RuntimeContext) -> dict[str, object]:
if ctx.current_node_id == "pre":
pre_seen["foreach"] = dict(ctx.foreach)
pre_seen["input_order"] = payload.get("order")
else:
child_seen["input_order"] = payload.get("order")
child_seen["context"] = ctx
return {"outcome": "ok", "output": {}}
child = Workflow(
name="child.workflow",
input_schema=_schema({"order": {"type": "object"}}),
state_schema=StateSchema.from_field_map(
{
"order": StateField(type="object"),
"child_items": StateField(type="array", default=["child-item"]),
}
),
output_schema=_schema({}),
node_defs=[
NodeDef(
name="probe",
input_schema=_schema({"order": {}}),
output_schema=_schema({}),
outcomes=["ok"],
)
],
start="pre",
nodes=[
NodeUse.model_validate(
{
"id": "pre",
"type": "node",
"node": "probe",
"input": [{"target": "order", "path": "input.order"}],
}
),
ForeachNode.model_validate(
{
"id": "orders",
"type": "foreach",
"over": "state.child_items",
"as": "c_order",
"mode": "serial",
}
),
NodeUse.model_validate(
{
"id": "work",
"type": "node",
"node": "probe",
"input": [{"target": "order", "path": "input.order"}],
}
),
],
edges=[
Edge.model_validate({"from": "pre", "outcome": "ok", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "loop", "to": "work"}),
Edge.model_validate({"from": "work", "outcome": "ok", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": END}),
],
)
parent = Workflow(
name="parent_orders",
input_schema=_schema({}),
state_schema=StateSchema.from_field_map(
{"parent_orders": StateField(type="array")}
),
output_schema=_schema({}),
node_defs=[
NodeDef(
name="noop",
input_schema=_schema({}),
output_schema=_schema({}),
outcomes=["ok"],
)
],
start="orders",
nodes=[
ForeachNode.model_validate(
{
"id": "orders",
"type": "foreach",
"over": "state.parent_orders",
"as": "p_order",
"mode": "serial",
}
),
SubgraphNode.model_validate(
{
"id": "run_child",
"type": "subgraph",
"workflow": "child.workflow",
"input_schema": _schema({"order": {"type": "object"}}),
"output_schema": _schema({}),
"input": [
{
"target": "order",
"path": "context.foreach.orders.item",
}
],
"output": [],
}
),
],
edges=[
Edge.model_validate(
{"from": "orders", "outcome": "loop", "to": "run_child"}
),
Edge.model_validate({"from": "run_child", "outcome": "ok", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": END}),
],
)
run = execute_workflow(
parent,
{"parent_orders": [{"sku": "A-17"}]},
{},
subgraphs={
"child.workflow": PreparedSubgraph(
workflow=child, registry={"probe": probe}
)
},
)
assert run.status == RunStatus.COMPLETED
assert child_seen["input_order"] == {"sku": "A-17"}
ctx = child_seen["context"]
assert isinstance(ctx, RuntimeContext)
assert tuple(ctx.foreach) == ("orders",)
assert ctx.foreach["orders"].item == "child-item"
assert ctx.foreach["orders"].scope_id != "root"
assert pre_seen["foreach"] == {}
assert pre_seen["input_order"] == {"sku": "A-17"}
tests/wf_api/test_authoring_contracts.py
+6 -2
View File
@@ -491,8 +491,12 @@ def test_structured_foreach_paths_appear_in_authoring_inventory() -> None:
Edge.model_validate(
{"from": "orders", "outcome": "loop", "to": "inner_body"}
),
Edge.model_validate({"from": "inner_body", "outcome": "ok", "to": "orders"}),
Edge.model_validate({"from": "orders", "outcome": "done", "to": "customers"}),
Edge.model_validate(
{"from": "inner_body", "outcome": "ok", "to": "orders"}
),
Edge.model_validate(
{"from": "orders", "outcome": "done", "to": "customers"}
),
Edge.model_validate({"from": "customers", "outcome": "done", "to": END}),
],
)