operations capa

operations-e2e-contract

The E2E oracle: ONE typed source of truth for the data-test-id / semantic-field-path scheme, the FieldKind→control contract, and the expected-control manifest + role-policy interface that both the render engine and the E2E harness key off (sprint 0.79 P1)

The E2E oracle: ONE typed source of truth for the data-test-id / semantic-field-path scheme, the FieldKind→control contract, and the expected-control manifest + role-policy interface that both the render engine and the E2E harness key off (sprint 0.79 P1)

Tieroperations
Roleunclassified (baselined)
Pathcrates/operations/e2e-contract
Edition2021
Targetsoperations_e2e_contract
Public items75 across 6 modules
Tests36

What it is for

operations-e2e-contract — the E2E oracle: ONE typed source of truth for the contract the registry-driven E2E harness keys off (sprint 0.79, P1).

# Why this crate exists

The locked E2E design (sprint 0.79) engineers against three footguns, and all three trace back to more than one source of truth:

1. Oracle drift — the manifest, the role policy, the data-test-id grammar, and the FieldKind→control mapping must derive from ONE Rust source, or the harness looks exhaustive while validating an alternate universe. 2. No-op theater — proving a control was driven requires first mapping each rendered control deterministically to its definition; that mapping is the data-test-id scheme defined here. 3. Leaky test dependencies — if the harness linked the whole engine to read the oracle, every consumer would pull DB pools and network clients.

This crate is the resolution to all three: it is the thin contract that BOTH the render engine and the future harness depend on — never on each other. The engine emits (data-test-id, data-field-path, data-test-perm) constructed via these types; the harness parses the same types and builds its manifest::ExpectedControlManifest from them. Because both sides go through one grammar (round-trip tested) and one mapping, the oracle cannot drift, and neither side drags the engine into the other.

# What it defines

cms.field.{surface}.{entity}.{def}.{field_path}.{control}, as typed constructors + parsers (core::fmt::Display + core::str::FromStr, round-trip tested).

(blocks2.items0.title), likewise round-trippable.

FieldKind→control contract, with FieldKind::WIRE_FORMS as the drift guard the application-cms parity test asserts against.

PermissionSet interface the harness builds from registries + roles (discovery itself is P3). Includes the reference PermissionRolePolicy.

# Security posture

Parse-don't-validate throughout: every string the engine emits is reconstructed through a typed grammar whose fallible parses return typed errors (errors) — no `unwrap`/`panic` on a parse path — so a malformed id from a stale build is an attributable failure, not a harness-aborting panic. The manifest's required_permission is the truthfulness anchor: it must carry the REAL role gate (for CMS field controls, cms.pages.write), so denial-path coverage is trustworthy rather than a guess.

Capabilities

ControlKind

The FieldKind → control contract — the oracle for how each field kind

Item
pub enum ControlKind
ControlKind :: fn is_container(self) -> bool

FieldKind

The FieldKind → control contract — the oracle for how each field kind

Item
pub enum FieldKind
FieldKind :: fn control(self) -> ControlKind
FieldKind :: fn wire_form(self) -> & 'static str

FieldPathParseError

Typed parse errors for the E2E-contract scheme.

Item
pub enum FieldPathParseError
FieldPathParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

TestIdComponent

Typed parse errors for the E2E-contract scheme.

Item
pub enum TestIdComponent
TestIdComponent :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

TestIdParseError

Typed parse errors for the E2E-contract scheme.

Item
pub enum TestIdParseError
TestIdParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
TestIdParseError :: fn from(e : FieldPathParseError) -> Self

FieldPath

The semantic field path — a typed, parse-don't-validate model of where a

Item
pub struct FieldPath
FieldPath :: fn new(segments : impl IntoIterator <Item = FieldPathSegment>,) -> Result <Self, FieldPathParseError>
FieldPath :: fn single(segment : FieldPathSegment) -> Self
FieldPath :: fn child(& self, segment : FieldPathSegment) -> Self
FieldPath :: fn segments(& self) -> & FieldPathSegment
FieldPath :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
FieldPath :: fn from_str(s : & str) -> Result <Self, Self::Err>

