diff --git a/README.md b/README.md index a6d995e3..d6857ed2 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,8 @@ The example opens in an architecture view with work nested inside its performers **Model explorer** groups roots by engineering purpose and opens one container's direct children. Breadcrumbs navigate ownership; **Allocated work** is listed separately. Search names, kinds or `@aliases` to find elements with ancestor context. Results are paged in groups of 100. **Collapse all** folds the outline; **Locate** clears the filter and reveals the selected element's ancestry. +**Data & interfaces** separates exchange nature from mechanism, supports bounded reusable types and typed defaults, and gives each interface item allocation its own protocol and artifact identity. Operation parameters have provider-side directions; qualified message paths distinguish repeated Record uses. Record/item/interface specialization preserves inherited identities. See the [data contract](docs/language.rst) for exact semantics and compatibility. + The inspector exposes typed properties, references, ordered lists, aliases and UUID identity. Applying or navigating away attempts to commit the draft; invalid values remain editable. **Escaped strings (advanced)** uses quoted JSON escapes for exact tabs, line breaks and carriage returns, for example `"First\nSecond"`. UUID changes atomically update dependent references. Accepted model/source history retains up to 100 edits within an estimated 32 MiB history budget. Choose **Interaction**, **Functional exchange** or **Boundary exchange** in the diagram palette, then click the source and a highlighted compatible target, or drag between them. Functional exchanges use output/input ports; function cards create or reuse real ports atomically. Boundary exchanges use compatible component ports. Middle-button drag pans without losing the chosen source; arrow keys also pan while drawing with the canvas focused. Click empty space to restart, or Escape to cancel. Each completed connection is one model/source history operation; edit its name and carried items in Properties. @@ -70,7 +72,7 @@ In the state view, **Select / move** drags vertices and containers without repar **Textual model** has a source-file folder tree, per-file drafts, syntax highlighting, live linting and explicit **Apply all**. Collapse/Locate navigate the hierarchy; collapsed folders retain draft and diagnostic indicators. Right-click a file for contextual actions. Projects can use relative includes to organize source into files. For example: ```text -arcadia 3; +arcadia 4; project harbor "Harbor assistance" { oa_entity control "Harbor control" {} oa_activity respond "Respond to requests" { diff --git a/crates/oa-desktop/src/guide.rs b/crates/oa-desktop/src/guide.rs index 106c842b..78c0bbb2 100644 --- a/crates/oa-desktop/src/guide.rs +++ b/crates/oa-desktop/src/guide.rs @@ -369,7 +369,7 @@ fn article(topic: Topic) -> Article { &[ "Create the source and target activities/functions in one perspective. Give each an engineering name and allocate leaf work to its responsible participant.", "Choose Interaction or Functional exchange in the diagram palette. Click the source, then a highlighted compatible target, or drag between them. Functional exchanges connect output ports to input ports; function cards create or reuse real ports in the same transaction. Middle-button drag pans while keeping the source; arrow keys also pan when the drawing canvas has focus. Click empty space to restart, or Escape to cancel.", - "Create an Exchange item under Data & interfaces. Choose its kind (Information, Material, Energy or Event) and describe its payload.", + "Create an Exchange item under Data & interfaces. Choose its nature (Information, Material or Energy) and its mechanism (Flow, Event, Operation or Shared data). Describe the payload independently of the connection.", "Select the exchange in Model explorer or the diagram. Edit its properties to reference the appropriate exchange items and available ports; Apply changes validates the complete record.", "Choose Boundary exchange and connect compatible component ports. Flow goes from Out to In; Standard is unoriented. Select / move returns to arranging. Exchange allocation associates a boundary exchange with the functional exchange it carries.", ], @@ -380,7 +380,7 @@ fn article(topic: Topic) -> Article { ), explain( "Use engineering payloads", - "Choose Information for data such as a distress report, Energy for delivered power, Material for a transferred substance and Event for a notification. Data types and fields can make structured payloads precise. URI artifact links can point to detailed interface-control documents.", + "Choose Information for data such as a distress report, Energy for delivered power and Material for a transferred substance. Mechanism separately describes how it is exchanged: an Event is a notification, an Operation has parameters, and a Flow carries values or a physical quantity. Data types and fields make payloads precise. Artifact links can point to interface-control documents.", ), ], related: &[ @@ -510,17 +510,34 @@ fn article(topic: Topic) -> Article { const { Article { summary: "Define exchanged payloads independently of the ports and participants that carry them. Reuse the same data definitions in related exchanges.", - keywords: "data interface port direction input output inout contract provision requirement exchange item enum enumeration record primitive field value type multiplicity minimum maximum", + keywords: "data interface port direction input output inout return contract provision requirement exchange item enum enumeration record primitive field value type multiplicity minimum maximum bounds default unit specialization inheritance association storage reference recursive path transmission acquisition protocol", sections: &[ walkthrough( "Define a reusable payload", &[ - "Open Data & interfaces and create an Exchange item. Select Information, Material, Energy or Event to describe the nature of the exchange.", - "Create a Data type where the payload needs a named definition. Choose its Data type definition and edit the corresponding values in Properties.", - "For structured definitions, create Data fields under a legal Data type or Exchange item owner. Set Value type and the minimum/maximum count as required by the contract.", + "Open Data & interfaces and create an Exchange item. Choose Information, Material or Energy for nature; choose Flow, Event, Operation or Shared data for mechanism. Keep Unspecified when the engineering decision is still open.", + "Create a Data type for a reusable definition. Choose Boolean, Integer, Real, String, Enumeration or Record. Numeric bounds are inclusive; String bounds count Unicode characters. A typed default must satisfy those bounds or enumeration literals. Units annotate quantities without converting them.", + "Create fields within an Exchange item or Record type. Set Value type, minimum/maximum count, unit and optional default. A default can be absent, explicitly empty when minimum is zero, or a list of typed scalar values. A type default describes one element; it does not create a required collection.", "Select the exchange and reference the payload items. Apply changes and check the result in Model checks.", ], ), + explain( + "Operation parameters and message values", + "An Operation's direct fields are parameters. In and InOut supply call values; Out, InOut and Return supply reply values, from the provider's perspective. There is at most one Return parameter. Qualified paths distinguish origin.latitude from destination.latitude when both use the same Coordinate record. Nested fields inherit the parameter direction. Message expressions are annotations, not evaluated values.", + ), + explain( + "Reuse, ownership and references", + "A Record or Exchange item can specialize one compatible base. Inherited fields keep their original owner and identity; edit the base to change them. Value fields compose a payload. Reference fields refer to separately identified Record objects and stop payload expansion. Optional recursive values and reference cycles are valid; a mandatory value cycle warns that no finite complete value exists. Data associations describe named reference ends, multiplicities and navigation between Record types without creating contained fields.", + ), + walkthrough( + "Allocate an item to interfaces", + &[ + "Create an Interface and allocate an Exchange item. Select its allocation row to edit transmission, acquisition and order; Open item navigates to the shared payload definition.", + "Two interfaces may allocate the same item with different protocols. Attach CAD, code or document evidence to the allocation when it concerns that particular contract.", + "Removing an allocation keeps the shared item and other allocations. If a live boundary depends on it, first revise that boundary contract. Undo restores an accepted removal.", + "An Interface may specialize one base and inherit its allocations. Duplicate allocation of an already inherited item is rejected. A specialized item satisfies its base contract; a base item does not satisfy a more specific contract.", + ], + ), walkthrough( "Connect participant boundaries", &[ @@ -723,7 +740,7 @@ fn article(topic: Topic) -> Article { ), explain( "Open and migration", - "Open reads and validates a complete candidate before replacing the current project. Supported legacy files are migrated explicitly; save the resulting current format under a new name if the legacy original must remain available. Unsupported or invalid input does not replace the accepted project.", + "Open validates a complete candidate before replacing the project. Versions 1, 2 and 3 migrate explicitly to version 4; Model checks shows preserved ports, supplied data defaults, generated interface allocations and unresolved message paths. Old Event items become Information notifications; unknown physical mechanisms remain Unspecified. Source3 upgrades retain files, includes, nested ownership and comments. Opening does not overwrite the original: use Save as if it must remain in its older format. Invalid input leaves the accepted project unchanged.", ), ], related: &[Topic::Source, Topic::Recovery, Topic::Artifacts], diff --git a/docs/scope.md b/docs/scope.md index 06803192..78812937 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -8,12 +8,12 @@ Arcadia Studio implements a systems-engineering workbench spanning Operational A |---|---| | Operational Analysis | Entities, actors, roles, activities, missions, capabilities and processes; entity/work decomposition; leaf allocation; role realization/assignment; interactions and capability/process involvement | | System Analysis | One System of Interest, external Actors, functions, missions, capabilities and functional chains; functional decomposition independent of the system boundary; allocation, functional/boundary exchanges and mission-capability links | -| Data and interfaces | Information/material/energy/event exchange items, primitive/enum/record data types, typed fields with multiplicity/units, separate function input/output and Standard/Flow component ports, interface provision/requirement, port and exchange allocations | +| Data and interfaces | Information/material/energy nature and Flow/Event/Operation/SharedData mechanisms, bounded primitive/enum/record types, typed defaults, field multiplicity/units/direction/storage, specialization, identified interface allocations and reference associations, separate function input/output and Standard/Flow component ports, interface provision/requirement, port and exchange allocations | | Behavior | Process/chain work and exchange contributions, control topology and sequence reuse; scenario lifelines, correlated calls/replies, timers, action/state occurrences, ALT/PAR/LOOP/OPTIONAL fragments, scenario reuse and pre/postconditions | | States and conditions | Participant-owned state machines, nested regions, states/modes and typed pseudostates, signal/time/change events, trigger/guard/effect transitions, linked entry/do/exit work, availability and constraints | | Perspectives and evidence | Bidirectional counterpart creation/linking, reviewed name/description updates, many-to-many typed/manual traces, arbitrary artifact URI/revision/fragment references | | Views and editing | Independent diagrams, decomposition/allocation nesting, collapse, pan/zoom/Fit/Arrange, editable connection routes and labels, four-side port positioning, direct interaction/functional/boundary exchange tools, contextual menus, SVG export, model explorer and typed properties | -| Text and storage | `arcadia 3` source projects with relative includes and nested declarations, stable aliases/UUIDs, a source-file tree, per-file drafts and diagnostics, comment-preserving graphical updates, exact model/source Undo/Redo, legacy migration, atomic saves and interrupted source-save recovery | +| Text and storage | `arcadia 4` source projects with relative includes and nested declarations, stable aliases/UUIDs, a source-file tree, per-file drafts and diagnostics, comment-preserving graphical updates, exact model/source Undo/Redo, legacy migration, atomic saves and interrupted source-save recovery | | Automation | Rust REST service for project/source-bundle/query/validation/transaction/transition/artifact workflows, ETag preconditions, bounded requests and atomic current-revision storage | Graphical and textual parity applies to the persistent fields of this profile. Diagram placements are model data; camera, selection, source cursor and undo history are session state. Canvas gestures need not match textual operations one for one: typed inspectors and explicit commands expose precise semantics. Full source replacement must repair dependencies in its candidate, while graphical delete/reidentify commands maintain references automatically. @@ -45,7 +45,7 @@ These are concrete design responses, not claims that every Capella user experien ## Required first-release work -Direct state/scenario/process canvas authoring, semantic-content drift and reviewed counterpart reconciliation, expanded data contracts, persistent coverage/filter views, Home/recent-project and unsaved-work recovery, hosted desktop editing, guidance and final acceptance remain in the [release plan](../harness/PLAN.md). These are unfinished requirements, not exclusions from the release. Interrupted source-save recovery restores a save transaction; it does not checkpoint unsaved models or drafts. +Direct scenario/process canvas authoring, semantic-content drift and reviewed counterpart reconciliation, native acceptance of expanded data contracts, persistent coverage/filter views, Home/recent-project and unsaved-work recovery, hosted desktop editing, guidance and final acceptance remain in the [release plan](../harness/PLAN.md). These are unfinished requirements, not exclusions from the release. Direct state editing has scoped Windows/Linux acceptance recorded in [state evidence](../harness/release-state-editing.md). Interrupted source-save recovery restores a save transaction; it does not checkpoint unsaved models or drafts. ## Remaining boundaries diff --git a/docs/server.md b/docs/server.md index 045b43f4..1b6bde70 100644 --- a/docs/server.md +++ b/docs/server.md @@ -1,6 +1,6 @@ # Arcadia Studio server -`arcadia-server` is a headless Rust REST service for the same schema-3 model, commands, source language, validation, artifacts and OA/SA traces used by the desktop. It stores each model and its authored source project together in an atomic JSON envelope. The service provides a deployment artifact and configuration examples; this repository does not assert that a remote instance has been deployed. +`arcadia-server` is a headless Rust REST service for the same schema-4 model, commands, source language, validation, artifacts and OA/SA traces used by the desktop. It stores each model and its authored source project together in an atomic JSON envelope. The service provides a deployment artifact and configuration examples; this repository does not assert that a remote instance has been deployed. The complete HTTP contract is [api.rst](api.rst); machine-readable schemas are in [openapi.json](openapi.json), also served at `/api/v1/openapi.json`. The original [service research](research-v2-service.md) discusses broader alternatives; retained history, SQLite, idempotency receipts and stored transition plans from that research are **not** the implemented storage contract. @@ -44,7 +44,7 @@ The data directory contains `.arcadia.lock` and one `.json` file pe Startup validates every committed envelope, its filename/UUID, revision, size and complete model. Any corrupt or unsupported envelope stops startup; the service does not silently skip bad data or invent an empty replacement. Sibling `.arcadia-write-*` files from an interrupted pre-commit write are not committed models and are ignored on startup. -Earlier model-only envelopes are accepted through the existing model migrations and receive deterministic source files in memory. Opening, reading or an exact no-op neither rewrites those envelopes nor advances their revision. The next changed edit persists the coupled representation. Already-coupled envelopes must contain stable source IDs and matching model/source; inconsistent pairs are rejected at startup. Capacity accounting includes source generated in memory for old envelopes, so an over-capacity old store fails explicitly without rewriting or pruning it. +Earlier model-only envelopes are accepted through the existing model migrations and receive deterministic source files in memory. Opening, reading or an exact no-op neither rewrites those envelopes nor advances their revision. The next changed edit persists the coupled representation. Already-coupled schema3 envelopes explicitly migrate both representations in memory; the independently migrated graphs must agree. Current-format source must contain stable IDs. Inconsistent pairs are rejected at startup. Migration reports remain visible until a current-format edit/save; opening alone never rewrites the envelope. Capacity accounting includes source generated in memory for old envelopes, so an over-capacity old store fails explicitly without rewriting or pruning it. Parsing, validation and blocking disk operations run on blocking workers. A shared store mutex captures snapshots and serializes final revision checks and writes. Parsing, semantic validation, source writeback and query processing use the captured snapshot outside that lock; an expensive candidate does not block the catalog or another model's preparation. Commit rechecks the exact ETag, so a candidate prepared against a superseded snapshot returns `412 revision_conflict`. A successful changed update increments revision once. Both model and source bundle must be unchanged for `changed: false`; comment-only edits advance the same revision. Each write serializes the whole envelope to a sibling temporary file, syncs it, and atomically replaces the destination. Unix also syncs the directory. The in-memory snapshot changes only after the replacement succeeds. A directory-sync error after replacement is reported as an uncertain write outcome while the in-memory head still matches the installed file. diff --git a/harness/STATE.md b/harness/STATE.md index 6adc51d8..8f7641d8 100644 --- a/harness/STATE.md +++ b/harness/STATE.md @@ -78,9 +78,11 @@ See release-data-implementation.md and release-data-contract.md in that checkout Core is committed0b58107; source/migration1230ab8. Root API/docs are integrated on the same working tree; desktop remains in flight and R6 is not accepted. -Core15 R6 +28workflow tests passed (final allocation-arrow suppression arrived -afterward and is queued for rerun). Earlier13ports/14scenarios and115 source/lib -tests passed; strict core Clippy preceded the last geometry/performance fixes. +Core15 R6 +28workflow tests passed again after final allocation-arrow suppression. +Linux0b58107 full core307 tests passed (one explicit probe ignored by default), +with strict all-target core Clippy. Earlier13ports/14scenarios and115 source/lib +tests also passed. Desktop final257 tests and strict all-target Clippy pass; +the optimized Windows desktop build is in progress for native acceptance. Root41 server tests pass, including3 new actual HTTP workflows for the published data example, protocol/artifact identity, atomic rejected defaults, query/export, @@ -95,20 +97,28 @@ Evidence: api-r6-contract and r6-server-tests-after.log under the release direct Independent core review found association transition closure pulling unrelated types and missing empty-enum warning; both corrected and focused tests passed. Repeated per-ancestor full scans were simplified to one scan per helper call. -Explicit debug inheritance timings250/500/1000:147/664/2739ms. Optimized timing is -still required; no optimized performance claim yet. +Explicit optimized inheritance timings250/500/1000: Windows21.070/89.088/391.590ms, +Linux22.381/111.662/408.129ms. These single-run empty-chain fixtures measure core +validation, not general UI latency. A1000-deep chain remains a pathological cost. -Current ownership: drawing_correctness owns desktop except data_view.rs; -state_architecture_review now owns only data_view.rs bounded focused-dictionary -correction. Its independent review found unbounded inherited rows/picklists, -unreachable recursive paths and loss of scenario values on same-phase style or -same-exchange reselection. Drawing worker fixes recursive drill-down/draft retention. -data_core now verifies Linux in a separate data-linux-review checkout/target. -Root owns API/OpenAPI/reST, integration and native input. No concurrent file writers. +Independent desktop review fixes now pass tests: a focused dictionary with24-row +pages replaces unbounded inherited rows; recursive paths support explicit drill-down +and imported finite paths; same-phase styles/same-exchange reselection preserve +valid drafts. Read-only follow-up found no new path/style defect. Paging resets +only on actual layer/document changes; its regression failed before and passes now. +Root found another unresolved scale issue: scenario creation still enumerates every +carried field into both a dropdown and individual input rows. Native reproduction +and a bounded focused value editor remain required before R6 acceptance. + +Current ownership: drawing_correctness owns desktop except root-owned guide.rs and +the dedicated Windows Cargo target. state_architecture_review independently reviews +R6 spec/API consistency; its data_view.rs ownership has ended. data_core runs an +isolated R3 typed-baseline experiment; Linux R6 core checkout is idle and verified. +Root owns API/OpenAPI/reST, docs, integration and native input. No concurrent writers. 1. State evidence is committed and main fast-forwarded to a8f451e; DATA received - the same evidence in c5276b1. Finish the3 concrete desktop review fixes and - optimized inheritance measurement, then native data-authoring acceptance. + the same evidence in c5276b1. Finish native data-authoring acceptance and bounded + scenario-value authoring, then full integrated Windows/Linux verification. 2. Finish R6 core/source/desktop, integrate actual REST/schema/reST, independent semantic/correctness/UX review, Windows/Linux checks and real data authoring. 3. Implement R3 typed semantic drift/reconciliation after R6 freezes. Current diff --git a/harness/TASK_LEDGER.md b/harness/TASK_LEDGER.md index 9bd5665d..7fa57765 100644 --- a/harness/TASK_LEDGER.md +++ b/harness/TASK_LEDGER.md @@ -39,6 +39,9 @@ requires native workflows, semantic evaluators and fresh independent review. whole-model equality or flat reformatting. Independent counterexamples were fixed. - R3 existing-target reconciliation remains name/description only. R6 data shape expansion is active implementation, not accepted functionality. +- R6 core/source and actual HTTP semantics pass focused Windows and full Linux + core checks; desktop257 tests pass after independent draft/path/paging fixes. + Native R6 acceptance and bounded scenario-value authoring remain outstanding. ## Assumptions and open questions @@ -49,7 +52,10 @@ requires native workflows, semantic evaluators and fresh independent review. - Routing offers a usable initial path plus manual pins; arbitrary dense diagrams are not guaranteed crossing-free. Measured dense full solve119ms remains a limit. - R3 typed historical bodies plus finite proposals appear simpler than a separate - recursive semantic-value schema. This candidate awaits R6 freeze and review. + recursive semantic-value schema. An isolated probe supports scalar partial review + and deleted historical references, but ordered membership/order acknowledgements + need separate typed order checkpoints. Historical source reference parsing is + still unimplemented; this remains a candidate awaiting independent review. ## Decisions and current strategy