Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions docs/parent-expressions-2026-10-06.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# `parent()` in expressions (VN36)

COMP-model proposal 01 §2.3 and proposal 02 (the `parent.<key>` row). Stacked on VN35
(`a5c77599`).

## What it is

```
parent().par.gain * 0.5 + op('lfo_wobble').chan.value
parent(2).par.throw two components out
parent().par.tint.r one component of a published compound (§V113)
```

`parent()` is `parent(1)`, and `n` is a positive integer literal. After `parent(n)` the
grammar takes `.par.<key>` with an optional `.<component>`, and nothing else. That is
checked at parse time, so `parent().chan.x` and `parent(0)` are syntax errors that say what
to write. A bare `parent` is still a variable name; only `parent(` changes meaning.

The AST gains `{ kind: "parentRef", hops, path, at, end }`. The span is a pure function of
the text, so the parse memo (T1172) still holds. The three exhaustive walks over
`ExpressionAst` handle the new node. A `parentRef` is not an `op()` dependency in the
authored document (§V81: a lexical read, never an edge). Reaching the evaluator unrewritten
means the expression is not inside a component, and it fails as `reference.unreadable` with
that reason. It never reads 0.

## How it reads: a name at flatten, a value per frame

This follows TouchDesigner. `parent()` returns the parent COMP, its `.par.Gain` evaluates
once where it lives, and readers get the number. They never get the formula.

1. **Flatten resolves a name** (`src/compiler/parent-references.ts`, called beside
`effectiveParameters`). `parent(n).par.key` becomes
`op('<the n-th enclosing instance>').par.key`. It runs as each node's parameters are made,
including an instance's own page. That ordering matters for T1017: an animated page slot
is carried INWARD onto its targets as text, and a `parent()` inside it means the component
around the instance. Resolved here, it is carried as a name, which means the same thing
at every depth. In VN35's end-of-walk pass it would be resolved one level too deep (a
test pins this).
2. **The reader reads a dissolved instance's page** (`node-references.ts`). Flattening
deletes the instance node. Its page survives as `FlattenedGraph.instancePages` (label →
the instance as flattened, plus its published schema), and `op('<instance>').par.<key>`
resolves there through the same `targetOf` as any node. This is T1485b's shape for
`.chan`, applied to `.par`. So an animated knob is evaluated once per frame at its
publisher, and an edit to it reaches every reader with the next flattening.
`flattenComponents` stays a pure function of the document (§V529).

Same rule as §V81: the read goes through the published page (§V80) and only that. A value
set on a nested instance's page, or on a private nested page, is read exactly where it is
set. `publishedKeyOrigins` is not involved.

As a side effect, `op('comp1').par.gain` from OUTSIDE a component is readable too. That is
TD's idiom.

### What sees the page

- **`FlatteningReads.instancePages` is required** (T1551b's rule). Every reader site says it:
the compile and the per-frame compile (beside `resolution.instances`), the value graph, the
OSC pump, parameter commands, the controls pane, the inspector (the root flattening's
pages while you are inside an instance), and the test harnesses.
- **Value-graph order.** The dependency walk follows `op('<instance>').par.<key>` into the
page and on to whatever the page knob reads. A Constant inside a component that reads a
page knob reading a root LFO therefore evaluates after the LFO in the same frame, not one
frame late. (T1485b's `.chan` branch had been catching `.par` reads of an instance name
too. It is now channel-only.)
- **Liveness.** `pruneToActiveSinks` adds each page as a liveness node that is never a
candidate, so a node read only by a page knob, through `parent()`, is not reported dead.

## Diagnostics

Both are warnings, and both fall back to the slot's retained static (§V108), exactly as a
failing `parent.` bind does. One problem gives one diagnostic, and the value is never 0.
Class `never`.

| code | when |
|---|---|
| `compiler/parent-reference-no-parent` | `parent()` on a root node, `parent(n)` past the outermost component, or an enclosing instance with no name |
| `compiler/parent-reference-unknown-key` | the component publishes no `key`. Lists what it does publish, with the nearest spelling |

A component name the page lacks, or a compound read whole, is refused per frame by the
reader, like any `op()` read. At the root, `flatteningIsIdentity` treats a `parent()` read as
it treats a `parent.` bind: it takes the full walk, so the diagnostic is raised.

## Detach

`component.detach` lands the copies at the instance's own level. `parent(n ≥ 2)` loses one
hop. `parent().par.k` becomes what the page key is from that level:
- its carried `parent.` source, re-aimed as a `parent()` read;
- the instance's own expression for it, inlined (it was written at that very level);
- or its value.

A read the copies cannot make the same way is reported (`component.detach.inexact`), and
the copy holds its static. `nestedParentReads` counts `parent(n)` too.

## Unchanged

- `parent.<key>` binds keep their current behaviour. That includes the fact that a bind
BAKES the page value, so an animated knob does not animate through a bind; only the §V80
fan-out and now `parent()` carry it live. VN38 migrates binds.
- Reference cycles (§V152). A ring through the boundary (a page knob reads an inner node
that reads `parent()`) is a plain `(node, key)` ring for the reader's guard, which names
it at runtime. The authoring-time refusal does not see it yet.
- Rename (§V128). `parent()` names no node. The rewritten name is a flattening artifact and
is never stored.

## Stage-1 bridge

`instancePages`, the value-graph look-through and the liveness entries exist because the
instance is dissolved. Once a COMP is a real node in the flat graph (proposal 01 stages 2–3),
the name index finds it and they retire together. The grammar, the rewrite to a name, and
the diagnostics are permanent.

## Tests

- Dawn (`parent-expressions.gpu.test.ts`), through the app's commands: Lamp (a Solid, red =
`parent().par.gain`, green = `1 - parent().par.gain`), placed twice with gain 1 and 0,
renders pure red and pure green. With the publish cut, both instances render their static
black and raise four `unknown-key` warnings. An animated page knob (`frame % 2`) gives two
frames and two colours.
- Integration (`parent-expressions.test.ts`): two instances; animated; cut; misspelt key;
`parent(2)`; a nested page value; a nested page that itself reads `parent()`; a page slot
carried inward (T1017); too deep; root; value-graph order; liveness.
- Reader (`instance-parameter-reference.test.ts`): page value, animated, a component, an
unknown key, and the per-frame values-only compile against the full compile.
- Grammar (`parent-reads.test.ts`), detach (`detach.test.ts`).
- Every gate red-verified by editing the code and restoring it.

