ARCADIA-Studio/examples/release1/README.md

Restore safe water pressure

This source-7 project follows one engineering question: after a pressure alarm, can the control room restore service remotely, or must a technician repair a valve? It connects the operational need to an explicitly chosen coordination-service boundary. Allow about 25 minutes for the walkthrough.

Copy the whole examples/release1 folder to your working location, then open the copied project.arcadia in Arcadia Studio. Keep the folder together: the entry includes 29 modules, and the evidence link is relative to it. If you instead use Save As to a new folder, it copies model source files only: also copy evidence/ beside the new entry and keep this README available. Save As does not copy external artifact targets. Existing older examples remain useful migration exercises.

The numbers, guards and states describe an illustrative design. The model does not simulate hydraulics, execute a control algorithm, or establish the safety of an actual water network.

1. Start with responsibility, not equipment

Open saved view 1 · OA responsibility and repair traffic. The Control room assesses the alarm, resets the valve and confirms pressure. The Field technician performs field repair. The parent activity Restore safe pressure groups these leaf activities; responsibility is allocated to the leaves.

Inspect Technician service conversation (oa_contact). This unoriented CommunicationMean connects operational participants. Request field repair and Report repair result are Interactions between their allocated activities. Each Interaction is explicitly allocated to the communication mean. No OA port or implementation component has been introduced.

Inspect the Valve repair exchange item and its pressure parameter. The parameter has direction InOut, Value storage, multiplicity 1..1, and a real-valued type bounded from 0 to 600 with unit text kPa. The unit documents the contract; no conversion is inferred.

2. Follow the alternative and its reusable procedure

Open process Handle a pressure alarm (oa_response) in the behavior workspace. Its first step references Assess an alarm procedure (oa_assessment_procedure), whose Action uses the assessment activity and whose ChainInvolvement supports Assess an alarm. Follow that reference to the Choice in the main process. The guarded branch allows an authorized remote reset; the else branch references Field repair procedure (oa_field_procedure). Both paths merge before confirmation. The explicit SequenceLinks define flow; the list of steps alone does not imply those branches.

Open the referenced procedure. It contains request exchange, repair action, then report exchange. The parent process reuses that procedure by identity. It does not copy its actions. The main process contributes to the restoration capability.

Open scenario Repair request and measured reply (oa_conversation). The Control room calls the technician using the communication mean, supplying 420.0. The technician's correlated Reply returns 320.0 on the reversed participant pair. The reply points to the actual Call. The enclosing scenario (oa_full_scenario) reuses this conversation with two explicit lifeline bindings.

The mission Maintain safe water supply links to the restoration capability, which includes the assessment capability. The repair conversation has the restoration context: it begins after assessment and coordinates repair. The assessment procedure supplies the separate assessment behavior support.

3. Examine the explicit SA engineering decisions

Open 2 · SA service boundary and functions. The chosen System is Pressure coordination service; the technician remains outside as a SystemActor. OA activities have traced SA functions. The communication mean has a traced SA BoundaryExchange (sa_contact), with two explicitly chosen Standard component ports. The two Interactions have traced FunctionalExchanges with directional function ports.

Inspect Valve repair service (sa_repair_interface), its synchronous Operation acceptance, and the client Requires / provider Provides links. Four PortAllocations connect the function ports to their component ports; two ExchangeAllocations connect functional traffic to the boundary exchange. These are explicit contract refinements. An operational channel cannot choose the technical interface or ports on the engineer's behalf.

The generator performs the real OA→SA transition. transition-before.json is the OA model plus the two intentionally named SA participants. transition-request.json contains their explicit mappings and both component-port Create decisions. It deliberately leaves the operational ExchangeAllocations out of this first transition: those allocations require the later reviewed SA interface and port refinements. Omitting these allocations is explicit, not silently guessed.

For a fresh transition exercise, import transition-before.json, select the OA content, map Control room to the existing System and Field technician to the existing SystemActor, and review both communication endpoint ports. The supplied request is the exact programmatic counterpart. The generated final project then adds the interface/port allocations, views, evidence and one unfinished function. Fresh transition UUIDs are normalized by the generator for stable published files, so an interactive replay is semantically comparable rather than byte-identical to model.json.

4. Compare views without changing the architecture

