ARCADIA-Studio/harness/release-textual-usability-audit-20260911.md

Text-only systems engineering usability audit — 2026-09-11

Author: Codex-9e8r6t /root/palette_finish. Coordination: Gitea issue #1, comment 105. Scope: the complete 815ff7b9-73c4-41a2-a809-635ecf8389d6/goal-objective.md, especially human/AI text authoring, low cognitive load, and small/large systems. Source snapshot sampled at d114a271c5ecffcd7960fb8aa44d45989c10dc33; shared creation integration was in progress. This is an independent static task walkthrough, not a timed user study, executed language test, native acceptance, or ratified notation redesign. No production edits, Cargo, or native input were used.

Main finding

The existing notation can express the three tasks without diagrams. Its concise authoring capabilities are stronger than its canonical examples suggest. The larger obstacle is maintaining an engineering context across declarations and files: finding the right reference, understanding definition versus occurrence, safely changing all uses, and knowing which omissions change meaning. Shorter syntax could help, but cannot by itself supply those capabilities.

Preserve the useful foundations: one typed model; readable alias references; stable UUID identity distinct from names; forward references; explicit allocation and reuse; strict structural checks with advisory completeness warnings; per-file drafts and one atomic bundle Apply; source-preserving updates. Evaluate authoring improvements against those properties rather than replacing them with implicit name matching or silent repair.

Evidence and method

Read production parser/conversion in crates/oa-core/src/language.rs (identity at 1226, version admission at 1404, defaults/ownership at 1634–1684), bundle compilation/updating in crates/oa-core/src/source_project.rs (286, 759, 780), the language reference sections 4.2–4.3 and 6–8, and the source editor/navigation/workspace implementations. Read the release1 engineering walkthrough and its OA process/scenario modules, plus the older nested examples/source-project/oa.arcadia as an ownership/allocation teaching pattern. The older example is a migration fixture, not evidence that a new source-7 recipe was executed.

Current editor evidence: views.rs:1115 mounts a highlighted plain text editor; the source toolbar offers Apply all, Revert file, text/model Undo/Redo and Find/go. source_navigation.rs:29 searches the supplied current buffer literally and case-sensitively; app.rs:2900 supplies only that buffer. File navigation, diagnostic/related-location navigation, and selected-model-to-source navigation (app.rs:2883) exist. The reviewed source path exposes no source-token go-to-definition, project-wide reference search/rename, completion, or folding. This is a statement about the inspected production UI, not a claim that the core lacks symbol information: language::analyze and the compiled SourceIndex already expose declarations and locations.

Counts below were computed read-only with PowerShell over exact checked-in text. A UUID clause means id "<36-character UUID>". A default line means a complete line containing only empty description/precondition/postcondition/guard or parent none, plus indentation/semicolon. Reference count means lexical @alias occurrences. Counts describe these examples, not minimum language cost or measured cognitive load.

Source artifact	Lines	UUID clauses	Counted default lines	Reference occurrences
examples/release1/oa/behavior/process_oa_response.arcadia	128	14	31	30
examples/release1/oa/behavior/scenario_oa_conversation.arcadia	64	5	10	18
examples/release1/oa/behavior/scenario_oa_full_scenario.arcadia	41	4	7	12

The complete release1 example has 30 .arcadia files, 258 UUID clauses and 483 reference occurrences. It is a useful modular teaching fixture, not evidence of large-model performance. Desktop admission allows 256 files, 64 MiB source, 100,000 graph objects, 250,000 records and 500,000 ordered references (source_workspace.rs:10); limits alone establish no usable latency or navigation scale.

Task 1 — start a small operational model entirely in text

Engineering intent: a vessel reports distress; a rescue team assesses the report. State participants, work, responsibility and the exchange before drawing anything.

Current steps:

