ARCADIA-Studio/harness/release-requirements-delta-20260910.md

# Updated requirements: semantic and workflow delta

Codex-956atf `/root/requirements_delta`, 2026-09-10. Independent, bounded audit for the root integrator. Read the new authoritative attachment in full, repository `PROJECT_GOAL.md`, Gitea issue #1 through comment #73, the open PR list (empty), and Wiki Home/release-readiness material. Ownership was announced in issue #1 comment #74. Other-host scenario layout, platform and packaging work remains outside this audit.

The attachment and synchronized `PROJECT_GOAL.md` have identical SHA256 `7C1BDBD077E31439501C04DC3613E6BE47A389704DDC3A44EF8BD9AD98EBB513`. Source inspection began at `eb5161b`; root advanced to `4ecad78433bdfcf20792f073924c80d8ba37c251` during the audit. That advance does not introduce the absent metamodel capabilities identified here. No production files, Cargo invocation, native application or runtime test were part of this audit. Existing test source is evidence of its assertions, not a new passing result.

## Disposition

The updated objective makes **calculations, quantities/units, reusable model libraries, and scalable selection workflows explicit release requirements**. Three material semantic gaps remain: the current model preserves expression and unit annotations without evaluating them, and modular source/reusable sequences do not provide a maintained cross-project library mechanism. The current specification accurately documents those limits; documenting a limit does not satisfy the newly explicit requirement.

The graphical/textual model, state/behavior semantics and REST service already have substantial implementations. This audit does not revive pre-source7 absence claims. Their remaining runtime acceptance is owned by the current release work. Strong specification/API foundations also exist; the question is extending their precise contracts and establishing conformance, not starting another metamodel.

## Requirement-to-evidence map

| Explicit requirement | Implemented capability and concrete evidence | Remaining delta / evidence limit |
| --- | --- | --- |
| Textual and graphical notation, equivalent editing | `docs/language.rst:9–43` defines one model and graphical conformance obligations. Source7 provides typed records, stable identities, nested declarations, modular source, validation, exact source/history updates. `forms.rs`, specialized behavior editors and the diagram authoring work adapt the same typed core. | Every new semantic feature below must enter both representations and the existing history/recovery boundary. Current behavior redesign has pending execution/native acceptance; this audit supplies none. |
| Constraints | `model.rs:651` stores `Constraint { expression: String, constrained: Vec<Id> }`. `validation.rs:560–586` checks text, reference membership/layer and empty-expression completeness. Forms treat `expression` as multiline text and `constrained` as references (`forms.rs:819–910,1034`). OpenAPI exposes the same closed string/reference structure (`docs/openapi.json:3089`). | Structural constraints are checked, but authored constraint expressions are not parsed or evaluated. There is no result expressing whether an authored predicate is satisfied. This is expressly stated in `docs/language.rst:202–205`. |
| Calculations | Numeric type bounds and typed defaults are validated; `DataValue` contains Boolean, i64 Integer, f64 Real, String and Enumeration (`model.rs:298`). `MessageValue.expression` is also a string (`model.rs:520`). | No calculation definition/application, typed expression tree, input binding, dependency evaluation or result model is present in the core module/kind/project catalogs. Arithmetic-looking message text is not computation: `guide.rs:606`, `language.rst:933`, and the HTTP data-contract tests preserve it as text. |
| Quantities and units | DataType/DataField carry `unit: String` (`model.rs:603–617`). `data.rs:608` inherits a named type's unit when field text is empty. `data.rs:1013–1038` warns for nonnumeric units and differing field/type strings. `r6_data.rs:209–281` contains an exact unit-inheritance/default/bounds assertion. Forms expose free unit text (`forms.rs:910`); REST/source round-trip it. | No quantity-kind identity, unit definition, dimension algebra, unit-bearing value or conversion. `language.rst:929–933` explicitly disclaims dimensional compatibility. A string equality warning cannot distinguish an equivalent scaled unit from an incompatible physical quantity. Existing scalar default checks do not close this gap. |
| State and behavior modeling | Current `OccurrenceBody`, state/event/transition models, reuse and source7 caller-qualified links/operation identity are implemented. `language.rst:517–876` describes these semantics; process/scenario authoring and lifecycle projection work is active. | Retain the current behavior/native gates. Lack of a simulator is not evidence that state/behavior *modeling* is absent; calculations need not turn these diagrams into executable simulations. |
| Reusable model libraries | Named data types, record/item/interface specialization, SequenceReference, ScenarioUse/bindings and modular source provide real reuse within a project. `language.rst:731`, `929–957`, `1646–1725`; `source_project.rs:17,286`. | Included files share **one global alias/UUID namespace** and add no namespace or library identity (`language.rst:1690`). The pure compiler admits an explicit local bundle and resolves no external project. `Project` has elements/relations/diagrams/artifact-links/traces only (`model.rs:1621`). No library package/version/dependency declaration, imported definition provenance, instance identity mapping or library upgrade/reconciliation workflow exists. Copying a directory or opening an example does not establish these semantics. |
| Strong standardized specification | Normative reST exists, with closed syntax, semantics, invariants, migration and graphical editing obligations. `docs/language.rst` explicitly separates its contract from native acceptance and external Arcadia/Capella/SysML conformance. | Extend the single specification with new evaluation/library semantics and valid/invalid examples before downstream implementation. Publish a release-scoped conformance matrix. Some supporting documents are stale: `docs/acceptance.md:8` still inventories 27 kinds while `model.rs:69` inventories 39. Do not use those old acceptance claims as current coverage. |
| Strong standardized API | `docs/api.rst:4–43` and `routes.rs:29–85` define versioned REST, a shared Project/Command/parser/validation boundary, ETags and rejected-write semantics. OpenAPI 3.1 is published. Root records schema validation separately. | No analysis/evaluation or library workflow can currently be exposed because the core lacks it. OpenAPI conformance is distinct from conforming to the OMG Systems Modeling API. The user's wording does not alone establish that a full OMG adapter is required; record the interpretation explicitly instead of calling a proprietary API OMG-standardized. |
| Avoid long homogeneous UI lists | Explorer has kind groups, containment, breadcrumbs, search and a 100-item paged catalog (`explorer_view.rs:17–149,249–388`). Existing contextual authoring narrows many choices. | A concrete remaining risk is `forms.rs:1034`: Constraint targets include every same-layer semantic identity; `:920–964` sorts the complete list; `:1952` renders an ordinary `pick_list` without a search/grouping control. Generic arrays (`:2020–2067`) render every full editor row. Compatibility filtering helps correctness but does not bound human search effort. Native dense-model evaluation remains required; this is a verified design path, not a measured task-time claim. |

