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](../../docs/api.rst). 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:

```text
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.