Merge Allocation drawing, Traceability guidance, and picker Escape candidate

harness/allocation-drawing-20260923.md

@@ -0,0 +1,83 @@
+# Direct Allocation drawing — issue 30
+
+Branch-specific design above `17f1f89fef4a6bf520f4b09a2116548b967d030e`,
+on `codex/allocation-drawing-ytr83r-20260923`.
+[Issue 30](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/30)
+holds live scope and acceptance. This note records the intended interaction and
+verification criteria, not completed tests, native acceptance or integration.
+
+The user reports that Allocation cannot be drawn from the tools menu in
+Containment. Core semantics and the existing relationship form already support
+the relationship there; the direct canvas tool is the missing affordance.
+Adding that tool follows the same source/target workflow as neighboring tools.
+A form shortcut alone would still require a dropdown instead of clicking the
+visible endpoints, leaving the reported drawing task unresolved.
+
+## Interaction and scope
+
+Choose Allocation in the diagram palette, click any visible eligible performer,
+then click compatible unallocated leaf work in the same semantic layer as that
+performer. The performer's layer need not match a mixed traceability view's owner
+layer. OA uses an Entity or Actor and an
+Activity; SA uses a System or Actor and a Function. Highlighting and the current
+source identify the proposed semantic direction: performer to work, independent
+of where their cards are drawn. Escape cancels the unfinished connection.
+The existing Create relationship form remains an alternative for explicit
+relationship entry; no new Activity or Function is created by this tool.
+
+Projection eligibility requires support for both performer and work cards:
+Containment, All relationships, OA ↔ SA traceability and Architecture · allocated
+work offer Allocation; Functional dataflow, Missions & capabilities and dedicated
+State-machine views do not. Containment and All relationships can display the resulting Allocation line
+when its placements and filters permit. Architecture · allocated work represents
+the same responsibility through nesting, not an additional Allocation arrow.
+OA ↔ SA traceability can contain both layers, but Allocation endpoints must
+still belong to the same layer as each other. Selecting an opposite-layer source
+retains the captured mixed diagram and prior application perspective; cancellation
+also preserves that perspective. After successful creation, the ordinary model
+synchronization sets the application perspective to the captured diagram's owner
+layer while keeping that diagram open. A projection that omits one endpoint category
+must not offer an unusable drawing workflow. Existing filters remain unchanged;
+successful creation does not promise that a filtered line is visible.
+
+## Preservation rules
+
+- Allocate only eligible leaf work with no existing direct performer. Reject
+  duplicate, occupied, composite, cross-layer and Port endpoints; do not treat
+  drawing a new relation as permission to reassign existing work.
+- Core validation is authoritative at completion, in addition to candidate
+  highlighting. Candidates must be actual projected endpoints, not hidden
+  children or computed parent summaries.
+- Create one Allocation in one document transaction. Preserve semantic parents,
+  elements, other relationships, traces and every saved placement, route and
+  view option. Derived projection geometry may change because responsibility
+  changed; that is distinct from rewriting stored layout.
+- Arming, choosing only a source, refusal and cancellation do not alter model
+  history. Stale document/revision/diagram, navigation and pending property or
+  source edits must prevent delayed completion without discarding those drafts.
+- Moving cards in Containment remains ordinary arrangement. Assignment-changing
+  drag and Arrange next drag retain their existing allocated-work-view scope.
+
+No general relationship browser, new reassignment policy, port generation or
+change to ownership semantics is introduced. The existing connection lifecycle
+and ordinary validated command boundary are preferred over a parallel gesture
+framework. Broader form-only relationship kinds are outside this bounded fix.
+
+## Acceptance criteria
+
+Exercise real connection events for valid OA and SA endpoint pairs, rejected
+endpoint classes, cancel/retry, hidden endpoints, stale captures and pending
+drafts. Compare the complete Project so the only semantic difference is the new
+Allocation; bind its fresh identity explicitly. Check exact source Undo/Redo
+and unchanged stored reference-view records. Verify projection eligibility for
+the new tool without regressing the existing four connection tools.
+
+In the actual application, find Allocation in Containment's palette, choose a
+performer and existing leaf work directly, inspect the resulting relation,
+Undo/Redo, Save, close normally and reopen. Confirm feedback explains nesting
+when using the allocated-work projection, rather than promising a new line.
+Inspect nested-card hit selection and filtered-result feedback. Native evidence
+must distinguish observed interactions from automated coverage and bind source,
+binary, process and predeclared full-Project expectations. No successful result
+is asserted here. Linux remains user-paused; combined release acceptance belongs
+to the integration owner.