Paths without a prefix in the table refer to `crates/oa-core/src` for model/data/validation/source_project, `crates/oa-desktop/src` for forms/guide/explorer_view, `crates/oa-server/src` for routes, and `crates/oa-core/tests` for r6_data.

## Domain observations, separate from the proposed design

Capella's official feature description defines reusable collections and replicas that can be packaged in libraries and shared by projects. It also identifies mass, cost and latency viewpoints. This supports a requirement for maintained reuse and engineering analysis; it does not imply that ordinary includes or presentation copying provide those functions. [Capella features](https://mbse-capella.org/features.html)

The official Arcadia/Capella comparison describes constraints, opaque/parseable expressions, properties and physical dimensions, with analysis often supplied through viewpoints. It does not require Studio to clone a dedicated parametric diagram or to become a behavioral simulator. The user has nevertheless explicitly required calculations, so Capella's extension architecture cannot justify implementing only prose. [Capella's parametric comparison](https://mbse-capella.org/arcadia_capella_sysml_tool.html#parametric)

SysML 2.0 distinguishes reusable calculations with results (§7.19), Boolean-valued constraints (§7.20), and quantity kinds/units with conversion (§7.8 and §9.8). These are useful reference distinctions, not a claim that Studio implements KerML or SysML. The proposed subset below is Studio's own design. [OMG SysML 2.0 language specification](https://www.omg.org/spec/SysML/2.0/Language/PDF)

The OMG Systems Modeling API publishes a separate normative specification, OpenAPI document and schemas. Merely using JSON, REST or an OpenAPI document does not implement that domain standard. [OMG Systems Modeling API 1.0](https://www.omg.org/spec/SystemsModelingAPI/1.0)

## Alternatives and a recommended minimum coherent design

These are candidates for root synthesis and independent semantic criticism, **not ratified scope changes or implemented capability**. A completed small engineering workflow is the useful first milestone; adding new text boxes is not.

| Candidate | Benefit | Principal cost or shortfall | Assessment |
| --- | --- | --- | --- |
| Keep expression/unit metadata; distribute source snippets | Very small change and preserves all current behavior. | Cannot compute a budget, reject a dimensionally invalid expression, or identify/update an imported library instance. | Fails the explicit requirements as a final release interpretation. |
| Add a bounded pure analysis model plus versioned local library packages | Delivers useful OA/SA analysis and cross-project reuse through the current Rust/core/source/API architecture. Evaluation and package resolution remain explicit and reproducible. | Requires foundational value/reference/identity decisions, one schema migration and complete editing adapters. | Recommended first-release direction, subject to the acceptance cases below. |
| Make external analysis tools/plugins the principal implementation | Domain solvers can remain specialized; artifact traceability is useful. | A link or export alone still leaves the required Studio workflow incomplete. Reproducible bindings, invocation, typed results, unit checking and failure handling need substantial contracts. | Useful later integration; acceptable as a primary route only if that full end-to-end workflow is implemented and accepted. |
| Adopt full KerML/SysML evaluation and OMG repository services | Strongest direct standards interoperability. | Broad semantics and repository lifecycle well beyond the current OA/SA model; large migration and UX burden. | Do not infer this commitment from “similar to SysML v2.” Evaluate separately if full conformance becomes an explicit target. |

### Analysis and quantities

The smallest useful core needs an **identified engineering property/value attached to an explicit semantic owner**, a reusable calculation with typed parameters/result, and a constraint with explicit parameter bindings and a Boolean result. A system's measured or assumed property must not be silently represented by an ExchangeItem field's *type default*: those are different domain facts. Root should compare a general owned-property record against a dedicated analysis context before selecting concrete Rust variants. Analysis properties can remain layer-owned; shared quantity/unit definitions need an explicit layer policy rather than accidental exceptions to existing data/reference rules.

Use a closed, versioned expression language with literals, exact reference identities, parameter names, arithmetic, comparisons, Boolean operations and bounded reusable calculation calls. Provide sum over an explicitly modeled finite collection so engineers can express budgets without manually expanding every term. Pin precedence, type inference, coercions, result type and diagnostics in reST. Reference spelling may use stable source aliases, but name matching must not establish identity. Cycles and wrong reference kinds require located diagnostics; an unevaluable dependency must not silently supply zero.

Evaluation should be a pure core operation on a model revision plus explicit inputs, shared by desktop and server. Distinguish a Boolean false result (an unmet engineering constraint) from invalid model structure, missing inputs and evaluation failure. Engineers must be able to save a model with an unsatisfied requirement. Results should identify the evaluated revision, input bindings and dependency path; mere evaluation must not dirty source or create an Undo step. Do not store an implicitly authoritative cached number that survives changed inputs.

Quantities need named quantity-kind and unit identities, dimension information, explicit scale/conversion rules and a unit-bearing value. Quantity-kind identity and dimensional compatibility are related but must not be conflated: equal dimension alone is not universal interchangeability. Preserve the entered magnitude/unit while deriving a comparison representation. Support base and derived scalar units plus user-defined scaled units; built-in definitions should be versioned like other library content. Specify absolute/relative quantities and affine-unit rules before admitting offset units. A unit outside the supported model must produce a precise unsupported/invalid diagnostic, never a pretend conversion.

Numeric behavior is a consequential open choice: compare exact decimal/rational arithmetic for predictable engineering budgets against bounded finite binary64 with explicit tolerance/comparison rules. Existing i64 bounds must not be weakened by converting all integers to binary64. Decide overflow, division by zero, nonfinite results and computation budgets before implementation. General equation solving, differential simulation, vectors/tensors and arbitrary embedded scripts are materially different candidate expansions; they are not implicitly delivered by a scalar calculation feature and must remain explicitly tracked if required by further scope evaluation.

### Libraries

Use an explicit **versioned package with a self-contained, validated source bundle, stable package/export identities and a digest**. Resolve/pin the complete dependency closure outside the pure compiler and retain the pinned bytes for offline reopen and hosted reproducibility. Local packages are sufficient to prove the workflow; a package registry or hidden network fetch is not required.

The first coherent library workflow should support two distinct uses: immutable imported definitions such as data types/units/calculations, and editable instantiation of an exported OA/SA model pattern. Imported definitions retain package provenance; an architectural instance receives fresh local identities with an explicit source-to-instance map. Two uses must not alias one another accidentally. Pattern closure must cover actual owned records, internal relations, sequence order/bindings and relevant traces; external references require explicit binding or a reported unresolved dependency. Do not clone a second System of Interest or bypass existing OA/SA admission rules.

An explicit namespace/export mechanism is needed; current global aliases and source include paths must not be repurposed as if they already provide it. Decide how shared immutable definitions participate in core references and commands, including prevention of accidental edits/deletes, and how layer-neutral vocabulary relates to OA/SA-owned elements. Pinning avoids silent changes, but a useful maintained library also needs an explicit update path: compare previous package revision, proposed revision and current local instance; show local changes/deletions and apply chosen updates atomically. Existing semantic-review concepts are relevant, but the current OA/SA counterpart reviewer is not automatically a cross-project library engine.

A package's content being present in the source bundle does not make it ordinary editable project source. Its provenance and immutable/editable role must survive text, JSON, REST, history and reopen. An explicit detach operation can produce ordinary local content while preserving traceable origin. Graphical presentation copying should be a separately declared choice; it must not be confused with semantic instantiation.

### Specification, API and selection workflows

Keep one versioned Studio language/semantic specification and one OpenAPI contract with explicit conformance obligations and an external standards mapping. Extend the core command boundary for analysis/library changes; do not put separate evaluators or library rules in Iced and HTTP handlers. Analysis responses need revision/input/result identity and structured diagnostics; library mutations need the same ETag and atomic rejection guarantees as current model writes. A read response must not imply an analysis result for a different revision.

For the proven long-list path, design one reusable contextual reference chooser: show the current value, appropriate scope/kind groups and containment context; support name/alias search and keyboard selection; reveal additional results explicitly with counts. Selected and invalid/missing values must remain visible. Search is helpful but cannot be the only organizing principle. A large collection editor should provide a compact overview and focused item editor instead of expanding every item into a full form. Apply this first to Constraint targets and similarly broad semantic/reference fields, preserving specialized caller/operation/port selectors already implemented.

## Acceptance before calling the delta satisfied

These are proposed evaluators. None has been executed in this audit.

| Case | Required observable result |
| --- | --- |
| A1 — Real engineering budget | On an OA activity or SA function, author two duration inputs, e.g. 750 ms and 1 s, calculate total duration and constrain it to at most 2 s. Obtain 1.75 s and satisfied. Change one input to make the constraint fail. Show input identities, units, dependencies and exact evaluated revision. Use a separately computed oracle, not the evaluator's own output as the expected answer. |
| A2 — Unit and numeric falsifiers | Equivalent scaled values compare correctly; adding duration to mass rejects; incompatible quantity kinds with equal dimensions are not silently substituted; division by zero, overflow, missing inputs and dependency cycles are distinguished. i64 boundary values retain precision. Verify whichever affine/relative-unit policy the spec actually admits. |
| A3 — Genuine representation parity | Build the same calculation/property/constraint through GUI, source and REST and compare the full resulting model. Change units/expression/bindings through each path. Verify named references survive rename, and invalid drafts preserve the accepted model/source. Graphical editing exposes the expression and result meaning rather than only an opaque payload. |
| A4 — Exact lifecycle and recovery | Save/reopen and GUI Undo/Redo restore full accepted model plus exact authored source/IDs for analysis and library edits. Crash recovery retains raw invalid expressions and unresolved binding drafts. Compare saved snapshots directly so a semantically similar reconstruction with new UUIDs cannot pass. Evaluation alone leaves revision/source/history unchanged. |
| L1 — Cross-project reuse | Publish one package with a reusable data definition, calculation and OA/SA pattern. Consume it in two fresh projects, instantiate the pattern twice with different bindings in one project, and verify distinct instance IDs and one clear source map. Reopen offline with the same pinned definitions/results. |
| L2 — Maintained library change | Publish an updated package, make a local instance edit, and preview update. Show retained/taken/deleted/conflicting content and affected bindings before one atomic apply. Rejection leaves all state unchanged. The untouched second project stays on its pinned revision; duplicate names, transitive package conflicts, missing dependencies and attempted edits to imported immutable content have explicit outcomes. |
| S1 — Independent contract consumption | A client created from the published schema can create/read/query/edit/evaluate and perform package/instance operations without relying on undocumented Rust layout. ReST/OpenAPI examples, invalid fixtures, schema migration, no-op behavior and stale-ETag rejection agree with the implementation. No unproved OMG or complete Capella-conformance claim is made. |
| U1 — Large-model human task | In the real minimum-size and wide application, select a desired Constraint target among at least 1,000 compatible records with repeated names, and edit one member of a large collection. The user can narrow by context/group, distinguish identity, reach keyboard actions and recover a no-match/invalid current choice without traversing the whole catalog. Establish a task-time/action budget before comparison; record observed results rather than treating widget count or pagination as usability proof. |

## Integration consequences and next actions

Root should record these as open first-release requirements in the durable ledgers now. Current behavior authoring, shared validation, source preservation and release-platform work remain useful and should continue. Their completion does not close A1–L2.

Before a production subsystem, run a bounded semantic design/criticism step on owned engineering properties versus analysis contexts, numeric policy, quantity-kind/unit compatibility, and immutable definitions versus instantiated patterns. The recommendation above makes those choices concrete enough to evaluate; it does not authorize silently substituting metadata or templates for the user's requested capabilities. If a materially stronger interpretation of “standardized” or “libraries” is selected, preserve that scope explicitly.

Any accepted extension needs a deliberate schema/source migration. Existing source7 Constraint expressions, guard/event/message text and arbitrary unit strings must remain authored annotations unless the engineer explicitly converts them to a checked expression or binds a unit identity. Do not infer execution from punctuation or recognize units heuristically during migration. Preserve complete identity/history, source ownership/comments, reference/deletion behavior, OA/SA transitions, semantic-review compatibility, JSON/OpenAPI, graphical drafts and recovery. Exact bundled definition versions must accompany hosted and file-based interchange.

Only after the new workflow passes its semantic, API/source and native acceptance should the specification's current non-execution/non-conversion statements be replaced. Updating those sentences alone would create a false conformance claim.