Parent spec: [[spec_0.1h-periods-nests|spec 0.1h — periods and nests]]

Syntax rules: [[05-periods-models|0.4 Periods and models]]

Theory: [[periods-nests-theory|Composition as twister (foundation)]]

Also related: [[20260122-connectors-external-to-periods-for-modularity|CDC #9: connectors external to periods]]

Reference docs:

[[spec_0.1l-branching|spec 0.1l — branching]] (uses "interface" terminology from the newer categorical view)
[[04-methodization|0.3 Methodization]] (no direct impact, but method recipes reference the wiring layer)
[[method-schemes|Method schemes reference]] (schemes attach to targets within stages, not to connectors)

Spec 0.1lA — Connector unification (terminology + placement + syntax)¶

This spec resolves two related issues:

[[20260122-connector-twister-terminology-unification|CDC #8]]: unify "connector" and "twister" terminology
[[20260122-connectors-external-to-periods-for-modularity|CDC #9]]: connectors are external to periods/stages (assembly-level)

1. Decisions¶

1.1 Terminology: unify under "connector"¶

Unify connector and twister under a single term: connector.

The two scopes are distinguished by qualifier:

Canonical term	Scope	Old term	Mathematical object
within-period connector	stage-to-stage (intra-period)	connector	\(\tau : X_{\mathrm{cntn}}(S_i) \xrightarrow{\sim} X_{\mathrm{arvl}}(S_{i+1})\)
between-period connector	period-to-period (inter-period)	twister	\(\tau : X_{\mathrm{cntn}}(P_h) \xrightarrow{\sim} X_{\mathrm{arvl}}(P_{h-1})\)

Both are bijective rename maps on field interfaces. The mathematical structure is identical; the distinction is purely one of scope.

Legacy alias: "twister" remains acceptable in informal usage and older code, but canonical documentation and new code should use "connector" with the appropriate scope qualifier.

1.2 Placement: connectors are external (assembly-level)¶

Connectors belong to the assembly (nest or period-as-assembly), not to the components (stages or periods). A stage declares its interface — what fields it expects at arrival, what it produces at continuation — but not its wiring to any specific neighbor. Wiring is an assembly-level concern.

This means: - Within-period connectors are part of the period assembly, not stored inside individual stages. - Between-period connectors are part of the nest assembly, not stored inside individual periods. - A stage (or period) is a modular, reusable building block that can be composed with any interface-compatible neighbor.

1.3 Consequence: no time indices on connector variables¶

Because connectors are positional — they sit between adjacent periods in the nest sequence — the position alone determines which continuation maps to which arrival. There is no need for time-indexed variables in connectors:

# NOT this:
k[t+1] :=: a[t]

# Just this:
k :=: a

The connector's position in the interleaved sequence is the time information. This reinforces the existing design rule: time indicators live only at the inter-period composition layer (as positional index), never inside stages, periods, or connector field declarations.

2. Rationale¶

The [[periods-nests-theory|unified framework document]] already uses "connector" for both scopes ("Within-Period Connectors" vs "Between-Period Connectors").
Two terms for the same mathematical object adds cognitive overhead.
The foundational principle in [[spec_0.1h-periods-nests|spec 0.1h §3.3.1]] — "the composition is the twister" — applies equally to within-period and between-period composition. Renaming to "connector" preserves this principle.
The [[spec_0.1l-branching|branching spec (0.1l)]] already moves toward "interface" as the unifying concept; "connector" is compatible with that direction.

3. What changes¶

3.1 Documentation updates¶

Document	Current usage	Change needed
[[spec_0.1h-periods-nests]] §3.3	Defines connector vs twister	Rewrite: both are "connector", qualified by scope
[[spec_0.1h-periods-nests]] §3.3.1	"Twister as composition"	Rename heading to "Connector as composition"
[[05-periods-models]] §0.4.0–0.4.2	Uses "twister" for inter-period, "connector" for intra-period	Unify to "connector" throughout
`CLAUDE.md` canonical terminology table	Lists connector and twister separately	Merge into single "connector" entry with scope qualifiers
`MEMORY.md`	References "Connectors = intra-period adapters; Twisters = inter-period adapters"	Update to unified terminology
[[20260122-connector-twister-terminology-unification	CDC #8]]	Issue

3.2 Code updates¶

Location	Current usage	Change needed
`explore/cons-port/` builder scripts	`nest["twisters"]`	Rename key to `nest["connectors_between"]` or keep `nest["connectors"]` with a scope field
Period template dicts	`period["connectors"]`	Stays as-is (already uses "connector")
Any new code	—	Use "connector" with scope qualifier in variable names and comments

3.3 Connector representation (unified YAML and Python)¶

A connector is a field isomorphism — a bijective rename map declaring that two field names denote the same economic field. The conceptual operator is :=: (read "is identified with"):

k :=: a      # field k is identified with field a

Direction (forward for state, backward for value via pullback) is determined by context, not by the syntax.

Data representation (settled)¶

At the data level, a connector is a dict mapping arrival field names to continuation field names:

connector = {"k": "a"}            # single field
connector = {"k": "a", "z": "z"}  # multiple fields

Identity fields (z: z) may be omitted — only non-trivial renames need to be declared. When all fields match by name, the entire connector is identity and may be omitted.

Open decision: YAML surface and period/nest construction

The exact YAML surface syntax for declaring connectors — and how that declaration maps to period and nest construction at the Ρ (representation) level — is not yet settled. Open questions include:

Should connectors appear in a period template YAML (e.g. a connectors: block alongside stages:)? Or are periods always assembled programmatically?
Should the nest YAML use an interleaved sequence (- period: ... - connector: ... - period: ...) or a separate declaration block?
How does the YAML declaration relate to the Python construction API? Is YAML parsed into dicts that feed a builder, or does the builder bypass YAML entirely?
Does a period template file exist at all, or is the period purely a programmatic construct (as suggested in the road-map ambiguities)?

These are syntax/representation decisions that depend on the broader period and nest instantiation design ([[spec_0.1h-periods-nests|spec 0.1h]]). The data-level dict representation above is stable; the YAML surface and construction API are deferred.

Illustrative examples (not normative)¶

The following examples show possible YAML surfaces for orientation. These are not final — see the open decision above.

Within-period:

# Possible period template surface
name: cons_port_period
stages:
  - port_stage
  - cons_stage
connectors:
  - between: [port_stage, cons_stage]
    connector: {m: m}    # identity — may be omitted

Between-period (interleaved nest):

# Possible nest surface
nest:
  sequence:
    - period: P_0
    - connector: {k: a}
    - period: P_1
    - connector: {k: a}
    - period: P_2

4. What does NOT change¶

The mathematical definition of a connector: a bijective rename map \(\tau\) on field interfaces ([[spec_0.1h-periods-nests|spec 0.1h §3.3.1]]).
The composition principle: composition is defined by interface compatibility, witnessed by a connector. The connector is the composition.
The identity convention: when field names match, the connector is identity and may be omitted.
The within-period common-namespace default: stages within a period share a namespace; a within-period connector is needed only when names differ.
The time-at-the-boundary rule: time indicators appear only at the inter-period composition layer. With external positional connectors, this is now fully enforced — no time subscripts appear anywhere in the connector syntax, and the connector's position in the sequence is the only temporal information.

5. Acceptance criteria¶

[ ] [[spec_0.1h-periods-nests]] §3.3 rewritten with unified "connector" terminology
[ ] [[spec_0.1h-periods-nests]] period dict no longer embeds connectors inside periods — connectors are assembly-level
[ ] [[05-periods-models]] updated: "twister" → "between-period connector" throughout; interleaved nest as canonical surface
[ ] CLAUDE.md canonical terminology table updated (merge connector/twister entries; add :=: syntax)
[ ] MEMORY.md updated
[ ] [[20260122-connector-twister-terminology-unification|CDC #8]] marked resolved
[ ] [[20260122-connectors-external-to-periods-for-modularity|CDC #9]] marked resolved
[ ] New code in explore/ and packages/dolo/ uses "connector" (not "twister") and external placement
[ ] Old code and prompts that use "twister" are not broken (legacy alias accepted)