harness/picker-escape-20260923.md

@@ -0,0 +1,74 @@
+# Picker Escape ownership — issue 35
+
+Branch-specific design above `301126f6098286bf440c1bd1b1ed685753984723`.
+[Issue 35](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/35)
+owns live scope, progress and acceptance. This document records the selected
+contract; it does not assert completed implementation, execution or integration.
+
+## Required interaction
+
+An open picker owns Escape: close its popup, request redraw and consume the key.
+Publish its optional close notification at most once; do not select an option
+or change the surrounding draft, model, source, history, selection or camera.
+A later Escape follows the existing surrounding workflow's policy. Reopening,
+selection and outside-click dismissal retain their existing behavior. Selection
+does not gain a new close callback as an incidental change to this repair.
+
+Event batches matter. A popup already closed by Escape must not select a stale
+option or emit another close notification when later queued events reach the
+same overlay object. This does not introduce a new global keyboard-repeat policy.
+
+## Decision and evidence
+
+The shared picker and its menu overlay currently omit Escape handling. Adding
+widget capture alone is insufficient: application subscriptions translate some
+captured Escape events back into modal cancellation. Those bridges also preserve
+legitimate cancellation from focused text inputs, so simply removing them loses
+existing behavior.
+
+The selected design gives dismissal to the picker overlay and moves the existing
+captured-key forwarding into a scoped wrapper around the ordinary application
+widget tree. Keep the wrapper structurally present even when inactive, preserve
+the existing activation predicates and message priorities, and delegate widget
+state, operations, layout and overlays transparently.
+
+The locked Iced 0.14 runtime processes overlays first and skips ordinary root
+updates for events captured by an overlay (`user_interface.rs`). Nested overlays
+likewise give their deepest child first refusal (`overlay/nested.rs`). Thus the
+Escape from an already mounted picker cannot reach ordinary-tree forwarding,
+while focused text-input cancellation can retain its previous policy. The runtime
+can reuse an overlay across an event batch; close-state checks must cover that
+case. Conversely, opening a picker and pressing Escape in the same batch can
+reach the ordinary tree before the runtime constructs its overlay. The wrapper
+therefore offers the currently available nested overlay first refusal for Escape
+before forwarding to ordinary children; the picker also handles base delivery.
+An overlay that already ignored Escape may receive this narrow preflight again.
+Audited reachable passive overlays perform no selection or draft action; the
+source-navigation observer can advance its conservative focus-freshness epoch
+again. Regression checks must retain stale-focus rejection and observable state.
+Do not generalize this replay to other keyboard or pointer events.
+
+Alternatives rejected: a widget-only patch leaves outer-draft cancellation;
+global open-picker bookkeeping duplicates widget state and requires coordinating
+every open/select/close/removal path; per-text-input forwarding can work but
+spreads the existing policy across many controls. Revisit the wrapper choice if
+runtime delivery changes or actual mounted tests contradict these assumptions.
+
+## Acceptance
+
+Use mounted runtime delivery for open/dismiss/reopen/select, optional callbacks,
+outside click and same-batch Escape/click sequences. Exercise the real application
+subscriptions with returned event status, including focused text cancellation,
+architecture editing, behavior drafts and Text workflows. Compare complete model
+and source state where dismissal must conserve them; direct helper calls alone
+do not establish event ownership.
+
+Native coverage should include the State hidden-element picker and the Add
+existing chooser's filter dropdown with a retained query: first Escape dismisses
+the picker, then a distinct Escape follows the chooser policy. Behavior creation,
+behavior source forms and Text Find/rename currently have no internal dropdown;
+picker coexistence there is composed mounted coverage, not a claim of a native
+control that does not exist. Verify their ordinary focused-text Escape behavior.
+
+Linux remains user-paused. Shared integration and release acceptance remain with
+the integration owner; this branch does not establish combined-release behavior.

