lda-wf/docs/structural_refs.md

Structural Refs

Qualified names are display strings. They are not authoritative identifiers.

The platform still accepts old dotted strings at MCP/API boundaries when it can parse them, but saved workflow artifacts and deployments should store structural refs from now on. A dotted string may be shown to humans and LLM clients, but runtime code should not infer source boundaries from it.

Why

These strings look similar but mean different things:

context7.default.query-docs
workflow.echo_wrapper.v1
demo.foo.bar

context7.default.query-docs usually means a concrete external source and a capability key. workflow.echo_wrapper.v1 means a saved workflow artifact and artifact version. demo.foo.bar is ambiguous: it could be source demo with capability key foo.bar, or source demo.foo with capability key bar.

No first-dot, last-dot, or regex parser can recover a boundary that was not stored.

Capability Refs

Use a source plus a local capability key:

{
  "source": "demo",
  "capability_key": "foo.bar"
}

The capability_key is local to the known source. It may contain dots. Those dots do not carry source meaning.

Old input like "demo.foo.bar" may still parse at compatibility boundaries, but that parse is best-effort and should not be used for new saves.

Workflow Artifact Refs

Saved workflow and wrapper capabilities are a separate domain:

{
  "artifact_id": "echo_wrapper",
  "version": 1
}

The display string workflow.echo_wrapper.v1 remains useful for lists, inspection, and old callers, but it is not the canonical saved shape.

Deployment Bindings

Deployment bindings map an artifact-local logical source to a concrete source:

{
  "logical_source": "demo",
  "concrete_source": "demo.personal"
}

Neither field is a capability name. Runtime code uses this source mapping before looking up the capability key.

Graph Paths

Capability refs and graph paths are different domains.

Path strings such as input.text, state.person.name, and output.echoed describe graph data movement. Do not reuse capability-ref parsing rules for graph paths.

New canonical graph path JSON uses TOML-key strings:

"input.message"

Structural root/parts objects are still accepted at model-parse boundaries and are advertised by generated schemas as an input form. Serializers and new examples should emit strings. Quote a segment when the field name itself contains a dot or space, for example state."person.name" or state.person."full name".

Authoring Path Inputs

wf_authoring accepts ergonomic path inputs and normalizes them into the core path objects before building canonical node bindings.

Single string arguments are TOML key expressions:

state("person.name")  # state -> person -> name
state('"person.name"')  # state -> "person.name"
state('person."full name"')  # state -> person -> "full name"

Varargs and iterables are literal path segments:

state("person.name", "email")  # state -> "person.name" -> email
state(("person.name",))  # state -> "person.name"

Builder canonical bindings use the path kind implied by position:

g.use(
    node,
    input=[
        {
            "target": '"payload.email"',
            "path": 'input."email.address"',
        }
    ],
    output=[
        {
            "source": '"result.score"',
            "target": "state.score",
        }
    ],
)

In an input binding, path is a graph source path and target is a node-local input path. In an output binding, source is a node-local output path and target is a workflow state destination path.

in_map, input_values, and out_map remain deprecated Python sugar for concise authoring. Use canonical binding lists when working from JSON/MCP or when path segments contain display punctuation.

"state.\"person.name\".\"three and four\""

"."

Old strings are accepted at parse boundaries for compatibility. Structural parts are literal field names, so a part may contain dots or spaces without being split again.

Reducer Refs

Reducer refs are capability refs, not graph paths. wf.std.add is shorthand for source wf.std and capability key add.

Configured reducer refs now use a structural CapabilityRef while keeping string reducer names as parse-only shorthand and display keys. Reducer config stays part of the reducer reference payload:

{
  "ref": { "source": "wf.std", "capability_key": "modulo_add" },
  "config": { "modulus": 10 }
}

That shape must not reuse graph path parsing rules. Reducer names live in the capability/source domain.