228 lines
14 KiB
Markdown
228 lines
14 KiB
Markdown
# Semantic desktop review — scalars and closed constructor groups
|
||
|
||
Status: milestones 1–2 and the closed constructor group forms are implemented.
|
||
Independent keyed/ordered review, historical pairing reset, multi-source review,
|
||
full GUI parity, native acceptance and release acceptance remain outstanding.
|
||
Base: `d130013`. Dedicated build target:
|
||
`D:/CodexBuilds/Capella2-semantic-desktop-target`. Native verification is root-owned.
|
||
|
||
## Scope and decisions
|
||
|
||
- Add an explicit Review semantics action for existing traced counterparts, with
|
||
canonical Operational/System comparisons in either application direction.
|
||
Preserve the existing counterpart creation and prose workflow with clear labels.
|
||
- Review one explicitly selected trace per dialog. Display grouped current and
|
||
historical facts, own/linked drift and incomplete review. Names never infer
|
||
reference correspondence; provide explicit reference and trace choices.
|
||
- Support every applicable scalar leaf through Keep, Take and typed final-value
|
||
forms. Candidate records contain the complete combined selected result. Identity,
|
||
alias and layer are protected. The closed core remains the validation boundary.
|
||
- State.Kind is a single structural scalar. Data, Port, Occurrence, nested
|
||
MessageKind and Event support their closed constructor groups and complete
|
||
typed payloads. Independent keyed membership/order/annotation/binding/attachment
|
||
decisions and pairing resets remain visibly read-only outside a replacing group.
|
||
- Core `6bb2583` permits first equal constructor acknowledgment without descendant
|
||
expansion. The GUI exposes **Acknowledge equal kind only** when applicable;
|
||
previously reviewed constructors remain governed by the core's switch rules.
|
||
- Show exact additional prepared impacts and require explicit acceptance. Apply
|
||
validates the stored semantic plan and executes its exact command batch through
|
||
Document, preserving source, baselines and one-step undo/redo. Do not place or
|
||
reveal diagram objects by mutating the model after preview.
|
||
- Retain typed drafts and review choices on invalid input, planning conflicts,
|
||
stale plans and failed source writeback. Display actionable errors in the dialog.
|
||
|
||
## Milestones and acceptance
|
||
|
||
1. Grouped read-only review, named trace/reference choices, exact comparisons and
|
||
honest traceability rollups; compact layout usable at 1100 by 700.
|
||
2. Scalar decisions and typed candidates; immutable initial observations; combined
|
||
final records; exact impact acceptance; atomic document/source commit. Focused
|
||
App event/source/history tests, strict Clippy and a dedicated desktop build.
|
||
3. All closed constructor forms are implemented, including nested MessageKind.
|
||
Independent keyed and ordered facts, reset, complete artifact lifecycle,
|
||
multi-source review and remaining source/REST parity cases are outstanding.
|
||
4. Root-owned native review, cross-surface fixtures, package/release acceptance.
|
||
|
||
## Verification
|
||
|
||
Scalar fixes were verified on SEM `6ad3cb`; the nested message-kind slice builds
|
||
on scalar commit `5a51a75`. Verification uses only the dedicated desktop target
|
||
(core behavior remains based on `6bb2583`):
|
||
|
||
```powershell
|
||
$env:CARGO_TARGET_DIR='D:/CodexBuilds/Capella2-semantic-desktop-target'
|
||
cargo test --locked -p oa-desktop --quiet
|
||
cargo clippy --locked -p oa-desktop --all-targets -- -D warnings
|
||
cargo build --locked -p oa-desktop
|
||
```
|
||
|
||
All **285 desktop tests passed**, including **11 original semantic review tests**,
|
||
**5 scalar review regression tests**, and **8 nested message-kind tests**.
|
||
Strict Clippy and the desktop build passed. The existing migration test's header
|
||
assertion now follows `SCHEMA_VERSION` instead of expecting schema 4.
|
||
|
||
Coverage includes both-direction Keep/Take/Candidate with exact comments and
|
||
source/model/baseline undo/redo; independent selected trace semantic histories;
|
||
invalid numeric and protected-property edits; stale-plan and source-writeback
|
||
rejection; typed reference mapping mixed with candidates; honest partial rollups;
|
||
equal-kind acknowledgment without implicit descendants; State.Kind candidates;
|
||
relationship role/bound candidates with retained identity/endpoints; and exact
|
||
inherited-annotation cleanup approval, cleared when decisions change. Unselected
|
||
invalid scalar drafts remain retained without contaminating another candidate.
|
||
|
||
The independent scalar review found three gaps, now corrected:
|
||
|
||
- Structural scalar edits replace only their authorized subtree. Clearing an
|
||
invalid selected bound, changing a variant, and adding/removing/reordering a
|
||
literal retain untouched raw inputs and editor buffers, including invalid
|
||
inputs belonging to another decision.
|
||
- Dependent default, reference and port controls read a noncommitting context
|
||
composed by the same scalar Keep/Take/Candidate assembler as the request. Raw
|
||
candidates remain separate. Incomplete inputs use their stored shape only for
|
||
those controls; request creation and Apply still reject invalid selected input.
|
||
The Boolean-source/Integer-target default reproduction now offers Boolean
|
||
literals in both directions. Tests also cover Candidate type, Keep reversion,
|
||
storage-dependent default controls and mechanism-dependent reference choices.
|
||
- Keyed fact headings display live names with stable aliases or deleted UUIDs.
|
||
Message annotation headings include the complete qualified path and field.
|
||
|
||
The regression tests exercise App events, the actual default-form helpers and
|
||
button availability, exact source retention before Apply, and one-step undo.
|
||
|
||
## Bounded constructor slice
|
||
|
||
Occurrence.MessageKind is a complete closed nested family: Asynchronous, Call,
|
||
Reply, Create, Delete and Timer. It is available only when both traced counterparts
|
||
are Exchange occurrences. The only constructor-specific payload is the timer
|
||
expression. This first slice left outer occurrence replacement read-only; the later closed
|
||
constructor slice below now covers it.
|
||
|
||
- Keep/Take/Candidate use the core's switch and first-equal acknowledgment policy.
|
||
Taking a replacing group copies the typed MessageKind, including its expression.
|
||
Taking an initial equal discriminator does not copy an unselected timer value.
|
||
- Candidate MessageKind has its own scoped draft. The independent TimerExpression
|
||
scalar draft survives group decisions; the group timer's exact raw text, editor
|
||
cursor and selection survive switching away from Timer and back.
|
||
- An overlapping kind/timer draft retains both decisions and blocks Apply until
|
||
explicitly resolved. The dialog offers **Replace timer decision with message-kind
|
||
group** and **Leave message kind unselected; use timer decision**. First equal-kind
|
||
acknowledgment can coexist with an independent timer decision. Divergent authored
|
||
candidate values reject; neither candidate silently overwrites the other.
|
||
- The kind detail includes baseline/current timer observations and the complete
|
||
proposed kind. It displays the exact plan-provided acknowledged/retired lists.
|
||
Exchange, reply-to, lifelines, annotations and pre/postconditions stay separately
|
||
scoped. Incompatible Timer contracts remain core errors; no dependency or payload
|
||
is silently removed. Existing additional-impact approval remains in force.
|
||
- Group changes compose with scalar choices and execute the exact prepared Document
|
||
batch. Tests cover both directions, all six kinds, mapped reply correlation,
|
||
historical retirement, repeated no-switch rejection, invalid combinations,
|
||
protected scopes, stale preview, source failure, comments and one-step undo/redo.
|
||
- The Traceability contextual toolbar now wraps at the available width so +Artifact
|
||
remains reachable in the compact layout. This is a single `row.wrap()` change in
|
||
`views.rs`; other toolbars are outside this slice.
|
||
|
||
Root reported native scalar coverage on frozen integrated `e7fa061`: mixed numeric
|
||
Keep/Take/Candidate, invalid default retention/repair, zero additional changes,
|
||
atomic Apply, comment/value inspection, Undo/Redo and Save All at 1440×900 and
|
||
1100×700. Reverse/type/reference/history/reopen native checks were still continuing
|
||
when this slice was implemented. This task launched no native application.
|
||
|
||
Built executable:
|
||
`D:/CodexBuilds/Capella2-semantic-desktop-target/debug/arcadia-studio.exe`.
|
||
The build target is idle. No native application was launched by this task.
|
||
|
||
## Remaining work
|
||
|
||
Milestone 3 must add independent keyed and ordered decisions, historical pairing
|
||
reset, complete artifact lifecycle and multi-source review. These facts are currently inspectable, with unsupported writes visibly
|
||
identified. The reference table supplies explicit mappings for scalar reference
|
||
Take; it does not claim to complete a reset or establish keyed acknowledgments.
|
||
|
||
Fresh independent requirements/correctness review and root-owned native checks of
|
||
the message-kind slice are required before release acceptance. Verify the compact
|
||
kind picker, timer text/focus retention, overlap choices, exact closure/retirement,
|
||
mapped Reply, blocked Timer contract, source reopening and toolbar wrapping.
|
||
|
||
|
||
## Remaining closed constructor families (this slice)
|
||
|
||
Owned files: `semantic_review/**`, `semantic_review.rs`, the scoped Draft adapter
|
||
in `forms.rs`, semantic-only port choices in `forms/port_fields.rs`, and this ledger.
|
||
No shared traceability header, core, API, native state or source language edits.
|
||
Base: `f73551f`; same exclusive desktop target.
|
||
|
||
| Constructor | Complete group payload | Independent fields |
|
||
| --- | --- | --- |
|
||
| Data | Definition, bounds, literal members, record supertype, default | Unit, owner and headers |
|
||
| Port | Contract, function item members, retained legacy direction/interface | Owner and headers |
|
||
| Occurrence | Body, nested message kind/timer, references, qualified annotations, bindings, branch and step order | Pre/postconditions, owner and headers |
|
||
| Event | Body, signal item members, time kind/expression or change expression | Owner and headers |
|
||
| MessageKind | Complete nested kind and timer expression | Other occurrence body properties |
|
||
|
||
Each group owns an independent draft, including the nested MessageKind group.
|
||
Keep/Take/leave-unselected retain all drafts. Constructor picker changes save the
|
||
old branch value plus its raw inputs and editor state. Switching back restores them.
|
||
Port input/output changes also carry authored item reference strings, including
|
||
invalid strings, rather than falling back to stored UUIDs. A Data definition switch
|
||
leaves its existing default visible until the user deliberately changes or clears
|
||
it; Port's retained generic association has explicit add/edit/clear controls.
|
||
|
||
The same combined candidate projection supplies dependent form context. Only the
|
||
selected roots are materialized; unrelated invalid scalar/group drafts stay local.
|
||
Full Take payloads use the public core typed reference visitor, so UUID-shaped prose
|
||
is never remapped. For historical same-kind Take, the closed adapter retains only
|
||
current target-present/source-absent rows without a previous source-present
|
||
observation on that target slot; the core independently
|
||
checks the supplied final record. No GUI acknowledgment, retirement or impact list
|
||
is synthesized. The core remains authoritative for those lists and applicability.
|
||
|
||
Group details show every baseline/current/proposed group observation, including
|
||
qualified and historical row identities. Actual preview acknowledged/retired lists
|
||
remain explicit. A replacing group and selected descendants retain both decisions
|
||
and provide explicit leave-unselected actions. First-equal discriminator observation
|
||
can coexist with independent descendant decisions. Conflicting authored values
|
||
reject instead of silently discarding either draft's edits.
|
||
|
||
Array controls support the whole authorized payload, including order, existing
|
||
owned branches/steps, signal items, annotations and scenario bindings. They do not
|
||
create referenced semantic objects, change their ownership, delete dependencies,
|
||
or infer reference correspondences. Incompatible payload/owner combinations stay
|
||
visible as validation failures. Apply still sends exactly one prepared Document
|
||
batch, preserving comments, source/model/history agreement and one-step undo/redo.
|
||
|
||
New coverage exercises all six Data definitions and companion defaults in both
|
||
directions; all eight Occurrence and all three Event kinds; all four Port forms;
|
||
combined owner context; nested and scalar draft retention; explicit overlap;
|
||
protected fields; mapped record, state, event item and scenario binding payloads;
|
||
complete owned branch/step order; historical retirement and first-equal scope;
|
||
90 Data/Event kind-pair and direction comparisons against the core-only preview;
|
||
source comments/reopen and atomic undo/redo. Full checks and core dependency status
|
||
will be recorded at freeze. This task launches no native application.
|
||
|
||
The delegated keyed-closure fix `43370de` is integrated into SEM as `9c3184b`.
|
||
Reverse Literal/Member/Binding/Annotation closure and historical local-member
|
||
preservation now pass the desktop desired-success tests. The separately delegated existing-target Port fix `8a75294` is integrated into
|
||
SEM as `7512ac8`. Fresh reverse Keep and Candidate reviews can preserve/edit the
|
||
OA Legacy association; taking a typed contract into OA still rejects. Both fixes
|
||
are covered by desired-success desktop tests; no GUI workaround weakens validation.
|
||
|
||
Native acceptance remains root-owned: use the existing trace Review semantics
|
||
entry, inspect complete group before/after and retired identities, switch variants
|
||
away/back, resolve explicit nested overlaps, repair invalid defaults/references,
|
||
apply once, inspect source, undo/redo, save and reopen at 1100×700 and 1440×900.
|
||
|
||
|
||
## Closed constructor freeze verification
|
||
|
||
On integrated SEM base `7512ac8`, all **299 desktop tests pass**. This adds 13
|
||
constructor workflow tests and one scoped port form regression to the previous
|
||
285-test slice. The new suite includes 90 complete Data/Event kind-pair/direction
|
||
comparisons against core previews, all closed candidate kinds, mapped qualified
|
||
annotation addresses, bindings and references, actual reverse Legacy edits, owned
|
||
branch/step ordering, source/model/history agreement, retained drafts and strict
|
||
scope protection. Both delegated core defects are resolved and exercised.
|
||
|
||
Owned-file rustfmt check, strict Clippy (`--all-targets -- -D warnings`) and the
|
||
desktop build all pass using the dedicated target and commands above. Native checks remain root-owned. No native application
|
||
was launched, and full milestone 3 / GUI parity / release acceptance remain open.
|