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
1 change: 1 addition & 0 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -1724,6 +1724,7 @@ V131: a variadic port's input ORDER is explicit & user-controllable — the edge
V132: variadic UI = n connected slots + 1 free, reorder by drag. reorder = 1 patch, 1 undo entry (V15). the free slot is how "1+n" is discoverable ⊥ documentation.
V127: node `name` = a unique IDENTIFIER within its graph, auto-numbered on collision (`noise1`, `noise2`). ⊥ decoration: it is the reference target for binds + expressions (V110), so uniqueness ! precede reference syntax.
V128: rename rewrites ∀ reference naming that node, ∈ the SAME patch — else a rename silently breaks a bind. rename is graph-wide, ⊥ node-local.
VN35: relative name paths (`instance/node`, `../node`) address one component copy in `op()` and source-reference parameters. Resolve against authored names once during flattening, retaining each parameter's authoring scope through publication and parent binds. Single-value references retain spaces in names; list references retain order. Exact naming doors refuse `/`. Every graph-patch writer shares command-time cycle validation against the same component projection as the compiler, including definition edits, dry runs and renames; unrelated edits remain possible in a file carrying a pre-existing cycle. Bare inward references retain their binding and warn with the explicit path to write. See `docs/path-names-2026-10-06.md`.
V129: a rename collision auto-suffixes, ⊥ rejects. the user's intent is the word; the number is bookkeeping, & a modal saying "name taken" is the tool arguing w/ a decision already made.
V123: `pulse` = a parameter type, ⊥ a node feature — declared once, available to any node (TD Pulse). ∀ node w/ `stateful.reset === true` (V46) SHOULD expose one.
V124: a pulse mutates RUNTIME state, ⊥ document state ∴ audited (V31), ⊥ undoable, ⊥ serialized. a pulse persisted as "on" would re-fire on load & wipe your work every open.
Expand Down
147 changes: 147 additions & 0 deletions docs/path-names-2026-10-06.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# 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.
- A projected parameter retains its authoring scope. A published expression written on
a root instance page resolves there even when its value fans out to an internal node;
a nested page's own expression resolves in that instance's enclosing definition.
Parent-bound source strings retain the same scope. Internal overrides use their target
node's scope. Single-value source references are resolved whole, so names with spaces
remain valid; only list-valued source parameters are split into tokens.
- 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.
- The patch gate validates a hypothetical draft using this same component projection.
The validator lives on `CommandContext`, so parameter commands, renames and graph
patches share it. A definition edit is projected into its linked instances without
changing the catalogue. A path that closes a parameter cycle is rejected atomically,
including dry runs; an unrelated edit can still repair a file carrying another cycle.
- 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).
- Internal parameter writes use main's validated descendant API, including nested paths.
- 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.

## Original VN35 measurements

- **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.

## Landing validation

