Files

Source authoring A/B experiment

Status: bounded executable experiment, 2026-09-05. Not production syntax or a release-completion claim. Owns this directory only. The standalone Rust workspace depends on the real oa-core and never compiles Iced. Main checkpoint during verification: 06b33848cea5a0b1a6168d79a68e5185c190383e.

The initial lowering experiment below was committed separately as c5788fc. The subsequent source-preserving writeback gate and its additional evidence are recorded in WRITEBACK.md. The one-way-only limitation below describes the initial checkpoint, not the later experimental writer.

Question and competing expectations

Does semantic ownership nesting, typed function-port/exchange shorthand and ordered occurrence blocks reduce the coordination burden of text-first OA/SA modeling without introducing different semantics or unstable identities?

  • A: source3 declarations organized by semantic aggregate. Expected advantage: simple exact mapping, easy reference edits, existing tooling. Possible failure: parent/endpoints/ordered-list bookkeeping remains dispersed even in small files.
  • B: the same model with actual ownership nesting and three bounded syntactic conveniences. Expected advantage: fewer redundant references and local owner context. Possible failure: more lines, ambiguous ownership versus allocation, costly writeback, or loss of precise model control.

The comparison deliberately uses compact, well-organized A, not a UUID-sorted/full-default straw man. Both candidates retain full explicit UUIDs. This experiment does not compare human completion time or establish that fewer tokens means easier modeling.

Method

Six independently authored fixtures define three complete model pairs:

  1. oa-*.arcadia: two performers, an activity decomposition, a carried item, explicit leaf allocations and an operational interaction.
  2. sa-*.arcadia: system/actor, function decomposition, typed function and component ports, a data field, functional/boundary exchanges, and explicit work/port/exchange allocations.
  3. scenario-*.arcadia: an operational conversation with an initial Call, correlated reverse Reply, and repeated asynchronous report with a precondition.

src/lib.rs uses the existing tolerant lexer, parses the small B surface, lowers to ordinary source3 declarations and calls the real source-bundle compiler and whole-model validator. It supports includes only through an explicitly supplied SourceBundle. No filesystem, network, alias namespace or semantic model implementation is added to the compiler. src/main.rs provides a single-file CLI inspection harness.

B supports:

sa_function transmit "Transmit report" id "00000000-0000-4000-8000-000000000204" {
    output report_out "Report output" id "00000000-0000-4000-8000-000000000208" items [@report_data];
}
functional_exchange report_flow "Report flow" id "00000000-0000-4000-8000-000000000214"
    from @report_out to @report_in items [@report_data];

The function owner of each explicit endpoint port supplies the redundant FE owner field. It creates no ports or allocations. Ordinary sa_port bodies remain available for fields beyond shorthand. All other existing explicit fields pass through to source3, including variant constructors, component contracts, diagram/node records and exact strings. A nested element supplies only its parent; an incompatible explicit parent is an error. steps { occurrence declarations }; supplies both ownership and the ordered list. Existing steps [@alias] remains accepted. The prototype requires explicit identity clauses everywhere; optional-ID stabilization is intentionally outside this experiment.

Observed results

Ten integration tests passed on Windows/Rust 1.98.1, plus strict all-target Clippy. The real CLI compiled sa-b.arcadia and printed the expected canonical source3 model.

Task Physical lines A/B Significant tokens A/B Explicit references A/B Parent fields A/B Explicit steps references A/B Chosen owner/member line span A/B
OA 12/13 111/103 9/7 2/0 0/0 2/2
SA 21/27 305/245 27/18 7/0 0/0 4/1
Scenario 28/29 290/262 29/21 5/0 3/0 11/11

Counts come from the real lexer excluding whitespace/comments; references count @ tokens. Line spans select the OA parent/assessment child, SA transmitting function/output port and scenario/last occurrence. They measure only those concrete fixture locations, not screen navigation or user time. Each fixture fits one file, so baseline cross-file navigation is equal. B did not shorten the scenario span or any file's line count.

The tests establish:

  • Every A/B pair produces an identical complete Project; canonical export parses back equally.
  • Display-name edits change exactly one authored line in each candidate and preserve every identity and unrelated property. An alias rename likewise preserves model reference identities.
  • Moving an entire aggregate into an included file, relocating it again, and separately moving the shorthand FE to another included file leave the complete model unchanged.
  • Reordering the repeated message changes only the ordered list; occurrence and call/reply identities remain stable. A edits a list; B moves its existing declaration block. Neither requires new identities.
  • Adding another report requires two authored locations in A (declaration plus membership list), one insertion in B's steps block. The resulting complete models are equal and existing identities survive.
  • Contradictory parents/endpoints, duplicate identity, duplicate steps fields, unknown/reversed ports and inappropriate nested owners fail. Removing work allocations while retaining dependent port/exchange allocations is rejected; the shorthand never repairs them invisibly. Removing all three allocation categories leaves exactly the explicitly unallocated model.
  • Explicit-field escape preserves a diagram, node geometry including negative-zero bits, and quoted Unicode text.

Two substantive initial test expectations were falsified. Removing work allocation while retaining dependent port allocation is invalid, so the test now checks that rejection and separately removes all dependent allocation relations. An occurrence omitted from its owner's steps is valid incomplete work with unordered_occurrence warning, not a structural error. The experiment records this existing semantic choice; it does not weaken or silently strengthen core validation. B's ordered block prevents that particular omission. Transient harness compile/CLI path mistakes were corrected and all final commands rerun.

Conclusion and next gate

B has real, limited benefits: fewer redundant references, substantially less port constructor/endpoint boilerplate, and elimination of two-site scenario membership editing. It uses more lines and does not improve every locality measure. These results justify evolving the small B surface on top of A's pure bundle foundation; they do not justify replacing the language with a broad SysML-like grammar or declaring usability solved.

Before production adoption, test source-preserving graphical writeback against these same fixtures. Rename a nested owner, alter a port contract, reorder/add an occurrence, move a semantic child, and move a diagram node. Unrelated files and comments must survive; syntax must remain nested/concise; changed references must still resolve. The current experiment is one-way lowering: it discards comments in the lowered output, has no editable concrete syntax tree, and does not attempt B regeneration. A whole-declaration canonical replacement is insufficient for that gate. No GUI or HTTP service workflow was exercised here.

Revisit B if preserving its organization requires ambiguous parent inference or broad rewrite rules. Revisit global aliases only when a representative larger model demonstrates frequent naming collisions or unwieldy references. Revisit automatic aggregate partitioning when common tasks span more than three files. Include branches/fragments/state nesting and genuinely large models in the next trial before extending the ordered-block convenience beyond the tested sequence cases.

The language references informing the hypothesis are the OMG SysML 2.0 language specification §7.5, its official vehicle example, and Capella's distinction between functional dependency and control flow. These support examining ownership locality and keeping relation meanings explicit; they do not prove this experimental dialect conforms to either standard.

Reproduce from the repository root

$env:CARGO_TARGET_DIR='D:/CodexBuilds/Capella2-source-authoring-experiment'
cargo test --manifest-path experiments/source-authoring/Cargo.toml --locked -- --nocapture
cargo clippy --manifest-path experiments/source-authoring/Cargo.toml --locked --all-targets -- -D warnings
cargo run --manifest-path experiments/source-authoring/Cargo.toml --locked -- experiments/source-authoring/fixtures/sa-b.arcadia

The target-directory override is optional; choose another writable directory on other machines. Linux execution and minimum-supported-Rust execution have not been tested for this isolated experiment. Keep this parser isolated; production grammar/diagnostic/editor work needs independent review rather than copying it wholesale.