feat(server): expose typed semantic transition review
This commit is contained in:
+124
-6
@@ -124,6 +124,15 @@ bearer token, if any. Non-loopback binding requires a configured token.
|
||||
* - POST
|
||||
- ``/api/v1/projects/{id}/transitions/apply``
|
||||
- Conditionally apply that client-held plan and base_revision.
|
||||
* - POST
|
||||
- ``/api/v1/projects/{id}/semantic-transitions/query``
|
||||
- Read selected traces' typed facts, own drift and linked impacts.
|
||||
* - POST
|
||||
- ``/api/v1/projects/{id}/semantic-transitions/preview``
|
||||
- Prepare typed semantic decisions and source writeback without writing.
|
||||
* - POST
|
||||
- ``/api/v1/projects/{id}/semantic-transitions/apply``
|
||||
- Apply that prepared candidate under its original shared revision/ETag.
|
||||
|
||||
``Content-Type: application/json`` is required for JSON requests.
|
||||
``text/plain; charset=utf-8`` is used for Arcadia source. The service does not
|
||||
@@ -146,8 +155,8 @@ Parsing, validation and query processing use snapshot workers, so this work
|
||||
does not hold the catalog lock or serialize unrelated model preparation.
|
||||
|
||||
Import accepts schema-1 JSON through the shared explicit migration adapter,
|
||||
as well as schema-2, schema-3 and current schema-4 JSON. Source import uses the shared language parser
|
||||
and its supported migrations. Export uses schema 4 / arcadia 4. Native JSON
|
||||
as well as schema-2, schema-3, schema-4 and current schema-5 JSON. Source import uses the shared language parser
|
||||
and its supported migrations. Export uses schema 5 / arcadia 5. Native JSON
|
||||
replacement accepts supported older schemas through the same explicit migration.
|
||||
Only documented query parameters are accepted. In particular, appending
|
||||
``?revision=...`` to model/source export is an error, not historical retrieval.
|
||||
@@ -160,7 +169,7 @@ A source bundle contains ``entry`` and a map of ``files``. For example::
|
||||
{
|
||||
"entry": "rescue.arcadia",
|
||||
"files": {
|
||||
"rescue.arcadia": "arcadia 4; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
|
||||
"rescue.arcadia": "arcadia 5; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
|
||||
"oa/work.arcadia": "// Engineering rationale\noa_activity assess \"Assess assistance\" {}\n"
|
||||
}
|
||||
}
|
||||
@@ -172,7 +181,7 @@ targets or another hosted resource. All submitted files must be reachable;
|
||||
missing files, cycles, duplicate keys, case collisions and escaping paths are
|
||||
rejected. The bundle permits at most 256 files, 32 include edges along a path,
|
||||
and 1,024 include edges in total. Model and source-byte budgets apply across
|
||||
the complete bundle, not separately per file. Current bundle syntax is source4; source3 bundles migrate explicitly while
|
||||
the complete bundle, not separately per file. Current bundle syntax is source5; source3/4 bundles migrate explicitly while
|
||||
preserving their files/includes/comments. V1/V2 single-file migration remains
|
||||
available through interchange import.
|
||||
|
||||
@@ -394,7 +403,7 @@ contract in the same transaction when removing a used interface allocation.
|
||||
Explicit schema1/2/3 migration preserves prior identities and typed ports. Reports
|
||||
add semantic defaults, generated interface allocations and unresolved message
|
||||
values. Old source3 bundles retain files/includes/comments during upgrade; all
|
||||
current exports use schema4/source4. Reading an old envelope does not write it or
|
||||
current exports use schema5/source5. Reading an old envelope does not write it or
|
||||
advance its ETag. Canonical exports omit transient migration reports.
|
||||
|
||||
Validation
|
||||
@@ -410,7 +419,7 @@ or::
|
||||
|
||||
or::
|
||||
|
||||
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 4; project rescue \"Rescue\" {}"}}}
|
||||
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 5; project rescue \"Rescue\" {}"}}}
|
||||
|
||||
A well-formed validation request returns 200 with ``valid`` and ``issues`` even
|
||||
if its candidate is invalid, including a model record that fails typed decoding.
|
||||
@@ -506,6 +515,115 @@ authenticated as an untouched server preview; the same authenticated client
|
||||
can submit ordinary typed commands. The core fingerprint is a change detector,
|
||||
not a security digest. There is no plan token, expiration store or receipt.
|
||||
|
||||
Typed semantic transition review
|
||||
--------------------------------
|
||||
|
||||
The sibling ``semantic-transitions`` routes use the `typed review semantics
|
||||
<language.html#typed-semantic-review-facts>`_ in ``language.rst`` sections 5.1–5.5.
|
||||
The original prose transition routes keep
|
||||
their existing contract. All new routes use JSON and the existing authentication,
|
||||
capacity, worker and error boundaries.
|
||||
|
||||
Query accepts ``{"traces":["trace-uuid"],"references":{},"revision":1}``.
|
||||
``references`` is an optional map of canonical OA UUIDs to SA UUIDs, including
|
||||
historical deleted identities. It never guesses correspondences from names.
|
||||
``revision`` is optional; a mismatch returns 409. Select 1–100 unique existing
|
||||
trace IDs; an empty or duplicate selection returns 400 and a missing trace
|
||||
returns 404. The response includes the current revision and items containing
|
||||
``trace``, ``oa``, ``sa``, typed ``facets``, ``drift`` and ``linked_impacts``.
|
||||
Own and linked drift and their unreviewed flags remain distinct. Query reads one
|
||||
immutable snapshot, does not refresh baselines, and does not fetch artifact URIs.
|
||||
|
||||
Preview accepts ``SemanticTransitionRequest``::
|
||||
|
||||
{
|
||||
"transition": {
|
||||
"direction": "OaToSa",
|
||||
"sources": ["40000000-0000-4000-8000-000000000002"],
|
||||
"scope": "SelectedOnly",
|
||||
"mappings": [{
|
||||
"source": "40000000-0000-4000-8000-000000000002",
|
||||
"target": "40000000-0000-4000-8000-000000000003",
|
||||
"target_kind": null
|
||||
}],
|
||||
"fields": [], "resolutions": [], "destination_diagram": null
|
||||
},
|
||||
"traces": {}, "references": {},
|
||||
"reviews": [{
|
||||
"source": "40000000-0000-4000-8000-000000000002",
|
||||
"resolutions": [
|
||||
{"facet":{"Header":"Name"}, "decision":"TakeSource"},
|
||||
{"facet":{"Data":"Unit"}, "decision":"KeepTarget"}
|
||||
],
|
||||
"reset": []
|
||||
}],
|
||||
"candidates": [], "accepted_impacts": []
|
||||
}
|
||||
|
||||
The example maps an existing OA data type to its traced SA counterpart, takes
|
||||
only its name and acknowledges intentionally different units. Other facets stay
|
||||
unreviewed or retain their earlier drift. Select an explicit trace through the
|
||||
``traces`` map (source UUID to trace UUID) when multiple trace kinds connect the
|
||||
pair. ``reset`` deliberately invalidates exact old selectors after changed
|
||||
correspondence. The optional collections default to empty. Semantic header
|
||||
decisions use typed facets; leave legacy ``transition.fields`` and
|
||||
``transition.resolutions`` empty.
|
||||
|
||||
Facet selectors are closed enums, for example ``{"Data":"IntegerMinimum"}``
|
||||
or ``{"Member":{"collection":"SignalItems","keys":{"oa":"oa-uuid","sa":"sa-uuid"}}}``.
|
||||
Annotation keys contain the entire path and field; enum literal keys are exact
|
||||
strings. ``KeepTarget``, ``TakeSource`` and ``Candidate`` operate on independently
|
||||
selected facts. Candidate records use existing Element/Relation/ArtifactLink
|
||||
types, must preserve identity/alias, and must equal precisely the result of
|
||||
the selected facets. Constructor review covers its coupled introduced/removed
|
||||
fields. Membership review does not silently acknowledge order; target-only
|
||||
members remain independent. OpenAPI defines every selector and typed payload.
|
||||
|
||||
Preview requires ``If-Match`` and returns ``{"base_revision":1,"plan":{...}}``.
|
||||
The plan contains the original typed request, mapping plan, review facts,
|
||||
acknowledged/retired selectors, linked impacts, exact prepared impacts, conflicts,
|
||||
commands, and base/prepared fingerprints. A conflict-free preview also prepares
|
||||
the complete authored source bundle and checks its model equivalence and capacity.
|
||||
No preview changes the model, source, revision or stored bytes.
|
||||
|
||||
If ordinary preparation induces additional cleanup, the plan reports exact typed
|
||||
before/after impacts and a conflict. Review those impacts, place the accepted
|
||||
records in ``accepted_impacts``, and request another preview. Acceptance cannot
|
||||
override a contradictory selected facet. Missing mappings, ambiguous order,
|
||||
duplicate decisions, invalid candidates or unresolved impacts cannot be applied.
|
||||
This is the shared core planner and command preparation, with no server-specific
|
||||
semantic mutation engine.
|
||||
|
||||
Apply accepts the entire preview envelope under the same ``If-Match``. It checks
|
||||
``base_revision``, the model fingerprint, unresolved conflicts, the prepared
|
||||
candidate fingerprint, ordinary model validation and coupled source preparation,
|
||||
then atomically stores one accepted model/source revision. The final store check
|
||||
also catches a concurrent edit during preparation. Source-only edits invalidate
|
||||
the preview through the shared ETag even when the model fingerprint is unchanged.
|
||||
Stale ETag/revision returns 412; semantic rejection returns 422 with code
|
||||
``semantic_transition_rejected``. Exact no-op candidates preserve revision.
|
||||
Read and preview again after a successful changed apply before reviewing further.
|
||||
|
||||
A supplied plan remains a client-owned candidate. Fingerprints detect stale or
|
||||
inconsistent proposals; they are not tamper-proof signatures, authentication
|
||||
receipts or proof of original review authorship. Apply preserves preview-generated
|
||||
identities and does not rerun the planner with fresh random IDs. Authenticated
|
||||
clients already have ordinary model/source editing privileges. The server does
|
||||
not persist plans, tokens or review sessions.
|
||||
|
||||
Requests allow 100 sources, trace choices and reviews; 200 mappings, candidates
|
||||
and accepted impacts; 5,000 canonical reference mappings; and 5,000 facet
|
||||
resolutions plus resets across all reviews. The legacy 400 prose-resolution
|
||||
limit and 200-command transaction limit still apply. Query has the same 5,000
|
||||
reference-map limit. Core bounded linked traversal errors remain observable as
|
||||
semantic rejection; no truncated result silently claims complete review.
|
||||
|
||||
Schema/source 5 adds ``TraceBaseline.semantic``. Absence or null is Unreviewed;
|
||||
migrating older prose baselines does not fabricate semantic history. The persisted
|
||||
baseline contains only closed typed ``FacetReview`` facts, not whole candidate
|
||||
records or a generic JSON value tree. Historical UUIDs remain historical, including
|
||||
after deletion, and source uses explicit ``uuid`` tokens for them.
|
||||
|
||||
Error contract
|
||||
--------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user