The branch is ported onto main without #4's unchecked writer or nested-mesh refusal.
Regression checks cover single paths with spaces, published and parent-bound scopes,
command-time cycle rejection through parameter commands and definition sessions, renames,
dry runs, and repair of unrelated nodes. A CPU check builds the three-projector fixture
through the real app commands and verifies its distinct bindings, aims and colours. The
Dawn pixel checks still require a real adapter and fail explicitly when it is unavailable.
2 changes: 2 additions & 0 deletions src/app/app-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { allNodeDefinitions } from "@nodes/definitions/index.ts";
import { createNodeRegistry } from "@nodes/registry/registry.ts";
import { createComponentSystem, registerComponentCommands } from "@domain/components/index.ts";
import { createFlattenedGraphSource } from "./flattened-graph.ts";
import { createReferenceCycleValidator } from "./reference-cycle-validation.ts";
import type { FlattenedGraphSource } from "./flattened-graph.ts";
import { installStarterComponents } from "@editor/component/index.ts";
import type { StarterSetInstall } from "@editor/component/index.ts";
Expand Down Expand Up @@ -339,6 +340,7 @@ export function createAppRuntime(options: AppRuntimeOptions = {}): AppRuntime {
// T615: the ONE flattening. Built beside the bus so a frame path has somewhere to read
// the flattened document FROM, and the raw one has no reason to be read at all.
const flattened = createFlattenedGraphSource({ store: bus.store, registry, components });
bus.attachReferenceCycleValidator(createReferenceCycleValidator({ registry, components: () => components.view(), root: bus.store.getGraph }));
const openedAssets = project.assets;
// A file binding already mutates through the parameter command. Its external asset
// record is a pure projection, shared by snapshots, manual save and project queries.
Expand Down
57 changes: 57 additions & 0 deletions src/app/reference-cycle-validation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import { flattenComponents } from "../compiler/flatten.ts";
import type { ReferenceCycleValidator } from "../domain/commands/bus.ts";
import { isComponentInstance, readComponentInstance } from "../domain/components/instance.ts";
import { isWithinInstance, toInstance } from "../domain/components/addressing.ts";
import type { ComponentRegistryView } from "../domain/components/registry.ts";
import { keyReads } from "../domain/graph/parameter-dependencies.ts";
import { channelDependenciesOf, referenceCyclesThrough } from "../domain/graph/reference-cycles.ts";
import type { GraphDocument } from "../domain/types/graph.ts";
import type { NodeRegistryView } from "../nodes/registry/registry.ts";

/** Validates hypothetical edits with the compiler's projection, without changing the catalogue. */
export function createReferenceCycleValidator(input: {
readonly registry: NodeRegistryView;
readonly components: () => ComponentRegistryView;
readonly root: () => GraphDocument;
}): ReferenceCycleValidator {
const channels = (node: GraphDocument["nodes"][string]) => channelDependenciesOf(input.registry.get(node.type));
return (draft, nodeId, host) => {
const edited = draft.nodes[nodeId];
if (edited === undefined) return [];
const authoredCycles = referenceCyclesThrough(draft, nodeId, channels);
if (authoredCycles.length > 0) return authoredCycles;
if (host === undefined && !Object.values(draft.nodes).some(isComponentInstance)) return [];
if (host === undefined && !isComponentInstance(edited) && !keyReads(edited.parameters).some(read => read.node !== null)) return [];
const components = input.components();
let graph = draft;
let projected = components;
if (host !== undefined) {
const definition = components.get(host.componentId, host.version);
if (definition === undefined) throw new Error(`Reference validation cannot find component ${host.componentId}@${host.version}`);
const replacement = { ...definition, graph: draft };
projected = { ...components,
get: (id, version) => id === host.componentId && version === host.version ? replacement : components.get(id, version),
graphOf: (id, version) => id === host.componentId && version === host.version ? draft : components.graphOf(id, version),
};
graph = input.root();
}
let flat = flattenComponents({ graph, registry: input.registry, components: projected });
const focuses: string[] = [];
if (host === undefined) focuses.push(nodeId);
else for (const [id, node] of flat.instanceNodes) {
const instance = readComponentInstance(node);
if (instance?.componentId === host.componentId && instance.version === host.version) focuses.push(toInstance([id], nodeId));
}
// A library definition with no live instances is validated as its own authored graph.
if (host !== undefined && focuses.length === 0) {
flat = flattenComponents({ graph: draft, registry: input.registry, components: projected });
focuses.push(nodeId);
}
const found = new Map<string, ReturnType<ReferenceCycleValidator>[number]>();
for (const id of Object.keys(flat.graph.nodes)) {
if (!focuses.some(focus => isWithinInstance(id, focus))) continue;
for (const diagnostic of referenceCyclesThrough(flat.graph, id, channels)) found.set(diagnostic.message, diagnostic);
}
return [...found.values()];
};
}
6 changes: 6 additions & 0 deletions src/compiler/diagnostics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,12 @@ export const CompilerDiagnosticCode = {
sourceReferenceMissing: "compiler/source-reference-missing",
/** T350: a source reference AND a wired input on the same loop — one truth. */
sourceReferenceAmbiguous: "compiler/source-reference-ambiguous",
/**
* VN35: a BARE name (`op()` or a source reference) that reaches into a component instance
* the referring node is not in. It binds, first-wins, as it always has; the path that
* names the intended copy is the fix (proposal 01 §2.2).
*/
referenceCrossScope: "compiler/reference-cross-scope",
/**
* T546: more than one renderer frames itself with this camera, so "what the renderer
* sees" has no single answer and the preview shows the stock reference scene. INFO, not
Expand Down
Loading
Loading