1. Create/open a source entry, or edit its existing project body. Use source version 7. Keep the existing project's identity if extending it.
2. Declare the two participants and two activities. Choose unique aliases and readable display names independently.
3. Add an allocation from each participant to its activity. Add an interaction from reporting to assessment. Work decomposition/lexical nesting is a separate choice and does not substitute for allocation.
4. Apply all; read located errors and advisory behavior-coverage warnings. Save the returned stabilized source, including generated IDs. Later edits must retain those identity clauses.

A candidate first-authoring recipe using existing grammar follows. It is statically derived from production defaults and relation requirements, not parser-executed in this audit:

arcadia 7;
project distress "Distress response" {
    oa_actor vessel "Vessel in distress" {}
    oa_entity rescue "Rescue coordination" {}
    oa_activity report "Report distress" {}
    oa_activity assess "Assess incident" {}
    allocation vessel_reports "Crew reports" { source @vessel; target @report; }
    allocation rescue_assesses "Team assesses" { source @rescue; target @assess; }
    interaction distress_report "Distress report" { source @report; target @assess; }
}

This requires eight declaration aliases including the project and six endpoint references; it requires no handwritten UUID, diagram, node placement, empty description, or explicit root parent. Successful stabilization would insert eight identities. Missing behavior context should remain a warning, allowing this useful intermediate model to be saved. The core/parser contract supports this staged authoring; blanket completion requirements would make the task harder.

Avoidable burden: a newcomer copying canonical text learns IDs and empty defaults before engineering relationships. Keywords plus aliases plus names can also obscure which label to change: renaming the displayed activity requires changing its string only; changing the alias requires repairing its references; changing/removing an accepted UUID is an identity change. These are different tasks and deserve a compact explanation next to the recipe.

The seven semantic records here are not all boilerplate. Explicit allocations and the directed interaction are the engineering assertion. Any shorthand experiment must preserve the distinction between work ownership and performer responsibility. A text-only user should not need an architecture view to discover that distinction.

Task 2 — reuse meaningful behavior without copying its definition

Use the release1 pressure-restoration model: reuse the reviewed repair call/reply conversation inside a larger scenario; separately use an assessment or field procedure in a process/chain.

Current scenario steps:

1. Open oa/behavior/scenario_oa_conversation.arcadia. Identify its viewpoint, context, semantic participants, two lifelines, ordered Call/Reply and reply correlation. Reuse the scenario alias, not its name.
2. In the caller module, declare the larger scenario with explicit viewpoint ParticipantInteraction, suitable context and engineering pre/postconditions.
3. Declare caller lifelines representing the same controller/technician (or a valid explicit role realization). These are local participation records, not new semantic participants.
4. Declare an occurrence whose body is ScenarioUse, reference @oa_conversation, and write both { referenced @callee_line; local @caller_line; } bindings. Include that occurrence in the caller's explicit steps list and give it the caller as semantic parent.
5. Apply all and inspect binding/viewpoint/recursion diagnostics. Change the reviewed conversation once and verify both callers still refer to that definition. Delete only the use to remove one usage; do not delete the shared definition.

Current process/chain steps:

1. Inspect the reusable same-layer process/chain and its work contribution aliases.
2. Add a SequenceReference { sequence @definition; } occurrence under the caller and include it in steps.
3. Author explicit SequenceLinks for precedence/guards. The steps list does not synthesize branching links. To connect inside a reused procedure, a source-7 ContextualLink carries the reference-occurrence path and leaf occurrence; the sequence definition ID alone does not identify one use.
4. For two uses of the same procedure, choose the intended occurrence path explicitly. Validate the whole bundle, preserving the callee and the other use.

Useful existing features: no copied activities, exchanges or scenario definition; explicit lifeline mapping; recursion checks; strict viewpoint compatibility; distinct identities for repeated reference occurrences; contextual links that can target one contribution without changing the reusable definition. Lexical nesting can remove redundant parent fields, but still requires explicit steps, links and binding pairs. This is documented semantics, not missing parser inference.

