95 lines
5.9 KiB
Markdown
95 lines
5.9 KiB
Markdown
# Source workspace integration contract
|
|
|
|
Status: implementation in progress after the accepted routing checkpoint. This
|
|
is the next vertical slice of the first release, not release completion.
|
|
|
|
## Observable outcome
|
|
|
|
A system engineer opens an entry `.arcadia` file and edits its included files
|
|
independently. Switching files retains invalid drafts and cursor positions.
|
|
Located project diagnostics navigate across files. Apply adopts the entire
|
|
validated source/model pair atomically. Graphical edits preserve comments and
|
|
file ownership. Undo/Redo restores exact accepted source, including comment-only
|
|
edits. Save All writes the project with conflict detection and recoverable disk
|
|
failure handling; reopen reproduces the accepted model and source.
|
|
|
|
## Architecture and sequence
|
|
|
|
1. Add `prepare_command(project, command)` to the shared semantic command engine.
|
|
It returns a validated candidate and selected identity without mutating input
|
|
or executing creation twice. Existing semantic Session uses the same helper.
|
|
2. Desktop `Document` owns one history of accepted `CompiledSourceProject`
|
|
snapshots. Command preparation followed by `update_bundle` succeeds before
|
|
adoption. Source-only accepted edits advance revision and history. Separate
|
|
draft history remains an editor concern; do not synchronize two accepted
|
|
model/source undo stacks.
|
|
3. Keep filesystem code outside pure `source_project`. Discover includes with
|
|
`inspect_includes`, enforce aggregate budgets and portable/contained physical
|
|
paths, retain exact original disk bytes before identity stabilization.
|
|
4. Integrate file navigation, full-bundle asynchronous lint, Apply, Open and Save
|
|
into the existing Iced application. Results carry document identity and draft
|
|
generation. The active text control renders one file; inactive drafts persist.
|
|
5. Extend production syntax through the same compiler/index/updater, separately
|
|
from this integration. Never copy the experimental lowering/writer wholesale.
|
|
6. Verify real native two-file editing, failure repair, graphical rename, exact
|
|
Undo, Save All and reopen; obtain independent correctness and UX review.
|
|
|
|
## Failure and persistence decisions
|
|
|
|
- Dirty text in any file blocks graphical mutation until explicitly applied or
|
|
reverted. A failed compile/writeback leaves model, source, revision and history
|
|
unchanged. Diagnostics retain original per-file spans and related locations.
|
|
- Successful lint is advisory: only explicit Apply adopts inserted identities.
|
|
- Syntax/missing-include errors retain loaded editable documents. Removing an
|
|
include detaches its buffer; it does not delete a file. Compile reachable files
|
|
while retaining detached dirty content visibly and guarding close/discard.
|
|
- Check all dependency baselines before saving, including unchanged files.
|
|
Stage exact bytes, keep recovery information, replace the entry last and roll
|
|
back ordinary partial failure. Interrupted recovery must not overwrite a newly
|
|
observed external edit. This is recoverability, not filesystem-wide atomic
|
|
visibility or compare-and-swap with other editors.
|
|
- Source Save As retains relative file layout and reviews destination collisions.
|
|
JSON remains whole-model interchange and cannot erase source layout/history.
|
|
- Recovery/staging directories use the reserved `.arcadia-save-*` prefix. Ignore
|
|
`.arcadia-save-*/` when tracking a source project in Git; these contain local
|
|
save recovery data, not model declarations.
|
|
- Source writeback consumes the command engine's complete original-to-candidate
|
|
identity correspondence. Changing UUID/alias or swapping UUIDs preserves the
|
|
authored declaration file and associated reference-list comments. Inferring
|
|
correspondence from surviving UUIDs or aliases is insufficient. Full model
|
|
replacement uses common UUIDs as its explicit correspondence boundary.
|
|
|
|
## Production syntax direction
|
|
|
|
Retain flat syntax. Nested elements express semantic parent only; allocation
|
|
stays explicit. Contextual input/output shorthand creates real SA function ports,
|
|
with item lists and an optional ordinary field body. FE shorthand references real
|
|
ports and infers redundant function endpoints after resolution. Ordered steps
|
|
blocks cover existing scenario/process/chain/Branch semantics. Typed value bodies
|
|
remain ordinary fields; includes stay document-level. No new global reserved
|
|
aliases. The parser must expose real spans and lexical ownership, never fake
|
|
spans for inferred values. Structural edits compose around the existing
|
|
UUID-aware scalar/list updater.
|
|
|
|
Contiguous leading and same-line trailing comments travel with their declaration;
|
|
blank-separated comments stay in the containing gap. Deleted syntax leaves its
|
|
comments in the old body with separation so they cannot become the next record's
|
|
documentation. Preserve authored flat placement; prefer owner-local placement
|
|
for new children. Equal explicit parent and nesting may coexist; contradictions
|
|
fail. Shorthand-derived contracts/endpoints have one definition. Valid edits that
|
|
outgrow shorthand expand that declaration locally instead of rejecting the edit.
|
|
|
|
## Acceptance evidence required
|
|
|
|
- Creation selects the same UUID persisted in source; rejection is fully atomic.
|
|
- Comment-only Apply/Undo/Redo and history branching restore exact bytes.
|
|
- Two-file errors and stale lint/discovery cannot change newer drafts or models.
|
|
- IDs stabilize once while disk conflict baselines retain original bytes.
|
|
- Item rationale comments follow UUIDs through reorder and alias swaps.
|
|
- Nested create/delete/reparent and occurrence reorder/move preserve identity,
|
|
comments, allocations and unrelated files; empty steps blocks remain editable.
|
|
- External edits/deletions/new-file collisions reject Save All before loss;
|
|
injected partial failures and interrupted recovery preserve coherent content.
|
|
- Default/minimum-size native editing and save/reopen are observed, not inferred
|
|
from compilation. Windows/Linux builds and focused regressions pass.
|