## Next

- VN60: delete stage-previz-8's 17 knob holders onto `parent()`.
- Preset morphs through `parent()`: the reader resolves the page node by its flat id, and
the morph index keys a root instance's fade by that same id, so it should fade. No test
pins it yet.
- Completion: offer `parent().par.` keys, and `op('<instance>').par.` keys (§V150 allows
offering less than the reader accepts, and this does).
- Authoring-time refusal of a ring through the boundary.
- VN38 (two-way bind) and VN43 (`parent.Name` shortcuts).
127 changes: 127 additions & 0 deletions docs/path-names-2026-10-06.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Path-aware names (COMP-model stage 1, VN35)

Proposal: `docs/comp-model-2026-10-06/01-comps-as-folders.md` (laubsauger/loom#3) §2.2, §3.2, §4 stage 1, §6.4. Upstream T1701b rates these paths "low regret".

## The bug, restated

`withUniqueNames` (flatten.ts) makes every label globally unique on the flat graph and renumbers
collisions inside instances. That keeps references *inside* an instance pointing at that instance's
own nodes (B41, §V320/§V321). But an outer reference can only reach in by a bare name, and a bare
name binds whichever copy kept its spelling, which is the first one. Instance a Projector three times
and an outer Render naming `projector_beam` binds copy 1 three times, or binds copies 2 and 3 not at
all. No diagnostic is raised.

## Decisions

1. **A path segment is a node's NAME (its label), as written in the graph it lives in.**
- For a node inside an instance, that is the label in the *definition*, never the B41-renumbered
flat label. An author never sees the flat label.
- The flat id (`inst/inner`, built from ids) stays the machine address. `addressing.ts` owns it.
- A path is the human address, and it resolves to a flat id.
- An instance with no label has no path, the same rule as any unnamed node (§V127).

2. **Syntax: relative only.**
- `a/b`: relative to the graph the referring node lives in.
- `../x`: one level up, to the graph that holds the referring node's instance. `..` may repeat.
- There is no absolute form. At the root a relative path already is the absolute one.
Inside a definition, `/a/b` would name a document the definition cannot know, and a
rename could not tell whether it was running at the root.
- A leading `/`, an empty segment, and a `..` after a name are malformed.
- There is no `.` segment.
- A token with no `/` is a bare name and keeps today's rules (see 4).

3. **Mechanism: resolve once, at flatten, in the same walk as B41.**
- Flatten already knows every level's authored labels, every instance's label and its scope.
- After the walk, each path reference on the flat graph is rewritten to the target's
(unique) flat label.
- Every downstream reader stays unchanged: source-reference synthesis, the `op()` reader,
liveness, channels, and the dependency walk over the flat graph.
- A path that does not resolve is left as written and hits the existing refusals:
`sourceReference.missing` is an error that names the path, and a failed `op()` falls back
to §V108 with its reason.
- Parsing and resolving a path go in `addressing.ts` (`parseNodePath`, `resolveNodePath`), so
`flat-id-joiner.test.ts` stays green and there is still only one joiner.
- Covered: `op('…')` in expression bindings, and every `SOURCE_REFERENCE_PARAMETERS` entry
(Render scenes/camera/lights/projectors, Light casters, Geometry material, Feedback source,
the renderers' camera, Camera Blur, Window, Layer).

4. **Bare names: resolution unchanged, plus a deprecation warning when one reaches INTO an instance.**
- New code `compiler/reference-cross-scope` (warning), registered in `classes.ts` and `class-reasons.ts`.
- It fires when a bare `op()` or source-reference name lands on a node that is neither in the
referrer's own graph nor in one of its ancestors' graphs.
- The message gives the path to write. When the name is carried by N instances, it also says
that only the first one binds, which is the silent mis-bind made visible.
- Reading OUTWARD stays silent: a component reading a root node by bare name is ordinary
lexical scope.
- Old files keep working exactly as they do now. Nothing changes until someone writes a path.
- Known pre-existing quirk, documented and not changed: with three nested levels, a bare name
that the middle level shadows resolves to the root node rather than the middle one, because
B41 rewrites only a level's own references. Under true lexical scoping it would bind the
middle node. Changing that changes how old files behave, so it is left for stage 2.

5. **Rename (§V128).**
- Renaming node `x` rewrites, in the same patch:
- bare `x`, as today;
- paths whose first segment is `x`, in the same graph (`renamedPathHead`).
- Not rewritten:
- a path that reaches into a definition from outside, when a node inside the definition is
renamed (the definition is shared and does not know its users);
- `../x` written inside a definition.
- Both cases are exactly where bare names stand today. The dangling path is an error that names
the path. Stage 2 (folders) closes this.
- B41's internal renumbering will NOT rewrite paths. It keeps rewriting bare names only, so a
path is always read in authored-label space.

6. **`/` in labels: converted at the naming door, refused at the exact doors.** This follows TD's
`tdu.validName`, which turns illegal characters into underscores, slashes included.
- `node.rename` already does what `validName` does: a name that does not conform goes through
`roleFromText`, which turns every run of characters other than letters, digits and `_` into
one `_`. So `rig/a` becomes `rig_a` there, as it did before.
- The doors that store a label exactly (`addNode` with a label, `setNodeLabel`, and so
`rename` with `exact: true`) store what they are given (§V324), so they refuse instead. The
code is `node.label.separator`, and the suggestion names the `validName` form.
- Only `/` is refused. Spaces and other characters still pass the exact doors, as they did,
because older documents and agent patches use them.
- No shipped document has a `/` in a label. A node already labelled `a/b` still loads, but it
is unaddressable by name until it is renamed.

7. **`kind_role` (T1593b).**
- Each segment is a node name and conforms on its own: `projector_left/projector_beam`.
- A path is not a name. It has no kind and is never kind-prefixed.
- `node-names.test.ts` is unaffected.

## Out of scope (rows that already exist or follow)

- `parent()` in expressions (VN36).
- Nested override keys (VN33's codec).
- Paths in preset targets, panel boards, cue lists and Channel In.
- The inspector's authored-graph `op()` read reaching into an instance. A bare name does not reach
there today either, so this is not a regression. It's for stage 2 or a follow-up row.

## Gate (the PR's claim), Dawn, through the app's commands

- **Setup.** One `projector_beam` saved as component "Projector" and instanced three times. Each
instance gets its own aim and a pure R, G or B cookie through VN33's `internalNodeId` overrides.
The outer `render_stage` names
`projectors: "projector_left/projector_beam projector_mid/projector_beam projector_right/projector_beam"`.
- **Claim.** Each third of the stage is lit only by its own projector's colour, which is only
possible if three different projectors are bound.
- **Red-verify.** Against today's code the paths dangle (`sourceReference.missing`). The literal old
bug gets a test of its own: the bare `projector_beam` lights only the left third, and now also
raises `compiler/reference-cross-scope`.
- **Unit tests.**
- Path parse and resolve: relative, `..`, malformed, not found, through an unlabelled instance.
- The rename rewrite of path heads.
- The label refusal.
- The cross-scope warning firing for inward bare names and staying silent for outward ones.

## Measured

- **Shipped documents.** Every example and starter component, and every project under
`projects/`.
- Not one shipped example raises `compiler/reference-cross-scope`.
- `projects/stage-previz/stage-previz-8.loom.json` raises 52 warnings, one per node and name.
These are exactly the leaks proposal 01 §2.2 describes. Converting that file to paths is
its own change.
- **Cost.** The pass adds about 0.15 ms to a flatten of stage-previz-8 (0.53 to 0.68 ms on an
M-series Mac). Flatten runs once per document revision, not once per frame.
Loading
Loading