Carry resolved realization posture through the backend-facing plan

[Brad-Edwards]

Finding

RAE provides Scenario.realization, AuthorRealizationPosture, scoped resolution, and SEM-218 compiled realization requirements. The backend-facing provisioning plan does not carry a complete resolved open/closed boundary that a backend can apply to the node and concern state it realizes.

A backend therefore cannot reliably distinguish:

• a closed omission, where additional scenario state is forbidden;
• an authored open concern, where backend selection is permitted within capability and envelope constraints;
• a constrained or exact leaf beneath an open scope; and
• backend/apparatus state that is outside scenario authorship but still requires governance and evidence.

Backend capability support, including OPEN_REALIZATION, cannot substitute for this missing author permission.

Impact

Backends must guess, implement parallel posture rules, or treat capability as authorization. This prevents end-to-end enforcement of the authoring boundary and undermines non-approximation evidence.

Required investigation before solutioning

Before changing plan contracts, investigate and document the existing architectural and design patterns in this repository, including:

• designation records across parsing, expansion, instantiation, and compilation;
• CompiledRealizationRequirement and concern registration;
• ProvisioningPlan and PlannedResource authority boundaries;
• realization envelopes, apparatus defaults, backend manifests, and artifact requirements;
• runtime disclosure, provenance, safe persistence, and control-plane handoff;
• module namespace and most-specific-scope behavior; and
• how reference, libvirt, and downstream APTL adapters currently reconstruct or lose posture.

Determine the minimum portable authority a backend needs without exposing authoring-only machinery or creating a second semantics layer. Do not select a carrier shape until this analysis is complete.

Acceptance criteria

• An architectural record traces realization posture and governing scope through every processing phase and identifies the exact loss points.
• The backend-facing execution handoff preserves enough typed authority to distinguish closed, open, constrained, exact, and delegated concerns.
• Backend OPEN_REALIZATION capability is never treated as author permission.
• Exact leaves retain precedence beneath open scopes.
• Closed omissions cannot be silently materialized as scenario state.
• Open selections remain bounded by backend capability and the applicable realization envelope.
• Apparatus/backend-only state remains distinct from scenario state and is disclosed through its owning contract.
• Runtime non-approximation and provenance evidence use the same resolved boundary admitted during planning.
• Conformance tests cover root/scoped open and closed posture, leaf precedence, imports/namespaces, delegation, unsupported openness, and excess state.

Relationships

Runtime concern coverage: #1078. Mechanism-neutral compute intent: #1076. TechVault authoring consumer: OpenRAE/env-packs#288. APTL enforcement consumer: Brad-Edwards/aptl#916.

Requirements

• SEM-218 — Explicitness And Realization Semantics

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 1067-resolved-realization-posture, 2026-08-10T05:02:21.325Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1067). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1067). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

Execution obligation OBL-1067-LITERATURE-LINKS — Opened

Category: quality
Observed state: SEM-218 references a curated research/research/primary/literature directory and local source files that are absent from the repository checkout.
Impact: Peer reviewers and implementers cannot reconstruct the cited primary-source basis from the documented paths.
Current obligation: Replace absent local literature paths with stable primary-source citations and verify all SEM-218 prior-art links resolve to repository-present or stable external authorities.

Evidence

• find research/research/primary/literature/dsl-and-standards returned no such file or directory
• specs/formal/realization/explicitness-and-realization.md:623-671 contains the absent corpus and file references

[Brad-Edwards]