Avoidable burden: the author must inspect multiple modules, carry global aliases in working memory, and translate an engineering statement into constructor wrappers, membership lists and ownership. The existing 41-line caller spends seven lines on counted defaults and four headers on UUIDs. Those costs can be reduced by authored examples and presentation without removing essential binding or occurrence information. An abbreviated form that silently binds same-named lifelines would hide errors; a context-aware insertion operation that previews exact aliases could help both human and AI editing.

Specific omission trap: language.rs:1668–1672 assigns MixedLegacy whenever a scenario lacks viewpoint, including source 7. The accompanying comment and documentation explain legacy preservation. A new text author omitting the field therefore gets legacy semantics with a warning, not a strict OA/SA viewpoint chosen from intent. Recipes should make viewpoint explicit and diagnostics should explain the choice. Changing backward compatibility or introducing new shorthand is a separate decision.

Task 3 — safely change a large modular model using text

Representative change: rename a work alias, move its declaration into a better module, and change an exchange endpoint while preserving unrelated comments, identities and reviewed links. First rehearse on release1; then use a purpose-built larger fixture with repeated display names and many modules. The latter has not been run here.

Current steps:

1. Start from the accepted source bundle and a known saved/revision baseline. Determine whether the request changes a name, alias, identity, ownership, allocation or actual exchange contract. Keep existing UUIDs for surviving objects.
2. Locate the declaration through its file or selected model object. For a text-only author starting at a reference, current in-app Find requires switching to and searching candidate files. An external editor/rg can search the bundle, but raw replacement also matches comments, strings and longer aliases unless carefully constrained.
3. Edit all affected buffers before Apply. Repair every alias use across modules. Move the declaration with its ID and update include directives as needed. A module move creates no namespace or implicit parent; lexical reparenting changes model ownership and must be deliberate.
4. For semantic retargeting, inspect dependent allocations, ports, behavior occurrences, lifelines, contextual paths and traces. The compiler catches invalid candidates, but structural validity alone cannot prove that the new endpoint is the engineer's intended endpoint.
5. Apply all once. App::apply_source compiles the reachable bundle before adoption; failure preserves drafts and the accepted model. Located diagnostics and related declarations help repair errors. Successful Apply is one model history operation; save/reopen and examine the source/semantic diff against the baseline.

Useful existing guarantees: cross-file forward resolution; duplicate aliases/IDs with related locations; explicit include graph; compiler with no ambient filesystem/network reads; stabilized UUIDs; raw draft retention; model/source transaction equality; surgical accepted-model updates that preserve unchanged fields/comments/files; revision/ETag protection for hosted bundle changes. Canonical export is explicit and separate from Apply. These are strong prerequisites for AI editing and review.

Remaining usability burden: files do not provide alias namespaces, so large projects need a global naming discipline; a clean module layout alone does not solve collision handling. Text-only alias rename lacks an exposed semantic refactor. The canonical model representation makes broad regeneration tempting, yet accepted identity and authored trivia must survive. An AI given stale or pre-stabilized buffers can accidentally recreate objects by omitting IDs. Provide accepted-source/revision context and a bounded patch workflow; do not equate valid generated text with preservation of engineering intent.

Syntax/conversion parsing may stop at the first error. Incremental feedback is therefore valuable, but a cascade of manual Apply attempts should be measured before adding speculative syntax recovery. Warning counts and task-relevant locations should remain visible without forcing completion of the entire engineering model.

Priorities, alternatives and falsifiable acceptance cases

These are proposed experiments and gates for root synthesis, not requirements already implemented or measured.