FieldPathSegment

The semantic field path — a typed, parse-don't-validate model of where a

Item
pub struct FieldPathSegment
FieldPathSegment :: fn field(name : impl Into <String>) -> Self
FieldPathSegment :: fn indexed(name : impl Into <String>, index : usize) -> Self
FieldPathSegment :: fn at(mut self, index : usize) -> Self
FieldPathSegment :: fn name(& self) -> & str
FieldPathSegment :: fn indices(& self) -> & usize
FieldPathSegment :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
FieldPathSegment :: fn from_str(s : & str) -> Result <Self, Self::Err>

Entity

The canonical `data-test-id` scheme — the stable identifier the render

Item
pub enum Entity
Entity :: fn as_str(self) -> & 'static str
Entity :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

Surface

The canonical `data-test-id` scheme — the stable identifier the render

Item
pub enum Surface
Surface :: fn as_str(self) -> & 'static str
Surface :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

TestId

The canonical `data-test-id` scheme — the stable identifier the render

Item
pub struct TestId
TestId :: fn new(surface : Surface, entity : Entity, def : impl Into <String>, field_path : FieldPath, control : ControlKind,) -> Self
TestId :: fn surface(& self) -> Surface
TestId :: fn entity(& self) -> Entity
TestId :: fn def(& self) -> & str
TestId :: fn field_path(& self) -> & FieldPath
TestId :: fn control(& self) -> ControlKind
TestId :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
TestId :: fn from_str(s : & str) -> Result <Self, Self::Err>

Actor

The expected-control manifest + the role-policy interface — the types

Item
pub enum Actor
Actor :: fn role(slug : impl Into <String>) -> Self
Actor :: fn role_slug(& self) -> Option <& str>

ExpectedControl

The expected-control manifest + the role-policy interface — the types

Item
pub struct ExpectedControl
ExpectedControl :: fn new(test_id : TestId, required_permission : impl Into <String>) -> Self

ExpectedControlManifest

The expected-control manifest + the role-policy interface — the types

Item
pub struct ExpectedControlManifest
ExpectedControlManifest :: fn resolve <P : RolePolicy>(actor : Actor, controls : impl IntoIterator <Item = ExpectedControl>, policy : & P,) -> Self
ExpectedControlManifest :: fn present_ids(& self) -> impl Iterator <Item = & TestId>
ExpectedControlManifest :: fn absent_ids(& self) -> impl Iterator <Item = & TestId>

ManifestEntry

The expected-control manifest + the role-policy interface — the types

Item
pub struct ManifestEntry

PermissionRolePolicy

The expected-control manifest + the role-policy interface — the types

Item
pub struct PermissionRolePolicy<P : PermissionSet>

PermissionRolePolicy<P>

The expected-control manifest + the role-policy interface — the types

Item
PermissionRolePolicy<P> :: fn new(permissions : P) -> Self
PermissionRolePolicy<P> :: fn presence(& self, actor : & Actor, control : & ExpectedControl) -> Presence

PermissionSet

The expected-control manifest + the role-policy interface — the types

Item
pub trait PermissionSet

Presence

The expected-control manifest + the role-policy interface — the types

Item
pub enum Presence
Presence :: fn is_drivable(self) -> bool

RolePolicy

The expected-control manifest + the role-policy interface — the types

Item
pub trait RolePolicy

PartyControl

PartyTestId — sprint 3.72's data-test-id grammar for the party detail

Item
pub enum PartyControl
PartyControl :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

PartyTab

PartyTestId — sprint 3.72's data-test-id grammar for the party detail

Item
pub enum PartyTab
PartyTab :: fn as_str(self) -> & 'static str
PartyTab :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

PartyTestId

PartyTestId — sprint 3.72's data-test-id grammar for the party detail

Item
pub struct PartyTestId
PartyTestId :: fn new(tab : PartyTab, widget : impl Into <String>, control : PartyControl) -> Self
PartyTestId :: fn tab(& self) -> PartyTab
PartyTestId :: fn widget(& self) -> & str
PartyTestId :: fn control(& self) -> PartyControl
PartyTestId :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
PartyTestId :: fn from_str(s : & str) -> Result <Self, Self::Err>