gc workflow phase recorded: plan (issue #1067). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Remediation brief

Gap claim

The SEM-218 authoring cascade, explicitness records, compiled demands, apparatus admission, and in-process disclosure exist, but provisioning-plan-v1 drops the resolved author boundary. The loss prevents a portable backend or HTTP control plane from distinguishing a closed omission from an authored open concern, retaining exact/constrained leaf precedence, or proving that runtime evidence used the same authority admitted during planning. Evidence and loss points are recorded in docs/decisions/issue-1067-resolved-realization-posture-handoff-preflight.md; the affected scenario is any plan with registered node/content realization concerns, including the TechVault/APTL consumer paths named by the issue.

Existing surface audit

• Authoring and phase carriage: Scenario.realization, RealizationDesignationRecord, composition pointer rewriting, namespace provenance, resolve_realization_designation, and semantic RFC 6901 validation already own scoped posture.
• Explicitness and constraints: ExplicitnessClass, ExplicitnessProvenance, CompiledCapabilityConstraint, RealizationValueConstraint, process-limit records, and DomainDescriptor already own leaf specificity and typed bounds.
• Concern ownership: RealizationConcernDescriptor, registered_realization_concern_descriptors, and CONCERN_PAYLOAD_PATH already own concern identity, payload location, projection, sanitization, and evidence needs.
• Planning and handoff: RuntimeModel.realization_requirements, materialize_realization_requirements, ProvisioningPlan, ProvisioningPlanModel, provisioning_plan_model, and the reverse control-plane converter are the canonical pipeline. The plan currently carries only operations, diagnostics, and envelope identity.
• Execution and evidence: _call_backend_apply, realization_disclosure, registered-concern evaluation, snapshot sanitization, provenance, and atomic control-plane persistence already own non-approximation. The direct manager supplies requirements out of band; HTTP submission cannot.
• Backends and downstream: reference and libvirt interpret the same planned-resource readers but cannot recover posture. APTL has no in-repo adapter and must consume the language-neutral plan contract.
• Published contract and governance: the draft provisioning-plan-v1 schema, fixtures, schema-publication entry, bundle generator, manifest/profile authority sets, and conformance validators are the governed migration surface. Recent PR feat: govern portable runtime process limits #1080 and issues Represent and govern runtime resource limits required by realized services #1066/Lower RuntimeConfiguration dimensions into the realization concern registry (SEM-218 I4 / dynamic-composition readback) #985 are the nearest typed-domain, concern-registry, and runtime-evidence precedents.

Near matches are insufficient: backend capability and the realization envelope describe what a backend can do, not what the author permitted; operation payload absence cannot distinguish closed from open; provenance after execution cannot reconstruct missing planning authority; and CompiledRealizationRequirement omits closed concerns and is an internal demand type rather than a portable contract.

Lineage and precedent

This extends the accepted SEM-218 family and ADR-008/ADR-061/ADR-070/ADR-078 boundaries; it does not create a new semantic family or ADR. The scoped cascade from #766, concern lowering from #985, and typed process-limit work from #1080 establish the repository lineage. ADR-063 identifies downstream plan consumption; ADR-066 keeps evidence distinct; ADR-098 keeps artifact requirements on their owning contract.

Literature and practice

The implementation follows the primary-source synthesis already normative in specs/formal/realization/explicitness-and-realization.md: Modelica fixed/start semantics, PDDL requirement refusal, OMG MDA intent/realization separation, XML Schema PSVI provenance, and OWL's open-world contrast. Security-domain precedents are CACAO 2.0, OpenC2, and VSDL. The design also reuses the bounded structural-domain criteria in docs/research/realization-envelope/prior-art-and-design-criteria.md. Broken references to the absent local literature corpus will be replaced with stable primary-source links under obligation OBL-1067-LITERATURE-LINKS.

Alternatives

1. Do nothing/evidence-only: rejected because observations cannot prove author permission that never crossed the handoff.
2. Send author designation records and resolve in each backend: rejected because it exposes authoring machinery, duplicates namespace/specificity semantics, and creates adapter-dependent outcomes.
3. Add a plan-wide open flag or infer openness from capability/payload absence: rejected because it loses concern identity, exact leaf precedence, constraints, closed omissions, and delegated origin.
4. Serialize CompiledRealizationRequirement: rejected because it is an internal demand graph, omits denial entries, carries unresolved delegation, and includes owning-contract details.
5. Chosen: project the canonical compiler/planner result into one mandatory, complete, value-safe plan-level resolved-authority collection.

Chosen architecture

• Add a closed typed resolved-authority contract beside provisioning operations. Each entry identifies address, semantic field path, realization domain/kind, canonical RFC 6901 operation-payload pointer, effective mode (closed/open/constrained/exact), governing scope, resolution source, and only publication-safe typed bounds/evidence requirements. Delegation is recorded as source and resolved to open or closed during planning.
• Compile a complete internal boundary for every registered concern, including legacy/scoped closed omissions, without changing the existing demand graph. Explicit leaves remain authoritative under broader open scopes.
• During planning, resolve apparatus defaults, bind safe constraint domains, project entries only for non-delete provisioning operations, and validate uniqueness, references, pointer ownership, mode/bound combinations, and registry-derived completeness. Missing, partial, unknown, cross-address, unsafe-bound, and stale-delete authority fail closed.
• Add one total plan lookup/validation helper used by submission, reference, libvirt, and runtime paths. Backend capability and envelope checks remain additional intersections and never synthesize permission.
• Make projection and reverse conversion lossless. Runtime disclosure, sanitization, and provenance consume the plan collection rather than an out-of-band requirements tuple; direct-manager and authenticated HTTP paths therefore enforce the same boundary and preserve the baseline snapshot on failure.
• Exact values remain in operation payloads. Artifact, apparatus/backend-private, credential, source, native-driver, and operational metadata remain on their existing owning contracts.

Documentation defense

Update the architecture record, SEM-218 formal phase/status and prior-art citations, and the implementer-facing realization reference. The docs will state the blocked assurance claim, exact loss points, chosen ownership, rejected carriers, value/secret boundary, limitations, adapter/APTL contract, and conformance gates. No changelog or version file will be edited.

Verification plan

Use mandatory TDD. Add focused issue-1067 tests first and observe failures for:

• root/scoped open and closed posture in both directions;
• exact/constrained leaves beneath open scopes;
• host, imported, and nested namespace ownership;
• delegated defaults resolved open/closed with source retained;
• unsupported openness and capability-not-permission;
• missing/duplicate/partial/unknown/cross-address/invalid-mode/unsafe-bound/stale-delete authority;
• projection, JSON/schema round-trip, reverse conversion, reference/libvirt lookup parity, direct manager and HTTP control-plane parity;
• closed-omission/excess-state rejection, envelope/domain rejection, provenance identity, snapshot sanitization, and baseline preservation.

Regenerate the published schema from its closed Pydantic authority, update valid/invalid fixtures and the publication entry hash/summary, and run focused pytest during red/green loops. Before completion run with RAES_REQUIREMENT_UID=SEM-218: implementations/python/.venv/bin/python tools/check_repo_policy.py, tools/check_requirement_governance.py, tools/verify_all.py, the configured completion gate, and make policy.

Implementation sequence

1. Write the compilation/planning/contract/runtime tests and confirm each fails for the missing boundary rather than fixture wiring.
2. Add the reusable contract enums/models, plan-level collection, total lookup, and fail-closed structural validators in raes_contracts.
3. Extend compiler/runtime-model metadata and planner materialization so closed omissions and delegation source survive while existing demands continue to drive capability/envelope admission.
4. Thread the collection through plan construction, projection, schema, fixtures, reverse control-plane conversion, submission diagnostics, reference/libvirt interpretation, and runtime disclosure/provenance.
5. Update public/formal docs and schema-publication metadata, repair the broken literature citations, then execute targeted and repository-wide gates.

Cross-cutting design checks

• Security: preserve closed parser/DTO models, canonical address and RFC 6901 validation, authenticated whole-plan submission, request-size/idempotency gates, value-free diagnostics, safe projections, secret redaction, pre-persistence backend-result validation, generic API errors, and zero argv/environment/libvirt/native-name exposure. Arbitrary secret-capable allowed-value sets are not publishable; an unrepresentable constrained boundary fails planning.
• Maintainability: reuse the resolver, explicitness records, concern registry, bounded-domain algebra, existing plan projectors/converters, diagnostics, and disclosure/sanitization code. No parallel resolver, path table, schema registry, exception family, logger, or persistence sidecar.
• Extensibility: a new concern extends RealizationConcernDescriptor; a new safe bound extends DomainDescriptor or its concern-owned typed contract; a new backend consumes the same total lookup and envelope/capability intersection.
• Whole repo: compiler, planner, contract models, generated schemas/fixtures/publication metadata, reference/libvirt backends, runtime manager/control plane/store, SEM-218 docs, governance checks, and external APTL consumption are in scope. Authoring syntax, envelope language, backend selection, resource-payload redesign, unrelated Express compute-node intent independently of backend virtualization mechanism #1076/Complete SEM-218 boundary coverage across RuntimeConfiguration #1078 semantics, and downstream APTL code are not changed.

[Brad-Edwards]

Execution obligation OBL-1067-LITERATURE-LINKS — Resolved

Category: quality
Observed state: SEM-218 no longer references the absent local research/research/primary/literature corpus.
Impact: The normative specification has verifiable literature citations and no broken repository-local evidence paths.
Current obligation: Replace missing local literature-corpus references with stable primary-source links.

Evidence

• rg finds no primary/literature reference in specs/formal/realization/explicitness-and-realization.md.
• The replaced citations resolve to stable primary OASIS, SigmaHQ, arXiv, JAIST handle, and SCITEPRESS publication pages.

Disposition: fix
Corrective action: Replaced every absent research/research/primary/literature path in the SEM-218 prior-art section with a stable primary-source publication link and removed the false local-corpus statement.

Verification

• rg -n 'research/research/primary/literature|primary/literature' specs/formal/realization/explicitness-and-realization.md returns no matches.
• Verified the replacement source locations against the publishers' or authors' primary publication surfaces.