Priority / hypothesis	Bounded option and alternative	Acceptance case
P1: authors can already start with substantially less clutter	Add current-version task recipes that omit safe defaults and initial IDs, followed by the stabilized result. Alternative: an editor snippet using exactly the same grammar.	A first-time author completes Task 1 without diagrams or manual UUID work; compile/save/reopen preserve all seven semantic records and six endpoints; second edit preserves all IDs; expected coverage warnings do not block progress. Compare errors/time with canonical-example-only guidance.
P1: cross-file context costs more than token count	Project-wide symbol search, source-reference definition/references, and an explicit alias-rename preview using parser identity. Alternative: expose the same language service to an external editor instead of building a richer native editor.	In a 100-module fixture with 1,000 declarations and repeated display names, locate the intended work by kind/layer/owner and inspect all typed uses. Rename one alias atomically; no UUID changes, comments/string lookalikes untouched, no omitted cross-file uses; malformed unrelated drafts remain retained. Measure navigation actions and p95 latency rather than declaring success from model size.
P1: reusable behavior needs identity-aware assistance	A text insertion recipe/command that asks for family, viewpoint, callee and caller bindings, then previews ordinary source. Alternative: concise manual examples plus definition/reference navigation.	Reuse one conversation twice; local lifeline IDs remain distinct, both uses resolve to one definition, reply correlation remains in the callee. Wrong viewpoint/represented object and recursive use are diagnosed. A contextual link targets only the first of two chain references; the callee and second use are unchanged. No silent name matching or copied definition.
P1: safe changes must be reviewable by humans and AI	Baseline-aware multi-file patch/preview with semantic change summary. Alternative: external Git diff plus existing atomic bundle API and explicit revision checks.	Rename a display name, rename an alias, and move a declaration as three separate cases: expected identity/reference changes only. Retarget to a structurally valid but unintended object is visible in the summary. Stale base, dangling reference and incompatible retarget refuse adoption while preserving all raw drafts; repair succeeds as one transaction and Undo restores exact accepted source.
P2: canonical detail should be available without dominating authoring	Optional editor folding/dimming of identity clauses and unchanged defaults, preserving exact source and reliable copy/search/diagnostics. Alternative: author-focused formatter/export distinct from canonical export, with explicit preservation guarantees.	Compare the 128-line process task in both presentations; author correctly identifies branches, guards, reusable definitions and occurrences. Selection/copy/patch/save preserves every hidden identity. Normal Apply never expands omitted defaults or reorders authored text. No improvement claim based on fewer visible lines alone.
P2: module names need to support discovery and collision management	Document alias conventions and offer collision-aware proposals/search. Alternative: later evaluate explicit namespace/import qualification with migration and ambiguity rules.	Two modules contain same-named work with distinct aliases; author resolves each from a reference without guessing. A colliding new alias reports both definitions and retains draft. Moving a module preserves resolution. Any namespace proposal must outperform current global aliases on these tasks before ratification.

For these studies collect task completion, incorrect semantic assertions, unnoticed identity replacement, number of file/context switches, diagnosis/repair attempts, and subjective confidence. Syntax length is a supporting measure. Include both engineers editing manually and an AI producing reviewed patches from the same bounded task; test small models and repeated-name modular fixtures. Do not infer large-system usability from a parser throughput test or a single tutorial.

Concrete documentation corrections for the owning worker

1. docs/language.rst:1599 still defines document = "arcadia" "5" ..., while the surrounding section uses source 7 and production admits 3–7. Make the grammar's current form consistent and explain migration separately.
2. examples/release1/README.md:68 and :73 describe/expect schema 6, but examples/release1/model.json:3106 is schema 7 and the entry declares source 7. Correct the two expectations.
3. Explain omitted viewpoint behavior for new textual scenarios explicitly; the current parser applies MixedLegacy beyond schema-2 migration. A fresh strict scenario recipe must not rely on omission.

No source changes or validations are claimed by this report. The candidate minimal recipe needs an executable core round-trip gate before becoming teaching material. Native source-editor performance, discoverability, keyboard use and minimum-window readability remain unmeasured here. These findings complement the creation/behavior/native work; they do not establish release acceptance or authorize a new notation.

Executed follow-up — existing source-7 REST server, 2026-09-11

This appendix supersedes the preceding unexecuted qualification for the Task 1 recipe and the fresh explicit-viewpoint snippet added to docs/language.rst. Root separately authorized a bounded non-GUI experiment. It does not supersede the static-only qualification for the reuse/large-model walkthroughs or establish native/overall release acceptance.

