Checkpoint source 7 workflows and in-progress diagram authoring redesign
Rust checks / check (ubuntu-latest) (push) Canceled after 0s
Rust checks / check (windows-latest) (push) Canceled after 0s
Rust checks / check (ubuntu-latest) (push) Canceled after 0s
Rust checks / check (windows-latest) (push) Canceled after 0s
Preserve current core, source, REST, desktop, recovery, documentation and validation work, including AGENTS.md and the development summary. This is a work-in-progress checkpoint: the new compact palette has outstanding compilation errors and native acceptance; earlier passing gates retain their documented scope.
This commit is contained in:
Codex
+177
-25
@@ -1,8 +1,8 @@
|
||||
Arcadia Studio OA / SA Language and Editing Contract
|
||||
====================================================
|
||||
|
||||
:Version: 6 (integration in progress)
|
||||
:Status: Source-6 contract under integration; native and API acceptance pending
|
||||
:Version: 7 (integration in progress)
|
||||
:Status: Source-7 contract under integration; native and API acceptance pending
|
||||
:Core implementation: ``crates/oa-core``
|
||||
:Text suffix: ``.arcadia``
|
||||
|
||||
@@ -11,12 +11,14 @@ Arcadia Studio OA / SA Language and Editing Contract
|
||||
|
||||
This specification defines the shared Operational Analysis (OA) and System
|
||||
Analysis (SA) model, its textual language, graphical editing obligations,
|
||||
validation, persistence, and explicit migration from versions 1, 2, 3, 4 and 5. MUST, MUST NOT,
|
||||
validation, persistence, and explicit migration from versions 1, 2, 3, 4, 5 and 6. MUST, MUST NOT,
|
||||
and MAY indicate requirements, prohibitions, and permitted choices.
|
||||
|
||||
Schema 6 adds OA communication means, exchange categories and saved view options.
|
||||
Their integration and acceptance are tracked separately; this version label does
|
||||
not claim completed graphical/API parity. Schema 5 added closed typed semantic review facts to trace baselines, including
|
||||
Schema 7 adds caller-qualified process/chain links and explicit interface-operation
|
||||
selection on boundary scenario invocations. Schema 6 added OA communication means,
|
||||
exchange categories and saved view options. Integration and acceptance are tracked
|
||||
separately; this version label does not claim completed graphical/API parity.
|
||||
Schema 5 added closed typed semantic review facts to trace baselines, including
|
||||
historical references that may no longer exist in the live model. It retains
|
||||
schema 4 bounded reusable data types, typed defaults, exchange mechanisms,
|
||||
qualified values, specialization, interface allocations and associations, and
|
||||
@@ -43,7 +45,7 @@ Actual verification evidence is separate from this contract.
|
||||
2. One authoritative model
|
||||
--------------------------
|
||||
|
||||
A Project stores ``schema_version`` (6), ``id``, ``alias``, ``name``,
|
||||
A Project stores ``schema_version`` (7), ``id``, ``alias``, ``name``,
|
||||
``description``, and maps named ``elements``, ``relations``, ``diagrams``,
|
||||
``artifact_links``, and ``traces``. Each map is keyed by the UUID contained in
|
||||
its record. Duplicate map keys and mismatching keys/identities are errors.
|
||||
@@ -383,7 +385,7 @@ layer merely because the Traceability diagram has an OA or SA layer label.
|
||||
Versions 1–5 reject the new relation, category constructor, diagram field (even
|
||||
an explicitly supplied default), and category historical facts. Reading version 5
|
||||
preserves existing records, legacy OA boundaries and reviewed facts, with an
|
||||
explicit upgrade report to version 6. Source upgrading changes the version token
|
||||
explicit upgrade report to the current version 7. Source upgrading changes the version token
|
||||
without rewriting unrelated authored trivia. No old boundary is automatically
|
||||
converted into communication means. Source-6 graphical/API/native acceptance is
|
||||
still tracked separately from this integration contract.
|
||||
@@ -444,7 +446,7 @@ Port deletion cascades to incident FEs; FE deletion retains independent ports.
|
||||
|
||||
For example::
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project ports_example "Typed function contract" {
|
||||
sa_function send "Send" {}
|
||||
sa_function receive "Receive" {}
|
||||
@@ -532,6 +534,78 @@ sequence without explicit links retains its ordered linear meaning and
|
||||
adjacent-exchange gap diagnostics. Implementations MUST NOT silently invent
|
||||
topology links when loading or reordering such a sequence.
|
||||
|
||||
4.2.1. Links into reusable sequences
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``ContextualLink`` owns an explicit ``owner`` Process or FunctionalChain and two
|
||||
``OccurrenceEndpoint`` records. Each endpoint contains an ordered ``references``
|
||||
list of SequenceReference occurrence identities and an ``occurrence`` leaf
|
||||
identity. Start at the link owner; each path member MUST be a contribution of the
|
||||
current sequence and reference a valid same-layer sequence of the owner's kind.
|
||||
Descend into that referenced definition before resolving the next path member or
|
||||
leaf. The final leaf MUST be a contribution of the resulting sequence. A path
|
||||
contains reference occurrences, never work elements or sequence-definition IDs.
|
||||
An empty path denotes a direct contribution of the owner. Missing targets,
|
||||
wrong owners, wrong kinds/layers and recursive reuse are errors.
|
||||
|
||||
Repeated references remain distinct. Given P with A→B→C and two references R1(P)
|
||||
and R2(P), a link from direct X to ``[R1], B`` affects only the R1 contribution
|
||||
of B. It MUST NOT target R2.B, alter P's definition, delay R1.A by replacing the
|
||||
endpoint with the whole R1 reference, or duplicate A/B/C. Two endpoints with the
|
||||
same leaf identity but distinct paths are distinct caller contributions.
|
||||
|
||||
The closed ``purpose`` has exactly three alternatives:
|
||||
|
||||
* ``Precedence { guard }`` describes predecessor/successor order; guard is prose.
|
||||
When both paths are empty, use the existing SequenceLink. All-direct
|
||||
ContextualLink Precedence MUST be rejected, preserving one canonical encoding.
|
||||
* ``Exchange { exchange }`` identifies the same-layer work exchange connecting
|
||||
the addressed work contributions; both endpoint works MUST match its actual
|
||||
source and target. It records assembly incidence, not an implicit extra
|
||||
precedence edge.
|
||||
* ``CommonWork { work }`` requires both addressed contributions to reference that
|
||||
same-layer Activity or Function. It states shared work identity, without
|
||||
fusing executions, deleting contributions or asserting precedence.
|
||||
|
||||
For example, within a complete source-7 project with the referenced declarations::
|
||||
|
||||
contextual_link after_check "Continue this assessment" {
|
||||
owner @alarm_process;
|
||||
source { references []; occurrence @external_check; };
|
||||
target { references [@first_assessment]; occurrence @assessment_b; };
|
||||
purpose { Precedence { guard "check accepted"; }; };
|
||||
}
|
||||
|
||||
The owner controls persistence/module placement and graphical editing context,
|
||||
including when neither leaf belongs directly to it. Generic leaf source/target
|
||||
accessors MUST NOT be used to infer ownership. Rename and reidentification visit
|
||||
every typed owner/path/leaf/purpose reference. Normal deletion of any such live
|
||||
dependency removes the entire dependent link in the same transaction; it MUST
|
||||
NOT shorten a path, substitute another reference instance or change purpose.
|
||||
Retargeting a reference that invalidates a surviving link MUST refuse unless an
|
||||
explicit repair batch makes the whole candidate valid. Undo restores complete
|
||||
identities, links and authored source.
|
||||
|
||||
Admission permits at most 64reference occurrences per endpoint and counts all
|
||||
authored reference-list entries against the caller's ordered-reference budget:
|
||||
50,000 for the REST service and 500,000 for the desktop source workspace. Core
|
||||
callers select their ParseLimits policy explicitly. Duplicate work definitions
|
||||
do not erase this accounting. Cache capacity,
|
||||
cache warmth, expansion order and diagram folding MUST NOT change admission.
|
||||
Cache eviction is permitted; rejecting a valid address because a cache is full
|
||||
is not.
|
||||
|
||||
Contextual diagnostics use separate precedence, exchange/common-work incidence
|
||||
and caller coverage projections. Expand callee topology separately for each
|
||||
reference path. Synthetic entry/exit connectivity is identifiable and MUST NOT
|
||||
count as authored degree or satisfy authored guards. Missing or empty definitions
|
||||
and expansion beyond 50,000 nodes/100,000 edges MUST report incomplete analysis;
|
||||
they MUST NOT produce a guessed bypass or a complete-looking reachability result.
|
||||
For X→R1.B plus P's A→B, an advisory may report two incoming authored links at
|
||||
R1.B. It MUST NOT invalidate the model, require an invented Join, change the
|
||||
standalone P or R2 diagnostics, or claim executable synchronization semantics.
|
||||
Existing direct-only diagnostics remain unchanged.
|
||||
|
||||
4.3. Typed scenarios and reusable behavior
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -587,6 +661,68 @@ until an explicit path is selected. New graphical choices always identify a path
|
||||
Values never overwrite types or items. Expression text is descriptive, preserved
|
||||
exactly and not evaluated; an empty expression warns.
|
||||
|
||||
4.3.1. Explicit interface-operation invocations
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The optional Exchange occurrence field ``operation`` distinguishes ordinary
|
||||
messages from explicit operation intent. Omitted or ``none`` retains ordinary
|
||||
channel semantics and is omitted in canonical output. A present closed record
|
||||
with absent/``none`` ``allocation`` means an explicitly unresolved operation.
|
||||
A present ``allocation @service_operation`` selects that exact
|
||||
InterfaceItemAllocation relation, not its item UUID, a name, a port or whichever
|
||||
allocation happens to carry the same parameters. Thus parameterless Reset and
|
||||
ReadStatus operations on one channel remain distinct maintained identities.
|
||||
|
||||
Operation intent is permitted only on SA BoundaryInterface scenario Call or
|
||||
Asynchronous occurrences. A selected allocation MUST expose an Information
|
||||
Operation item through the actual concrete Standard component ports used by the
|
||||
invocation: receiver Provides, sender Requires a compatible interface exposing
|
||||
that same allocation, using the normal interface inheritance rules. Containment
|
||||
does not inherit participant interface roles onto a port. A separately allocated
|
||||
same item is not the selected allocation. The actual channel traversal determines
|
||||
direction, including an unoriented channel used in reverse. Call requires
|
||||
Synchronous transmission; Asynchronous requires Asynchronous transmission;
|
||||
Unspecified is incomplete and warns. A selected allocation without these proofs
|
||||
is an error. Explicit unresolved intent remains editable with a located warning.
|
||||
|
||||
Reply MUST store no operation selection. It derives allocation, provider and
|
||||
signature from its exact correlated Call, while independently satisfying the
|
||||
existing reply order, reverse-participant and channel checks. It may reuse the
|
||||
Call channel in reverse or use a separate explicit return channel. The separate
|
||||
channel MUST carry the selected item or an admitted subtype and satisfy its own
|
||||
actual endpoint contract, including for a parameterless/void return. The Reply
|
||||
receiver need not provide the operation; the provider was established by the
|
||||
Call. No operation or correlation may be guessed from similar names or fields.
|
||||
|
||||
Selected Call/Asynchronous values use only that operation's In/InOut signature;
|
||||
Reply values use Out/InOut/Return. All ordinary nested-path and multiplicity rules
|
||||
still apply. Unresolved operation intent preserves still-live expressions and
|
||||
performs independent live-reference/path checks with an incomplete-signature
|
||||
warning. It MUST NOT fall back to the union of items carried by the channel.
|
||||
Selecting a new allocation validates all retained values and refuses incompatible
|
||||
values without silently pruning them or creating defaults.
|
||||
|
||||
Deletion cleanup clears a deleted selected allocation to explicit unresolved
|
||||
intent and preserves still-live values; it does not erase the Call or Reply.
|
||||
The whole candidate MUST still satisfy independent channel contracts. Deleting
|
||||
the sole allocation can therefore refuse while a boundary still carries its
|
||||
now-unadmitted item. An explicit repair batch must address every affected channel,
|
||||
including a separate Reply channel. If a surviving allocation admits the item,
|
||||
deletion can succeed, but it MUST NOT select that surviving allocation as the
|
||||
operation. Item/field deletion uses the normal proven-reference cleanup rules.
|
||||
|
||||
SA→OA transition of operation intent requires one explicit
|
||||
``OperationOmission { source, rationale }`` per selected invocation. Rationale
|
||||
MUST be nonempty. Missing, irrelevant, duplicate or wrong-direction decisions
|
||||
are errors. Reply derives its Call's abstraction without a second operation
|
||||
choice. The source model retains its operation; other facts and values are mapped
|
||||
explicitly and the complete target is validated. The transition MUST NOT invent
|
||||
OA technical ports, operation identities or functional refinement to avoid this
|
||||
decision.
|
||||
|
||||
4.3.2. Scenario reuse
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ScenarioUse references an existing same-layer scenario and maps its lifelines
|
||||
with ``bindings [ { referenced @callee_line; local @caller_line; } ];``.
|
||||
Each binding is one-to-one and references a direct lifeline of the appropriate
|
||||
@@ -827,7 +963,7 @@ This complete data contract example is also exercised through the REST API:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project engineering_data "Engineering data" {
|
||||
sa_data_type voltage "Voltage" {
|
||||
definition { Real { minimum 0.0; maximum 48.0; }; };
|
||||
@@ -896,7 +1032,7 @@ This complete source example places one state from an existing machine:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project operating "Operating modes" {
|
||||
oa_entity crew "Crew" {}
|
||||
oa_state_machine modes "Modes" { parent @crew; }
|
||||
@@ -1350,7 +1486,7 @@ change.
|
||||
This valid source records deliberately different constructor/unit observations.
|
||||
Its historical integer minimum is absent; the Real side has no integer branch::
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project reviewed_dimensions "Reviewed dimensions" {
|
||||
oa_data_type oa_dimension "Operational distance" {
|
||||
definition { Integer { minimum 0; maximum 10; }; };
|
||||
@@ -1503,13 +1639,13 @@ deeply nested drafts produce a diagnostic instead of exhausting the parser stack
|
||||
|
||||
The pure ``source_project`` core API compiles a virtual source bundle, containing
|
||||
``entry`` and a ``files`` map from logical paths to UTF-8 strings. Its entry is a
|
||||
root-level ``.arcadia`` file with the source5 project header above. A project entry
|
||||
root-level ``.arcadia`` file with the source7 project header above. A project entry
|
||||
MAY also be ``include string ";"``. An included fragment consists only of ordinary
|
||||
declarations and include statements; it MUST NOT contain another version header,
|
||||
project wrapper, or project description. Includes MUST occur at document level,
|
||||
never inside an element body or typed field value. For example::
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project rescue "Rescue" id "00000000-0000-4000-8000-000000000001" {
|
||||
description "Operational model";
|
||||
include "oa/participants.arcadia";
|
||||
@@ -1575,15 +1711,15 @@ spans never refer to concatenated or synthetic source.
|
||||
|
||||
Single-string parse/lint APIs remain filesystem-free and reject include
|
||||
statements with an explicit source-bundle requirement. V1/V2 single-file imports
|
||||
continue through explicit migration. Modular projects accept source3, source4 and
|
||||
source5. Source3 is upgraded as one project, preserving file paths, includes, nested
|
||||
continue through explicit migration. Modular projects accept source3 through
|
||||
source7. Older bundles are upgraded as one project, preserving file paths, includes, nested
|
||||
ownership and comments through targeted token edits. Generated allocation
|
||||
declarations stay in their interface's existing file. Individual include fragments
|
||||
are not independently migrated. Missing UUIDs stabilize before migration so new
|
||||
allocation identities are deterministic on subsequent compilation.
|
||||
An authored source4 bundle upgrades through the strict prose-only baseline
|
||||
adapter; after any missing UUID stabilization, the version token alone changes
|
||||
to 5. Existing prose, comments, includes and nested ownership remain intact.
|
||||
to 7. Existing prose, comments, includes and nested ownership remain intact.
|
||||
Source5 semantic facet comments follow their closed selector identity through
|
||||
row reordering and reidentification; UUID-looking text does not act as an Id.
|
||||
|
||||
@@ -1866,7 +2002,7 @@ explicitly before Apply succeeds.
|
||||
|
||||
Loading detects JSON from its first non-whitespace ``{``; other input is parsed
|
||||
as Arcadia source regardless of filename. Saving an ``.arcadia`` suffix uses
|
||||
the accepted V6 source bundle (``arcadia 6``); other suffixes use V6 JSON. Both forms preserve the same
|
||||
the accepted V7 source bundle (``arcadia 7``); other suffixes use V7 JSON. Both forms preserve the same
|
||||
complete model. JSON rejects unknown fields throughout typed payloads,
|
||||
duplicate maps, unsupported versions, and structural errors.
|
||||
|
||||
@@ -1876,7 +2012,7 @@ diagrams and artifacts. Version4 prose baselines migrate with semantic none;
|
||||
their names/descriptions remain exact even when live endpoint values differ.
|
||||
The adapter MUST NOT infer semantic review from live values, and version3/4
|
||||
inputs MUST reject semantic baseline fields. The migration report retains the
|
||||
original from_schema and current to_schema 5. Reopening a current5 save produces
|
||||
original from_schema and current to_schema 7. Reopening a current7 save produces
|
||||
no migration report. The real V4 reviewed-prose fixtures remain compatibility input.
|
||||
|
||||
The schema-3 reader freezes the changed data payloads and old constructor catalog;
|
||||
@@ -1902,7 +2038,23 @@ order) and ``unresolved_message_values`` (occurrence, field, reason). These new
|
||||
report arrays default empty when reading older responses. Version 1 normalizes
|
||||
through V2, then the typed-port V3 adapter, shared V4 data upgrade and V5 review
|
||||
adapter. Original V2 and real V3 fixtures remain unchanged compatibility inputs. Current exports
|
||||
always use version 6; reading/migrating alone never saves or changes revisions.
|
||||
always use version 7; reading/migrating alone never saves or changes revisions.
|
||||
|
||||
Versions 1–6 MUST reject ContextualLink, operation fields (including explicit
|
||||
null/default values) and their new typed semantic facets. Current semantic review
|
||||
adds Occurrence.Operation and Relation.ContextOwner/ContextSource/ContextTarget/
|
||||
ContextPurpose. Historical endpoints and operation selections remain typed
|
||||
historical UUIDs, never live graph references or inferred current facts.
|
||||
Version 5/6 migration preserves old Call/Reply/values, direct SequenceLinks,
|
||||
traces, and version-appropriate view selectors without guessing operation intent
|
||||
or contextual links. An authored source upgrade changes only the version token
|
||||
until an actual model edit requires further writeback.
|
||||
|
||||
Desktop recovery MUST verify old 5/6 checkpoint fingerprints with the exact
|
||||
historical serializer and closed old-version admission before accepting the
|
||||
migrated model. It retains invalid raw buffers and authored review decisions;
|
||||
transient impact approvals are reset and plans are recomputed against the
|
||||
accepted base. A saved unchecked executable plan/command MUST NOT be restored.
|
||||
|
||||
Native source Save All checks the original contents of observed dependencies
|
||||
before staging writes. Existing target files are replaced individually and the
|
||||
@@ -1928,7 +2080,7 @@ defaults without changing any prior identity, name, reference, order, geometry,
|
||||
artifact or trace field. The original V2 golden source/JSON in
|
||||
``crates/oa-core/tests/fixtures`` MUST NOT be regenerated from the newer demo;
|
||||
they verify that every old persistent field survives. Canonical output writes
|
||||
the added defaults through the explicit schema-3, schema-4 and schema-5 migrations.
|
||||
the added defaults through explicit migration to the current schema 7.
|
||||
|
||||
The V2 adapter preserves every original identity, alias, prose, parent,
|
||||
placement, trace and artifact. Generic ports become Legacy with their original
|
||||
@@ -1947,14 +2099,14 @@ IDs, required resolutions, generated endpoint IDs/aliases/owners, and boundary
|
||||
orientation defaults. REST import, replacement, candidate validation and
|
||||
project snapshots surface the same report. Opening an old server envelope
|
||||
preserves its resource ID/revision and bytes; the next explicit edit writes
|
||||
schema 5. Model/source exports contain only the canonical model. Migration
|
||||
schema 7. Model/source exports contain only the canonical model. Migration
|
||||
reports are transient response metadata, not persisted model facts.
|
||||
|
||||
Admission checks account for generated objects and their references before
|
||||
construction. Both the old V2 contract and the resulting V5 graph are
|
||||
construction. Both the old V2 contract and the resulting current graph are
|
||||
validated. Migration itself does not save or increase a stored revision.
|
||||
Canonical second saves are stable. V1 normalization produces the frozen V2
|
||||
model and then uses these same V2-to-3-to-4-to-5 stages.
|
||||
model and then uses the same explicit adapters to reach schema 7.
|
||||
|
||||
Save validates a snapshot, writes a sibling temporary file, flushes it, and
|
||||
atomically replaces the destination. Failed serialization or validation must
|
||||
@@ -1991,7 +2143,7 @@ the assigned UUIDs explicitly.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 6;
|
||||
arcadia 7;
|
||||
project harbor "Harbor assistance" {
|
||||
oa_entity control "Harbor control" {}
|
||||
oa_activity assess "Assess assistance" {}
|
||||
|
||||
Reference in New Issue
Block a user