Switch between 2 · SA service boundary and functions and 3 · SA service conversation only. They place the same semantic identities. The focused view uses the participant exchange category, an explicitly empty work-category selection, and NameAndItems labels. It shows the boundary conversation and hides functional traffic. The underlying exchanges and their port positions remain unchanged.

Open View properties to inspect the selections. Clearing a filter does not delete a relation. The category is an engineering collection of existing exchanges; it is not a replacement exchange. 4 · SA mission and included capability supplies a separate goal view.

Open 5 · SA pressure supervision in the state workspace. Follow the initial state to monitoring, the typed high-pressure Change event into waiting, and the guarded return. Waiting has an Entry action linked to the assessment function. This is an event/action relationship, not free prose embedded in a transition label.

5. Investigate the deliberate warning

Model checks should report exactly one warning: work_without_behavior_context on Audit pressure thresholds (sa_audit_thresholds). It has a responsible System but no process/chain or scenario use. expected-diagnostics.json records the expected located issue.

Decide whether threshold auditing belongs in the response process, in a separate maintenance behavior, or outside the intended model. Add the appropriate behavior use or remove the explicitly out-of-scope function. Merely hiding it in a view would not resolve the coverage question. The supplied model intentionally leaves this decision open.

6. Make one reviewed change and inspect its source

1. In OA, rename Confirm safe pressure (oa_confirm) to Confirm stable pressure and Apply the edit.
2. Open semantic OA→SA review for that activity and its existing function counterpart (sa_confirm). Review the Header Name facet and choose Take source. Preview, then Apply the reviewed change.
3. Confirm that the SA function name changed while the deliberately different System name remains Pressure coordination service.
4. In Source, inspect sa/functions/function_sa_restore_work.arcadia and traceability.arcadia. The counterpart name and review history change. Unrelated modules retain their text. Use Undo/Redo in this editing session to inspect the reviewed transaction; then Save and reopen to check persistence. Undo history is session-local; reopening restores the saved model, not the previous undo stack.

The integration oracle executes this exact semantic review and source update. It separately proves that changing the request Interaction to target a Control-room-owned activity violates the communication allocation's performer pairing: command and source-update paths reject the invalid candidate together.

Source, service and reproducibility

File or folder	Purpose
project.arcadia	Openable source-7 entry with all module includes
oa/, sa/	Participants, work, data, capabilities and reusable behavior
views/	Five saved views; filters and placements are presentation state
traceability.arcadia	OA↔SA correspondence and review history
model.json	Current schema-7 interchange of the final accepted model
transition-before.json, transition-request.json	Explicit first-transition replay inputs
evidence/repair-check.md	Local teaching evidence linked from the SA conversation
model.rs	Deterministic lesson builder shared by generator and tests

The REST routes are documented in the API reference. Import model.json with POST /api/v1/projects/import; query the returned resource's /model and /validation. Expect schema 7 and the one warning above. JSON import provides canonical source; to retain the exact modular source layout, use /api/v1/projects/import-source-project with a SourceBundle containing entry project.arcadia and only the 30 reachable .arcadia file strings, keyed by slash-separated relative paths. Neither route reads the artifact target from your local filesystem.

For transition replay, import transition-before.json instead. Submit transition-request.json to that baseline resource's /transitions/preview with its current ETag in If-Match. Review the returned plan, then follow the documented /transitions/apply protocol. Use the baseline resource for this exercise: the final model already contains the mapped records and subsequent refinements. This tutorial's automated evidence is core/source validation; it does not claim a separate native or HTTP acceptance run of this particular example.

From the repository root, with the supported Rust toolchain available:

cargo run --locked -p oa-core --example generate_release1 -- examples/release1
cargo test --locked -p oa-core --test release1_teaching

Regeneration deliberately overwrites the generated source and JSON in the selected output folder. Copy the lesson before experimenting. No old examples are rewritten. The tests check deterministic regeneration, exact source/interchange parity, explicit transport and reply direction, behavior reuse, view identity/geometry, atomic rejection, and a reviewed name change preserving unrelated modules.

The available SVG export is for architecture views. Faithful process, scenario and state-scene SVG export is outside this first-release export scope; the interactive behavior workspace is the authoritative rendering for this exercise.