The existing executable .local/target-gnullvm/debug/arcadia-server.exe reports arcadia-server 0.2.0; --help exposes a REST service, not a standalone parse/check CLI. Executable size is 39,743,488 bytes, SHA256 efeeb89c0d2e0f93df4472cb3e9f48b2b722a37ae1043c90a5a56f2e845fe665. This matches the preserved Windows server documented in release-source7-native-acceptance-20260907.md:84. The binary's timestamp alone does not establish its grammar version; the initial suspicion that it predated source 7 was withdrawn before drawing a result.

Compared preserved snapshot .local/linux-qa/runtime/source7-20260907T082753190288Z.tar.gz (SHA256 cbb371a93a562e1e641d7629fe351e016d63e66fc9112499b3fed6d5cd171f78) to the current core/server: all 120 files match byte-for-byte, with identical file inventory. provenance.json retains each digest and review-results.json verifies the set equality. This establishes relevant source correspondence to that preserved snapshot and the documented binary lineage; it is not a fresh build of today's entire desktop workspace.

Experiment artifacts live in harness/experiments/textual-authoring-20260911-local/. run_experiment.py starts only its own hidden server with a private fresh store and --bind 127.0.0.1:0. It imports each exact single-file SourceBundle, retrieves accepted source/model, and uses conditional source-project PUT with the returned ETag. A final restart checks persisted source/model. The server is stopped afterward; no server remains from this experiment. No Cargo, Rust/direct-rustc, desktop launch, or native input occurred.

Complete run: PASS, 26 real HTTP requests, 0.902 seconds measured script wall time. This small-fixture timing is not a throughput or large-model latency result. Independent semantic expectations were written in the experiment before comparing responses:

Case	Verified accepted meaning	Normalization and next edit
Exact Task 1 OA recipe	Exactly four root OA elements: Actor vessel, Entity rescue, Activity report, Activity assess; exactly two participant→activity Allocations and one report→assess Interaction with empty carried-items list; no diagrams, artifacts or traces.	Only eight UUID clauses inserted, including the project; all other input bytes preserved. Rename only Assess incident to Assess incident carefully: same complete model except that string, all IDs/endpoints/aliases unchanged; accepted source equals the exact requested one-string patch.
Documented fresh OA scenario	Exactly one root Scenario, explicit OperationalActivity viewpoint, no context, empty pre/postconditions and steps; no relations, diagrams, artifacts or traces.	Only two UUID clauses inserted. Rename only its display name to Assess the reported distress: exact identity/model/source preservation outside that string.

For each case, resubmitting the stabilized bundle returned changed: false with unchanged ETag and exact source; the name-only edit returned changed: true with a new ETag. Reusing the old ETag returned 412. Appending an invalid declaration returned 422. Both rejections left accepted source and model unchanged. After restarting the server on the same private store, both complete models and source bundles matched the saved post-rename values exactly.

The successful PUT diagnostics confirm staged authoring works: the OA recipe produces two work_without_behavior_context warnings and one exchange_without_behavior_context; the empty explicit-viewpoint scenario produces one empty_sequence warning. They do not prevent acceptance. These exact warning lists were separately asserted from the recorded responses in review-results.json.

The first attempt had an experiment-only JSON-shape mistake in the scenario assertion after the OA case passed: expected Shared/layer/body/Scenario instead of the schema's Oa/Shared/Scenario. The existing release1 JSON and production model enum independently confirmed the correction. Both source inputs and every semantic expectation remained unchanged. Initial response/failure artifacts are retained; the passing count comes only from the subsequent complete run.

Exact submitted/accepted source newlines are retained inside the JSON response/summary strings. Standalone .arcadia text snapshots use the host's Windows newlines; the preservation assertions compare the original HTTP strings before snapshot writing, so those display files are not a claim of byte-identical transport capture.

This closes the bounded executable acceptance gap for the two snippets, including first identity stabilization, a safe subsequent edit and retained persistence. It does not test GUI Undo, editor discoverability, aliases across modules, scenario reuse, large-system performance, or an AI authoring task. The prioritized acceptance cases above remain proposed work.