PartyTestIdComponent

PartyTestId — sprint 3.72's data-test-id grammar for the party detail

Item
pub enum PartyTestIdComponent
PartyTestIdComponent :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

PartyTestIdParseError

PartyTestId — sprint 3.72's data-test-id grammar for the party detail

Item
pub enum PartyTestIdParseError
PartyTestIdParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

operations_e2e_contract

flowchart TD
  n_operations_e2e_contract["operations_e2e_contract"]
  n_operations_e2e_contract --> n_control["control"]
  n_operations_e2e_contract --> n_errors["errors"]
  n_operations_e2e_contract --> n_field_path["field_path"]
  n_operations_e2e_contract --> n_id["id"]
  n_operations_e2e_contract --> n_manifest["manifest"]
  n_operations_e2e_contract --> n_party["party"]

Public surface

`control`

ItemWhat it is
pub enum ControlKindThe kind of HTML control a field renders as — the vocabulary the harness uses to know how to drive and assert a control without per-control code
ControlKind :: fn is_container(self) -> boolWhether this control is a container (it holds child controls the harness must recurse into) rather than a leaf the harness drives directly
pub enum FieldKindA mirror of application_cms's FieldKind, kept here so the contract crate stays thin (see the module docs)
FieldKind :: fn control(self) -> ControlKindThe ControlKind this field kind renders as — the heart of the FieldKind→control contract
FieldKind :: fn wire_form(self) -> & 'static strThe serde wire string for this variant (the value emitted into the {control}-adjacent kind position and used in data-* attributes).

`errors`