harness/traceability-view-20260923.md

@@ -0,0 +1,73 @@
+# Traceability view comprehension — issue 31
+
+Branch-specific work above `b8685416f56e53e30bd11ecf93a54cea10ac8458`.
+[Issue31](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/31)
+owns live progress. This note records the chosen design and acceptance plan,
+not completed validation or integration.
+
+The user's observed problem is that OA↔SA traceability looks like All
+relationships and its purpose is unclear. Existing core behavior already
+projects both layers' placed elements, ordinary relationships and explicit
+traces with available endpoints. Switching projection neither creates semantic
+counterparts nor adds missing placements. Existing Add existing supports both
+layers, but its default suggested-type filter conceals opposite-layer choices.
+Show in this diagram also has inconsistent cross-layer eligibility and selects
+an opposite-layer element before placement, potentially changing the target view.
+
+## Decision and criteria
+
+Make the existing workflow understandable and reachable before introducing a
+second counterpart browser. Criteria: a new user can explain the distinction,
+find both named ends, place existing counterparts in the chosen saved diagram,
+see/inspect correspondence, understand absent lines, and preserve semantic data.
+Keep the established mixed ordinary/trace contract, explicit semantic creation,
+saved view filters and single-operation placement history.
+
+Use concise projection-local explanation, the actual count of projected trace
+edges, Add existing elements, Review layer traces, and existing View visibility.
+Default the Existing chooser to All compatible types only for Traceability;
+creation and ordinary-view defaults stay scoped to their existing contexts.
+Align Show in this diagram with actual supported placement and retain the
+captured diagram across cross-layer selection. Review layer traces opens a
+predictable layer-trace inventory without a stale artifact filter/search, through
+existing navigation/draft guards. It does not promise that subsequently choosing
+an opposite-layer endpoint preserves the originating diagram.
+
+The count is exactly `project_view(...).edges.filter(trace).count()`, after saved
+filters. It is neither a project-wide trace total nor a coverage denominator.
+No overlapping missing/hidden reasons are added into invented totals. Port
+correspondences use owner-card placements; relation-to-relation correspondences
+remain reviewable semantic records and are not promised a diagram line.
+
+An expandable view-local counterpart browser with named Place/Locate actions
+was independently proposed. It can reduce name memorization, but introduces
+another scope, owner-mapping, omission-reason and targeted-placement interface.
+The existing chooser already completes the bounded placement task once its
+default and shortcut are corrected. Revisit the richer browser if the actual
+native task remains confusing. Tooltip-only, traces-only replacement, automatic
+counterpart creation/placement and forced OA/SA layout were rejected: respectively
+weak task completion, broken mixed-context contract, surprising semantics/history,
+and unwanted authored-layout changes.
+
+## Verification plan
+
+Exercise the real Existing chooser and actual Show menu path for opposite-layer
+elements, including stale/pending refusal and ordinary-view restrictions. Only
+the current diagram's intended placement may change; preserve semantic maps,
+other views, route/visibility choices, exact source Undo/Redo and save/reopen.
+Ports cannot become node placements. An already placed element must not acquire
+a duplicate placement. Predictable trace review must preserve drafts and obey
+the usual modal/navigation guards.
+
+Use core projection/filter evidence for no trace, missing endpoints, both placed,
+ordinary OA/SA edges, multiple traces, explicit hides plus disabled Trace kind,
+port owners and relation correspondence. Do not infer visible lines from
+unfiltered edge_availability or confuse unrelated model traces with counterparts.
+
+Native acceptance starts with an OA-owned mixed view, one already visible
+correspondence pair and another existing named SA counterpart not yet placed.
+Find/place it through the visible controls, see/select the additional trace,
+inspect an absent-line visibility reason, Undo/Redo and Save/reopen. Inspect
+toolbar/canvas space and chooser clarity at a realistic window size. Different
+help text or count tests alone do not resolve the user's comprehension complaint.
+Linux remains user-paused; Codex-956atf retains shared integration ownership.