diff --git a/docs/decisions/issue-2060-shared-connection-design.md b/docs/decisions/issue-2060-shared-connection-design.md new file mode 100644 index 0000000000..27845dc4cf --- /dev/null +++ b/docs/decisions/issue-2060-shared-connection-design.md @@ -0,0 +1,264 @@ +# Connections across application, network and electrical domains + +## Recommendation and status + +Reuse native SDL relationships for existing application connections. +Reuse infrastructure links for their current deployment-network meaning. +Use profile-owned records and graph references for electrical descriptions. +The recursive contract needs no new connection operator. +Public SDL still needs the optional domain-profile host proposed by the +[#2059 investigation](issue-2059-domain-description-design.md). + +The shared concept is a typed connection between named subjects. +Endpoint detail adds constraints. A port or terminal need not be specified. +Domain profiles give each connection its meaning. A common view keeps those meanings. + +Issue [#2060](https://github.com/OpenRAE/rae/issues/2060) requests a design PR. +This design adds no SDL field, schema, adapter or code. +The examples are review cases. They are not runnable SDL or proof of conformance. +The [preflight](issue-2060-shared-connections-preflight.md) records the supporting boundary assessment. + +## Repository assessment + +This assessment uses revision `3eb5790183b3f757a7fcdada9167c488fa5c9f5e`. +The issue pins revision `33c09e9dfe9e26699489745809699a43e42d7630`. +Their reference and recursive-constraint specifications are identical. +Module names below are relative to `implementations/python/packages/`. + +| Owner | Existing meaning | Limit | +| --- | --- | --- | +| `raes.relationships.Relationship` | Named directed edge with typed source and target resolution. | Generic `connects_to` and string properties provide no electrical validation. | +| [ADR-052](adrs/adr-052-typed-runtime-relationship-subtypes.md), `RelationshipProxyUpstream` | Optional typed detail for a route-to-origin connection; cross-scope agreement checks. | Runtime metadata does not execute HTTP or prove reachability. | +| [Infrastructure](../../specs/sdl/document-model.md#10-infrastructure), `InfraNode.links` | Switch-backed network attachments; separate explicit deployment prerequisites. | Links also contribute provisioning dependency addresses in the current compiler. | +| [References](../../specs/sdl/references.md), `DeclarationIndex`, reference-purpose policy | Exactly one eligible declaration, with collision and ambiguity rejection. | A private profile member is not automatically a public SDL target. | +| [Recursive constraints](../../specs/sdl/recursive-realization-constraints.md), `raes_contracts.realization_structure` | Records, keyed identity, local closure, graph edges, conjunction and refinement. | The scalar graph evaluator does not validate the whole topology. | +| [Typed profiles](../explain/reference/domain-profiles.md), `raes_contracts.domain_profiles` | Exact definitions, offline admission and operation-specific installed support. | Generic contracts supply neither domain vocabulary nor a public SDL attachment field. | +| [Plan profiles](../../specs/sdl/plan-realization-profiles.md) | Constraints on existing authenticated provisioning resources. | Profiles cannot add resources, dependencies or participant affordances. | + +`raes_processor.compiler.provisioning` owns the current infrastructure-to-plan mapping. +`raes_processor.planner.prepared_node_admission` checks the corresponding required resource addresses. +Neither path should receive electrical topology through an analogy with network attachment. +Ordinary relationships remain metadata in the compiler's `_metadata_specs()` path. + +## Three comparison cases + +These sources and repo contracts inform the design choices below. +These choices do not imply conformance to those standards. + +### Application service connection + +Consider an HTTP reverse proxy that forwards its `api` route to an origin service. +[RFC 9110, June 2022, section 3.7](https://www.rfc-editor.org/rfc/rfc9110.html) +describes gateways and their upstream communication. +The request path has its own roles. Transport connections carry those requests. + +SDL already has the applicable connection detail in `RelationshipProxyUpstream`. +Its route, upstream node, optional service and selected TLS facts remain under their existing validators. +The author can instead state a coarse `connects_to` edge between eligible declarations. +That coarse statement does not assert the omitted route or TLS facts. +Neither case needs an invented TCP port. + +If both records give an upstream target, the existing agreement checks apply. +An open parent does not permit a change to an exact origin. +A service connection proves no startup order, successful request or causal effect. + +### Network link and device interface + +Consider a controller interface attached to a communication network. +[OPC UA Devices 1.05.0, section 5.4](https://reference.opcfoundation.org/specs/OPC-10000-100/5.4) +defines a device's logical network interface with protocol-specific connection-point types. +[Section 5.5](https://reference.opcfoundation.org/specs/OPC-10000-100/5.5) +gives `ConnectsTo` symmetric topology meaning. +[Section 4.7](https://reference.opcfoundation.org/specs/OPC-10000-100/4.7) +permits optional connection points in the device structure. +This connection point is not a TCP port or an electrical terminal. + +[RFC 8345, March 2018, sections 4.2 and 4.4.5](https://www.rfc-editor.org/rfc/rfc8345.html) +supplies a second network comparison: directed point-to-point links between nodes and termination points. +Its bidirectional representation uses two directed links. +Each profile thus needs its own direction rules. +Neither source gives a direction rule for all domains. + +For supported deployment networks, existing SDL `infrastructure.links` already supplies switch attachment. +It does not describe arbitrary cables or preserve a complete OPC UA or YANG topology. +A profile can describe interface ownership and network membership when those details are selected. +An author who selects only the subjects need not invent interface names or protocol details. + +### Electrical connection and CIM terminals + +Consider a breaker terminal and a line terminal connected at junction `j1`. +The breaker and line are separate subjects. +Each terminal keeps its equipment owner. Both name the same junction. +A third terminal can join that junction. It need not create three pairwise connections. + +The public +[ENTSO-E RCP data exchange specification 2.3.1, 16 October 2024](https://eepublicdownloads.entsoe.eu/clean-documents/CIM_documents/Grid_Model_CIM/RCP/2.3.1/RCP_DES_v2-3-1.pdf), +page 74, shows `Terminal.ConductingEquipment` and `Terminal.ConnectivityNode` references. +These examples support the ownership and junction comparison. +The paid IEC 61970-301 clauses were not inspected. +This design asserts no IEC-wide cardinality rules. +The preflight's historical CIM14 source is separate evidence, not an interchangeable profile revision. + +Profile records can retain equipment, terminals and junctions as distinct keyed identities. +Governed graph references express terminal ownership and junction incidence. +A CIM connectivity node is neither an SDL compute node nor a network switch. +The owning profile checks electrical kinds, multiplicity, units and selected compatibility rules. +Topology alone supplies no energized state, impedance model, load-flow solution or safe switching operation. + +Terminal detail is necessary for this terminal-level example. +A coarse equipment connection can omit it. That description is not a complete CIM terminal model. +Omission leaves the detail open. It does not forbid terminals or assert that none exist. + +## Minimum common concepts + +This table describes a common interpretation, not a new public record or base class. + +| Concept | Common meaning | Domain-owned constraints | +| --- | --- | --- | +| Connection identity | Stable identity within an explicit owner and profile revision. | Parallel links remain distinct even when endpoint subjects coincide. | +| Connection kind | Exact semantics supplied by the native contract or admitted profile. | Protocol, electrical compatibility, symmetry and graph cycle policy. | +| Endpoint subject | One identified subject of an admitted kind. | Consumer, provider, device, network, equipment or junction eligibility. | +| Endpoint refinement | Selected child identity owned by that subject. | Route, interface or terminal membership; no universal socket requirement. | +| Roles and incidence | Domain-defined association between connection participants. | Directed pairs, symmetric membership or shared-junction incidence. | + +Retain the junction identity instead of projecting it into all possible endpoint pairs. +The profile defines direction. Field order alone does not define power flow. +A profile can encode incidence with ordinary records and governed scalar graph references. +It needs no hyperedge operator in the recursive algebra. +No endpoint acquires deployment or action authority through this common interpretation. + +## Compatibility and the smallest extension + +The existing surfaces suffice for supported application metadata and switch-backed deployment networks. +They do not suffice for public authoring of arbitrary electrical subjects and their typed connections. +The gaps are a public host, domain terms and admitted semantics. +The recursive contract already meets the structural needs. + +Reuse #2059's proposed optional scenario-level profile host for non-compute descriptions. +Do not add a second universal connection section or require a physical-equipment node kind. +Each selected profile owns connection records, member identities and validation rules. +Keep profile-local members local unless another SDL declaration must address them. + +That use needs a registered declaration kind. It also needs rules for each reference purpose. +This design leaves the field name and published schema to a separate language change. + +Existing native relationship types and their typed details keep their current meanings and defaults. +For example, omitted integration direction currently defaults to bidirectional; projection must preserve that fact. +There is no new interpretation of `properties` strings as governed references. +There is no change to existing infrastructure compilation or provisioning admission. + +Public references still resolve exactly once within their purpose's candidate set. +A refined child must belong to the specified subject and have the required kind. +Profile admission constructs governed identity domains from admitted subjects, not unchecked reference strings. +Definition references remain acyclic; permitted topology cycles do not relax that rule. +Whole-graph cycle checks belong to installed profile semantics. + +Repeated imports keep each owner, profile and member identity distinct. +New governed fields need explicit rewriting at the composition boundary and revalidation after instantiation. +Private strings are not rewritten by guessing from dots or JSON Pointers. +Current relationship rewriting is selective; it is not evidence that every nested integration identifier is composition-safe. +If native and profile records repeat a fact, admission requires agreement. +Import order cannot select a winner. + +Open records keep exact children. Closed collections keep their named universe and profile revision. +Keyed members keep their identities when reordered. +Open membership permits extra conforming members. It does not permit a change to an explicit endpoint. + +Refinement uses existing conjunction and `realization_constraint_refines()` relations. +Unknown, redacted, delegated, optional, forbidden, empty and null remain distinct states. +No universal endpoint inventory or implicit observation request follows from these rules. + +## Connectivity, dependency and causal claims + +| Statement | Owning meaning | Inference it does not permit | +| --- | --- | --- | +| Service uses an origin | Application relationship and any selected typed detail. | Deployment order, successful traffic or business effect. | +| Device attaches to a network | Network topology; existing infrastructure also feeds provisioning dependencies. | Arbitrary physical wiring or authorization to exchange traffic. | +| Terminal joins a junction | Electrical incidence under its admitted profile. | Power direction, energized state or equipment-control permission. | +| Resource requires another resource | Existing deployment prerequisite contract. | A physical connection or a causal explanation. | +| An action caused an outcome | Separate model or evidence under [ADR-081](adrs/adr-081-behavioral-relation-taxonomy-and-claim-discipline.md). | Proof from an adjacent topology edge alone. | + +A permitted electrical ring can contain three equipment branches and three junctions. +That loop stays in its domain graph; it creates no provisioning dependency cycle. +Deployment dependencies and recursive definition references retain their independent cycle rules. +No rule infers a direct connection from a multi-hop path or a dependency from physical adjacency. + +## Data flow and security + +The diagram describes the proposed profile path alongside current boundaries. +It does not depict a new executing component. + +```mermaid +flowchart LR + subgraph U[Untrusted author and imported descriptions] + A[Subjects and selected connections] + E[External vocabulary identifiers] + end + subgraph P[Processor trust boundary] + V[Bounded parsing and composition] + R[Typed identity resolution] + S[(Pinned local definitions and installed support)] + C[Profile and constraint admission] + D[(Admitted description with provenance)] + end + subgraph X[Separate execution authority] + B[Authenticated plan and backend admission] + end + A -->|declarations and constraints| V + E -->|inert identifiers| V + V -->|bounded structured values| R + R -->|resolved identities| C + S -->|offline definitions and operation support| C + C -->|admitted values and explicit limitations| D + D -->|separately authorized supported operations only| B +``` + +| Asset and threat | Control at the boundary | Verification obligation | +| --- | --- | --- | +| Private topology leaks through external references. | Offline definitions; inert, credential-free locators; no device discovery. | Reject remote retrieval and executable profile payloads before mutation. | +| A connection crosses the wrong owner or kind. | Exact declaration lookup and purpose policy; child ownership checks. | Reject dangling, ambiguous, wrong-kind and relocated targets. | +| Graph data exhausts admission resources. | Existing finite byte, depth, member, identity and diagnostic budgets. | Return bounded `limit-exceeded` separately from semantic refusal. | +| Description implies device access or traffic permission. | Existing caller, target and authenticated-plan checks remain independent. | Refuse execution without separately admitted support and authority. | +| Schema validity becomes a false domain claim. | Exact semantic-contract support and whole-graph validation. | Keep unsupported semantics `unsupported`; opaque exchange is not conformance. | +| Topology is presented as observed state. | Separate author, backend-selected and observed provenance. | Require observation evidence for reachability, energized state or delivery claims. | + +Connection data contains no credentials or handler locations. +Existing secret-reference, diagnostic and logging rules remain in force. +Errors contain bounded safe identities, not raw connection strings or private values. +Residual risks include incorrect domain mappings and incomplete backend reports. +A valid description proves neither physical truth nor operational safety. + +## Positive and rejected review cases + +All cases concern design admission, except where the table explicitly identifies existing SDL behavior. +They do not claim that the proposed host or domain validators are implemented. + +| Case | Permitted result | Rejected result | +| --- | --- | --- | +| Existing proxy route with typed upstream detail. | Resolve the selected route and origin; preserve concrete shared TLS facts. | Accept contradictory route and relationship targets. | +| Sparse connection between whole subjects. | Retain the selected subject identities without inventing ports or terminals. | Require an OS socket or terminal inventory for every connection. | +| Refined network endpoint. | Preserve the named interface's owner and admitted protocol constraints. | Substitute a same-named interface on another device or an electrical terminal. | +| OPC UA symmetric membership. | Preserve symmetry under the selected profile. | Treat serialization orientation as one-way communication. | +| RFC 8345 directed link. | Preserve direction; retain two links for the bidirectional case. | Merge both directions into one indistinguishable edge. | +| Two parallel links between the same subjects. | Retain separate connection identities. | Deduplicate by endpoint pair. | +| Three electrical terminals share junction `j1`. | Preserve all terminal owners and the one junction identity. | Replace the junction with pairwise edges or an IP switch. | +| Allowed electrical ring. | Retain the loop under the profile's cycle policy. | Feed it into deployment ordering or infer causal influence. | +| Forbidden deployment or definition cycle. | Apply that graph owner's existing refusal independently. | Waive the refusal because electrical loops can be valid. | +| Exact endpoint under an open record. | Add permitted detail without changing the endpoint. | Retarget the endpoint because its parent is open. | +| Closed terminal membership; open equipment details. | Keep the named terminal set while refining unrelated permitted fields. | Add a terminal inside that closed universe or close sibling records. | +| Keyed members reordered or imported twice. | Preserve identity and keep each import's owner distinct. | Match by list position, merge imports or guess dotted-string references. | +| Invalid target or child ownership. | Refuse missing, ambiguous, wrong-kind or wrongly owned identities. | Create declarations from reference spelling. | +| Unsupported electrical semantics. | Preserve only explicitly admitted opaque exchange with its limitations. | Report electrical conformance or execute a simulator from schema validity. | +| No observation demand. | Retain the authored connection description. | Infer capture, retention, export, reachability or energized state. | + +## Effect on governing artifacts + +ADR-052, ADR-105 and ADR-121 retain their existing decisions. +This investigation changes no normative specification or published schema. +It adds no policy enforcement, architecture checker, estate model or operational runbook. +The diagrams describe existing admission boundaries and a proposed use of them. +The existing policy and architecture checks therefore need no changes in this design PR. + +A public host needs a separately reviewed schema, reference policy and composition rules. +Executable domain support needs targeted admission, refinement and refusal tests at those boundaries. +The cases above define their review scope without prescribing a universal ontology or replacing RAE semantics. diff --git a/docs/decisions/issue-2060-shared-connections-preflight.md b/docs/decisions/issue-2060-shared-connections-preflight.md new file mode 100644 index 0000000000..1429f09938 --- /dev/null +++ b/docs/decisions/issue-2060-shared-connections-preflight.md @@ -0,0 +1,179 @@ +# Shared connections architecture preflight + +## Recommendation and scope + +Issue [#2060](https://github.com/OpenRAE/rae/issues/2060) calls for a design PR, with no formal requirement attached. +Reuse native relationships, reference policy and recursive profiles first. +Keep application links, network attachment and electrical topology separate. +Deployment order and causal claims have their own rules. +The shared concept does not need to become a shared executable graph. + +This preflight sets bounds for that work. It does not select syntax or change language authority. +No new ADR is needed: ADR-052, ADR-105 and ADR-121 already govern these boundaries. +The [#2059 design](issue-2059-domain-description-design.md) supplies the domain-description context. +Its proposed profile host is not an implemented SDL field. + +Inspection revision: `3eb5790183b3f757a7fcdada9167c488fa5c9f5e`. +The issue pins `33c09e9dfe9e26699489745809699a43e42d7630`. +Both have the same `references.md` and `recursive-realization-constraints.md` contents. +Module names below are relative to `implementations/python/packages/`. +Private modules identify current owners. Later code must use the owning package's public interface. + +## Existing owners and important limits + +| Concern | Canonical owner | Boundary the design must preserve | +| --- | --- | --- | +| Declared connection | `raes.relationships.Relationship`, `RelationshipType.CONNECTS_TO` | A named, directed pair of eligible declarations. String properties add no domain checks. | +| Application detail | `RelationshipServiceIntegration`, database/mail access, forwarding edges and `RelationshipProxyUpstream` | Reuse the relevant typed detail and scenario checks. These records do not execute a connection. | +| Network attachment | `raes.infrastructure.InfraNode.links`, `raes.validator._nodes_infra_network` | Targets must be switch-backed infrastructure entries. They cannot stand for arbitrary equipment wiring. | +| Network detail | `RuntimeNetworkEndpoint`, `RuntimePublishedPort`, `ServicePort` | Attachment, host publication and node-local transport identity have distinct contracts. A service grants no traffic access. | +| Public references | `DeclarationIndex`, `build_declaration_index()`, `raes._reference_targetability`, `_relationship_endpoint_policy` | Keep exact identity and purpose-specific eligibility. Reject ambiguous names. Each new kind or detail needs an explicit policy decision. | +| Partial descriptions | `raes_contracts.realization_structure` and [recursive constraints](../../specs/sdl/recursive-realization-constraints.md) | Reuse presence, knowledge and keyed identity. Keep local closure, conjunction, refinement and bounded outcomes. | +| Domain meaning | `raes_contracts.domain_profiles`, [typed profiles](../explain/reference/domain-profiles.md) | Exact definitions and installed semantics own domain rules. The generic profile contract adds no public SDL host. | +| Deployment graph | `raes_processor.compiler.provisioning`, planner and prepared-node admission | Infrastructure links create provisioning dependencies. Physical topology must not enter that path by analogy. | +| Claims and evidence | ADR-079/081 and ADR-064/066 | A connection proves no causality or reachability. Nor does it prove delivery, live state or observed evidence. | + +The compiler's `_metadata_specs()` preserves relationships as metadata. +`_compile_node_runtimes()` includes both infrastructure dependencies and links in resource dependency addresses. +`planner/prepared_node_admission.py` also checks those required addresses. +A model or compiler change alone cannot safely change this meaning. + +`RuntimeNetworkRealization` permits only one endpoint record per network. +It supplies no general interface identity. +Do not claim it already covers several distinct OPC UA connection points on the same network. +Likewise, service-integration lookup uses local application IDs. It is not a general cross-domain address contract. + +The core graph-reference evaluator checks the scalar against its governed identity domain. +It does not perform whole-graph topology checks. +The owning graph profile checks its cycle prohibition. +Definition references must remain acyclic under every topology policy. +Do not reuse a dependency-cycle check for an electrical loop. + +## Comparison boundaries + +These cases bound the review. They do not settle the mapping or syntax. + +| Comparison case | Existing surfaces to assess | Meaning that must survive | +| --- | --- | --- | +| Consumer application connects to an engine or upstream service | Native relationship with integration, database or proxy detail. Existing application and service references. | Preserve roles, protocol and any constrained authentication. Neither endpoint needs an invented socket. | +| Device interface attaches to a network | Existing infrastructure links and runtime endpoint detail, within their deployment scope. OPC UA connection points as comparison evidence. | Keep interface ownership, network membership and communication-profile compatibility. These differ from a TCP port, cable or application link. | +| Equipment terminals meet at an electrical junction | Profile-owned records, keyed terminal identities and governed graph references. | Preserve equipment ownership, junction identity and electrical constraints. None is a compute node, IP subnet or deployment dependency. | + +[OPC UA Devices 1.05.0, section 5.4](https://reference.opcfoundation.org/specs/OPC-10000-100/5.4) +models a device's network interface and protocol-specific connection-point subtypes. +[Section 4.7](https://reference.opcfoundation.org/specs/OPC-10000-100/4.7) makes connection-point declarations optional in the device structure. +An OPC UA connection point is not an electrical terminal. +These models do not require each SDL endpoint to declare a connection point. + +For public CIM comparison evidence, the +[ENTSO-E CIM14 profile, revised 10 June 2014](https://eepublicdownloads.entsoe.eu/clean-documents/CIM_documents/Grid_Model_CIM/140610_ENTSO-E_CIM_Profile_v1_UpdateIOP2013.pdf), +section 6.3.33, distinguishes equipment terminals and connectivity nodes. +This source uses CIM14. It does not describe the IEC 61970-301:2020 model discussed in #2059. +Do not combine their cardinalities or claim current IEC conformance. + +The #2059 RCP 2.3.1 PDF could not be retrieved here. +Its detailed clauses were not reverified. + +The minimum common candidate is a typed connection between identified subjects. +Endpoint roles or refinements apply where their domain needs them. +This shared concept alone does not justify a new base class, schema or ontology. +The investigation must separate gaps in terms, public attachment, addressability and semantic support. + +Native application and deployment-network fields already cover part of the problem. +Physical equipment lacks a general public declaration host. A dotted string cannot supply one. + +## Invariants for any candidate design + +- An endpoint can name a whole declared subject. Ports, interfaces and terminals remain optional refinements unless explicitly constrained. + Existing `ServicePort` requires a port; do not fabricate a port to use it as a universal endpoint. +- If an endpoint names a child, its owner and kind must agree with the connection domain. + Build its allowed identity universe from admitted subjects, not an unverified list of authored strings. +- Keep containment separate from connectivity. A terminal belongs to equipment and may connect at a junction. + Several terminals can share that junction. Keep its identity rather than all possible pairwise edges. +- Keep stored edge order, application flow direction and electrical flow convention distinct. + A directed `source`/`target` pair does not establish power-flow direction or causal influence. +- Preserve parallel connection identities where different links join the same subjects. + Do not deduplicate solely by endpoint pair. An indirect path is not a direct connection. + Self-connections and permitted cycles need domain-specific rules, not a global assumption. +- Keep omitted detail, optional presence and forbidden presence distinct. + Unknown knowledge, empty collections and explicit null also have separate meanings. + `RelationshipServiceIntegration.direction` defaults to bidirectional. Omission there cannot silently become unconstrained in a projection. +- Local closure binds the named collection or record only. An open parent cannot replace an exact child. + Adding or reordering permitted keyed members must preserve identity and authored constraints. +- A connection type and every supplied typed detail must agree about endpoint eligibility. + Reuse ADR-052's cross-scope agreement approach when the same fact appears on a route, endpoint or relationship. +- A shared label or number does not prove protocol or electrical compatibility. + Domain rules must preserve units and the selected model edition. Do not add a global implicit conversion rule. +- Keep native addresses and JSON Pointers distinct. + Profile-local identities, external standard identifiers and compiled resource addresses also have separate roles. + Reference visibility grants no deployment, action, observation or access authority. +- Composition must keep owners distinct across repeated imports. Reject collisions and resolve variables again after instantiation. + `_rewrite_relationship_sections()` handles selected governed fields. It does not traverse all profile values or nested runtime identifiers. + In particular, do not assume `service_integration` local references already receive namespace rewriting. + +The extension seam uses immutable `DomainProfileResolutionContextModel` and an exact semantic-contract coordinate. +The host context must be explicit too. +Domain definitions own roles, member identity, compatibility, units, multiplicity and topology policy. +Required operations remain explicit through `DomainProfileAdmissionPolicyModel`. +A further domain should supply a definition and installed semantics through these seams. +It should need no new core resolver or equipment enum. + +## Cross-cutting boundaries + +The design PR changes no executing layer. +Any later executable change must keep these owners and controls. +The [#2059 preflight](issue-2059-domain-description-preflight.md#cross-cutting-layers-and-canonical-owners) +gives the broader domain boundary inventory; the connection-specific obligations follow. + +| Layer and canonical incumbents | Required treatment | +| --- | --- | +| SDL ingress: `raes._yaml_loader`, `_source_validation`, `_mapping_key_analyzer`, `SDLModel`; portable ingress: `raes_contracts.json_ingress` | Keep safe YAML and reject duplicate keys. Keep closed fields and bounds on bytes, depth and work. Direct construction and artifact admission need shape checks too. | +| Profile/schema admission: `domain_profiles`, `_domain_profile_schema_registry`, shared `ContractModel` | Keep exact coordinates, namespace trust and schema sealing. Use the safe Draft 2020-12 subset. Reject remote retrieval and unsupported keywords. Bound graph and diagnostic work. Reuse the shared validator. | +| Semantic and config admission: `admit_domain_profile_bindings()`, `realization_profiles`, runtime `backend_profiles`, `control_plane_configuration`, `manager_plan_admission` | Check complete constraints before mutation. Require explicit host and operation support. Support rows and schema validity alone cannot implement semantics. Direct runtime submissions need the same checks. | +| Identity and composition: `identifiers`, declaration index, reference-purpose policy, `raes.composition`, language service | Reuse canonical parsing, collision checks and purpose rules. Completion, navigation and validation must agree. Keep profile-local subjects local unless they need a reviewed public address. | +| Auth: `control_plane_security`, API `_auth`, `control_plane_plan_authorization` | Keep principal, target, route and authenticated-plan checks. Profile trust does not grant caller authority. Topology grants no device access or network permission. This work needs no new route. | +| Secrets/environment: `raes.runtime_environment`, `raes_contracts.secret_references`, `runtime_values`, generated-artifact contracts | Keep classification and redaction. Keep literal values and value sources mutually exclusive. Add no environment map or credential resolver to endpoints. Keep operator credentials outside public connection data. | +| URI and host/OS: `raes_contracts.uri_safety`, profile identity checks, existing artifact/module admission | Keep locators inert and credential-free. Parsing must not access networks, discover devices or files, or load handlers. Never put payloads, tokens or connection strings in shell commands or process argv. | +| Errors and logs: `raes._errors`, `raes_contracts.errors`, `diagnostics`, `operational_logging`, API `_responses` | Use `Diagnostic` for expected findings. Reuse error categories and fixed HTTP refusal envelopes. Value-object checks raise `ValueError`. The owning boundary translates failures once. Log bounded safe metadata once. Exclude payloads and connection strings. | +| Persistence and results: existing `ControlPlaneStore`, `control_plane_store_snapshots`, `realization_snapshot_sanitization`, backend result admission | Keep safe codecs, exact owners, revision checks and atomic state transitions. Check delivered refinements before publication. Add no connection database, sidecar, cache or second lifecycle. | +| Observation and evidence: observation demand, participant information-flow controls, ADR-064/066 | Keep author intent, backend choices and observations distinct. A connection proves no live reachability or energized circuit. Collection, retention, export and participant disclosure need their existing authority. | +| Publication and package policy: `specs/`, `contracts/schemas/`, `contracts/schema-publication/`, `raes_schemas.schema_bundle()`, ADR-117/121 | A later language change needs governed schema authority. It also needs generator parity and conformance cases. Keep contracts below SDL, processor and runtime. Add no reverse imports or compatibility wrappers. | +| Workflow: `.ground-control.yaml`, `.gc/plan-rules.md`, `CONTRIBUTING.md`, `noxfile.py`, `tools/nox_support/`, `.pre-commit-config.yaml` | Use the requirement-free route and targeted local checks. Keep full CI gates, release-please ownership and ADR pins. Formal evidence captures use the existing content-addressed workflow. | + +The trust path remains author data → bounded parsing → typed references and offline admission → admitted description. +Execution needs a separate request and installed support. +It then requires an authenticated plan and ordinary backend admission. +Endpoint locators never select code or grant execution authority along that path. + +## Review evidence and non-goals + +The eventual design needs positive and rejected examples. +Cover both sparse and refined connections. +Include an omitted port and a dangling or wrong-kind endpoint. +Also include incompatible domain refinements and conflicting duplicate facts. + +Include a shared junction, an allowed electrical loop and parallel links. +Keep a separate example of a deployment dependency cycle. +Cover repeated imports, keyed reordering and additions to a closed collection. +Include an exact child under an open parent too. + +Unsupported domain semantics must remain unsupported. Opaque carriage cannot establish conformance. +Label examples as supported SDL, programmatic contracts or proposals. Use their actual entry point to choose the label. + +Reuse the existing endpoint/candidate-parity, runtime integration, recursive-normal-form and profile admission tests. +Focused inspection probes passed 15 cases across these owners: +`test_issue_1339_relationship_candidate_parity.py`, `test_runtime_platform_application.py` and `test_issue_1203_recursive_normal_form.py`. +They check existing behavior only. +They do not prove the proposed model or standards conformance. +This prose-only preflight needs no new behavior or mutation tests. + +Non-goals include a universal ontology or required terminal inventory. +Do not add dependency semantics or replace the realization algebra. +Public syntax and schema changes are outside this preflight. +So are protocol clients, network publication, equipment actuation, simulators, Parts and new persistence. + +Do not hide enforced meaning in `Relationship.properties`, descriptions, labels or arbitrary backend payloads. +Do not remodel a CIM connectivity node as a compute node or network switch. +Do not infer connectivity from dependency, causality from connectivity, or safe operation from a valid description. +Do not add a second schema, validator, exception family or workflow for connections. +The later design PR must complete the comparison and choose the smallest compatible extension, if any.