ItemWhat it is
pub enum TestIdParseErrorA failure parsing a crate::TestId from its canonical string form
pub enum TestIdComponentWhich structural component of a crate::TestId was at fault — used by TestIdParseError::EmptySegment for precise diagnostics.
TestIdComponent :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
TestIdParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub enum FieldPathParseErrorA failure parsing a crate::FieldPath from its semantic string form (e.g
FieldPathParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
TestIdParseError :: fn from(e : FieldPathParseError) -> Self

`field_path`

ItemWhat it is
pub struct FieldPathSegmentOne .-separated step of a FieldPath: a field name plus zero or more array indices that index into it (outermost first)
FieldPathSegment :: fn field(name : impl Into <String>) -> SelfA scalar segment: a bare field name with no array indexing
FieldPathSegment :: fn indexed(name : impl Into <String>, index : usize) -> SelfAn indexed segment: a field name followed by a single array index (items0)
FieldPathSegment :: fn at(mut self, index : usize) -> SelfAppend a further array index to this segment (for the rare multi-index shape grid13)
FieldPathSegment :: fn name(& self) -> & strThe field name component.
FieldPathSegment :: fn indices(& self) -> & usizeThe array indices applied to this segment, outermost first.
FieldPathSegment :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub struct FieldPathA semantic path to a field inside a page's metadata tree (blocks2.items0.title)
FieldPath :: fn new(segments : impl IntoIterator <Item = FieldPathSegment>,) -> Result <Self, FieldPathParseError>Build a path from an ordered list of segments
FieldPath :: fn single(segment : FieldPathSegment) -> SelfA single-segment path from one segment (the common scalar-field case).
FieldPath :: fn child(& self, segment : FieldPathSegment) -> SelfReturn a new path with segment appended — used when the engine descends into a repeater row or block instance while rendering nested fields.
FieldPath :: fn segments(& self) -> & FieldPathSegmentThe ordered segments of this path (always non-empty).
FieldPath :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
FieldPathSegment :: fn from_str(s : & str) -> Result <Self, Self::Err>Parse one segment: a non-empty name followed by zero or more index
FieldPath :: fn from_str(s : & str) -> Result <Self, Self::Err>Parse a full path: one or more .-separated FieldPathSegments

`id`

ItemWhat it is
pub enum SurfaceWhere a CMS control is rendered — the {surface} component of a TestId
Surface :: fn as_str(self) -> & 'static strThe wire token for this surface (the {surface} segment text).
Surface :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub enum EntityThe kind of definition a field belongs to — the {entity} component
Entity :: fn as_str(self) -> & 'static strThe wire token for the {entity} segment.
Entity :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub struct TestIdThe canonical, parsed data-test-id for one CMS control
TestId :: fn new(surface : Surface, entity : Entity, def : impl Into <String>, field_path : FieldPath, control : ControlKind,) -> SelfBuild a test id from typed parts
TestId :: fn surface(& self) -> SurfaceThe surface this control is rendered on.
TestId :: fn entity(& self) -> EntityThe entity (registry) the field's definition belongs to.
TestId :: fn def(& self) -> & strThe definition key (template/block/widget key).
TestId :: fn field_path(& self) -> & FieldPathThe semantic field path within the page's metadata.
TestId :: fn control(& self) -> ControlKindThe control kind this field renders as.
TestId :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
TestId :: fn from_str(s : & str) -> Result <Self, Self::Err>Parse a canonical id back into its typed parts

`manifest`

ItemWhat it is
pub enum ActorAn actor whose view of the controls the harness verifies
Actor :: fn role(slug : impl Into <String>) -> SelfConvenience constructor for a role actor from any string-like slug.
Actor :: fn role_slug(& self) -> Option <& str>The role slug, or None for the anonymous actor.
pub enum PresenceWhether a control must be present, present-but-disabled, or absent for a given actor — the per-control verdict the harness asserts against the DOM
Presence :: fn is_drivable(self) -> boolWhether the actor is expected to be able to drive (mutate) this control
pub struct ExpectedControlOne expected control: the canonical TestId the engine should have emitted, the ControlKind it must render as, and the permission the real role gate requires to interact with it
ExpectedControl :: fn new(test_id : TestId, required_permission : impl Into <String>) -> SelfBuild an expected-control entry
pub struct ExpectedControlManifestThe set of controls expected on one surface+entity+definition, resolved for one actor — i.e
pub struct ManifestEntryOne entry of an ExpectedControlManifest: an ExpectedControl plus the Presence the RolePolicy resolved for the manifest's actor.
ExpectedControlManifest :: fn resolve <P : RolePolicy>(actor : Actor, controls : impl IntoIterator <Item = ExpectedControl>, policy : & P,) -> SelfResolve a manifest for actor by asking policy for each control's presence
ExpectedControlManifest :: fn present_ids(& self) -> impl Iterator <Item = & TestId>The ids the actor MUST be able to see and drive (presence == Present).
ExpectedControlManifest :: fn absent_ids(& self) -> impl Iterator <Item = & TestId>The ids the actor MUST NOT see (presence == Absent) — the denial set.
pub trait RolePolicyThe interface that supplies role policy to manifest resolution
pub trait PermissionSetSupplies the set of permissions an actor holds, so a policy can decide presence from permissions rather than hard-coding role→control rules
pub struct PermissionRolePolicy<P : PermissionSet>The reference RolePolicy: a control is Presence::Present iff the actor holds its required_permission, otherwise Presence::Absent
PermissionRolePolicy<P> :: fn new(permissions : P) -> SelfWrap a PermissionSet as the reference role policy.
PermissionRolePolicy<P> :: fn presence(& self, actor : & Actor, control : & ExpectedControl) -> Presence

`party`

ItemWhat it is
pub enum PartyTabWhich tab — or the persistent header chrome — a party-page control renders on: the {tab} component of a PartyTestId.
PartyTab :: fn as_str(self) -> & 'static strThe wire token for this tab (the {tab} segment text).
PartyTab :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub enum PartyControlThe kind of control a party-page data-test-id names: the {control} component of a PartyTestId.
PartyControl :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub enum PartyTestIdComponentWhich structural component of a PartyTestId was at fault — used by PartyTestIdParseError::EmptySegment for precise diagnostics.
PartyTestIdComponent :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub enum PartyTestIdParseErrorA failure parsing a PartyTestId from its canonical string form
PartyTestIdParseError :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
pub struct PartyTestIdThe canonical, parsed data-test-id for one party-page control
PartyTestId :: fn new(tab : PartyTab, widget : impl Into <String>, control : PartyControl) -> SelfBuild a party test id from typed parts
PartyTestId :: fn tab(& self) -> PartyTabWhich tab (or the header chrome) this control renders on.
PartyTestId :: fn widget(& self) -> & strThe free widget token.
PartyTestId :: fn control(& self) -> PartyControlThe control kind.
PartyTestId :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result
PartyTestId :: fn from_str(s : & str) -> Result <Self, Self::Err>Parse a canonical id back into its typed parts

Re-exports. Exported here, defined elsewhere.

ExportDefined in
{Actor,ExpectedControl,ExpectedControlManifest,ManifestEntry,PermissionRolePolicy,PermissionSet,Presence,RolePolicy,}manifest::{Actor,ExpectedControl,ExpectedControlManifest,ManifestEntry,PermissionRolePolicy,PermissionSet,Presence,RolePolicy,}
{ControlKind,FieldKind}control::{ControlKind,FieldKind}
{Entity,Surface,TestId}id::{Entity,Surface,TestId}
{FieldPath,FieldPathSegment}field_path::{FieldPath,FieldPathSegment}
{FieldPathParseError,TestIdComponent,TestIdParseError}errors::{FieldPathParseError,TestIdComponent,TestIdParseError}
{PartyControl,PartyTab,PartyTestId,PartyTestIdComponent,PartyTestIdParseError}party::{PartyControl,PartyTab,PartyTestId,PartyTestIdComponent,PartyTestIdParseError}

Boundary

Depends on no other workspace tier.

Shares tier operations with 40 other crates: operations-approval-workflow, operations-assessments, operations-block-imaging, operations-boot-media, operations-browser-agent-worker, operations-camera-discovery, operations-camera-liveview, operations-camera-registry, … (40 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)operations
Architectural role (taxonomy)unclassified (baselined)
Locationcrates/operations/e2e-contract
Vocabulary in force (lexicon)current

Dependencies

Runtime, from outside the workspace.

CrateRequirementFeaturesOptionalOnly on
serde^1derivenoalways

Development. None.

Build. None.

Depended on by. 3 workspace crates.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_application_cms["application-cms"] -->|uses| SELF
  n_operations_e2e_harness["operations-e2e-harness"] -->|uses| SELF
  n_platform_staff_ui["platform-staff-ui"] -->|uses| SELF
  SELF["operations-e2e-contract"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

KindNameSource
liboperations_e2e_contract`src/lib.rs`

Error model

Error typeNamed by
FieldPathParseErrordeclared, no public signature returns it
PartyTestIdParseErrordeclared, no public signature returns it
TestIdParseErrorPartyTestIdParseError

Operational characteristics

PropertyEvidence
async public surfacenone detected
async runtimenone detected
database accessnone detected
network I/Onone detected
unsafe codenone detected
environment variablesnone detected

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

3 workspace crates depend on this one: application-cms, operations-e2e-harness, platform-staff-ui.

Verification

KindCount
Unit tests36
Integration tests0
Examples0
Doctests0

Evidence by module. How often each public module is named by something executable.

ModuleTestsExamplesConsumers
control205
errors300
field_path204
id307
manifest808
party503

What the tests establish, by name:

Documentation coverage

MeasureDocumentedTotal
Public items with rustdoc6075
Public modules with a //! block66
pie showData
    title Public items with rustdoc
    "Documented" : 60
    "No rustdoc detected" : 15

Metrics

MetricValue
Rust source files7
Source lines2057
Code lines1270
Public API items75
Public modules6
Tests36
Examples0
Cargo features0
Direct runtime dependencies1
Workspace reverse dependencies3
pie showData
    title Public API by kind
    "enum" : 13
    "method" : 52
    "struct" : 8
    "trait" : 2
pie showData
    title Rust source composition
    "Code" : 1270
    "Blank or comment" : 787

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

Todas las operations · Manual