Skip to content

11 Technical Risks

Alex Flom edited this page May 4, 2026 · 20 revisions

Risks and Technical Debts

This chapter enumerates known risks and technical debts in Prism’s architecture and in conforming implementations. An entry listed here is a structural property an implementation must navigate; it is not implementation discretion. Every entry has a name, a description, an architectural impact, and a mitigation posture.

The risks are not exhaustive. Operational risks (build pipeline failures, CI infrastructure outages, dependency supply-chain compromise) are out of scope; this chapter covers risks intrinsic to Prism’s architecture as specified in this wiki.

TR-01 — generic_const_exprs incompleteness on Rust nightly

Description: uor-foundation’s internal proc-macro sub-crate enables `#![feature(generic_const_exprs)] because the shape proc-macros (product_shape!, coproduct_shape!, cartesian_product_shape!) emit ConstrainedTypeShape impls that reference <H as HostBounds>::CAP at array-size positions. The feature is incomplete in Rust nightly and has been so for an extended period; specific complex const-expression patterns can fail to type-check or fail to monomorphize even when the pattern is logically well-formed. The macros are reached by application-author code through `prism’s vocabulary re-exports of `uor-foundation’s internal proc-macro sub-crate.

Architectural impact: An application author who writes a ConstrainedTypeShape declaration that exercises a const-expression pattern the compiler cannot yet resolve will see a compilation error that does not point at a UORassembly violation but at a toolchain limitation. This blurs the diagnostic distinction QS-04 specifies: the author cannot tell from the error whether the contract is violated or the toolchain is incomplete.

Mitigation posture: The shape proc-macros emit const-expression patterns the toolchain handles correctly today. The set of expressible shapes is bounded by what the toolchain supports; new shape variants prism might want to expose are gated both by uor-foundation’s proc-macro emissions (where the feature opt-in lives) and by toolchain progress. The wiki’s UORassembly contract (section 8) is specified independently of the toolchain’s current feature implementation; if a future Rust release stabilizes `generic_const_exprs or removes its incompleteness, the contract does not change. The risk is therefore one of time-bounded toolchain quality, not of architectural drift.

TR-02 — Gauge-level fixity at compile time

Description: Prism’s substitution axes are fixed at the application author’s compile time. An author cannot change the HostTypes, HostBounds, or Hasher selection at runtime; nor can they support multiple selections in a single executable without pre-compiling each variant separately. This is a direct consequence of constraint TC-01 (zero-cost runtime) and ADR-007 (substitution-axis allocation).

Architectural impact: An application that needs to operate against multiple substitution-axis configurations — for example, a service that accepts inputs hashed under SHA-256 from some clients and BLAKE3 from others — cannot be a single Prism executable. It must be either multiple executables or a non-Prism executable that delegates to Prism executables per-input.

Mitigation posture: This is a deliberate architectural property, not a defect. The mitigation, if an application’s domain requires multi-substrate operation, is at the application architecture level: compose multiple Prism executables, or use a meta-tool that selects among them. The wiki does not specify the meta-tool.

TR-03 — Host-platform feature-flag combinatorics

Description: All three crates — uor-foundation, prism, and prism-verify — expose feature flags alloc, std, serde, observability (section 8). prism’s flags are consistent with `uor-foundation’s (additive across the dependency graph). The author selects feature flags as part of their crate’s `Cargo.toml. Feature combinations now interact across two crate boundaries: a crate that depends on prism with alloc enabled and on a third-party crate that depends on uor-foundation (or another prism consumer) with std enabled triggers Cargo’s feature-unification, producing a build with both features active in both prism and uor-foundation. The unified build’s behavior is normatively specified — feature flags are additive (section 8) — but the compile-time and binary-size consequences vary across combinations and span both crates.

Architectural impact: An author whose crate composes with other crates that depend on prism or uor-foundation may not have full control over which features are active at build time. The author’s intended #![no_std] posture, for example, may be silently overridden if any transitive dependency enables std on either crate. The combinatoric space is now the cross-product of features at the uor-foundation and prism boundaries; with prism-verify participating in some dependency graphs, the cross-product extends to three boundaries.

Mitigation posture: Authors who require a specific feature posture can pin their dependency on prism (and indirectly uor-foundation) to a build profile that disables default features and explicitly enables only the flags they require (default-features = false plus an explicit features = […​] list, in Cargo.toml, for each Prism crate the author depends on). Cargo’s feature-unification still operates, so a transitive enabler of std will still cause std to be enabled, but this is detectable through cargo tree and similar inspection. The wiki specifies the additive property of features; the application author’s responsibility is to manage the feature graph across all three Prism crates for their crate’s intended deployment.

TR-04 — Distribution channel selection is out of architectural scope

Description: Prism is silent on the distribution channel by which the executable reaches the user (ADR-004). This is an architectural property — Prism’s specification does not constrain the channel — but it is also a risk: the absence of a normative channel means the channel’s properties (integrity, authenticity, availability) are application-author concerns that the architecture does not address.

Architectural impact: A compromised distribution channel can deliver a different executable than the author published. The user’s verification of an output (Scenario 2) confirms the output’s claims given the trace; it does not confirm the executable that produced the trace was the one the author intended. These are orthogonal properties; Scenario 4 in section 6 calls this out explicitly.

Mitigation posture: Application authors who require executable-authenticity guarantees adopt a supply-chain integrity mechanism out-of-band: code signing, content-addressable distribution (e.g., signed Git tags, content-addressed package registries, blockchain-anchored references), reproducible builds, attested build pipelines. Prism does not specify any of these; the application author selects whichever mechanism their threat model requires. The wiki acknowledges the orthogonality; conforming implementations are not responsible for solving it.

TR-05 — Hasher selection mismatch produces verification failure indistinguishable from data corruption

Description: The verifier rejects a trace with ReplayError::HasherMismatch if the supplied hasher_instance’s identifier does not match the trace’s `hasher_identifier. The user, faced with this error, cannot distinguish from the error alone whether: (a) they have the wrong Hasher instantiated; (b) the trace was produced with a Hasher whose identifier conflicts with another Hasher in the wider ecosystem; (c) the trace was tampered with to alter the identifier.

Architectural impact: Diagnosing why a verification fails is harder for the user than diagnosing why an execution fails. The execution’s error model (section 8) returns typed impossibility witnesses with positional information; the verification’s error model returns identifier-level errors that do not localize within the trace.

Mitigation posture: The application author’s documentation should communicate the Hasher identifier alongside any distributed traces, in a form that is not itself the trace (e.g., human-readable text the user can confirm matches what their verification environment expects). Prism’s wiki does not specify this communication format; it is the application author’s responsibility. The risk is that an author who skips this step leaves users unable to diagnose verification failures.

TR-06 — Trace format evolution requires version coordination

Description: The trace wire format carries a format_version field equal to TRACE_REPLAY_FORMAT_VERSION. The verifier rejects traces whose format version it does not recognize (section 8). If the wiki’s normative specification of the trace format is revised in a future revision of this wiki, the resulting format will have a different version number; existing traces will not be verifiable by the new verifier and new traces will not be verifiable by old verifiers. The format is defined in uor-foundation (data definitions in bridge); produced by prism’s pipeline; consumed by `prism-verify (façade) re-exporting prism’s replay implementation. Format-version evolution therefore spans two repositories (`UOR-Foundation/UOR-Framework for uor-foundation; UOR-Foundation/Prism for prism and prism-verify).

Architectural impact: Verification is bound to the trace format version, not just the trace content. Long-lived traces — produced today, verified years from now — require the verifier in use at verification time to recognize the format version the trace was produced with. Cross-repo coordination is now required for any format-version bump: uor-foundation is amended first (the data definitions change), then prism is repinned against the new uor-foundation and amended for the new producer/consumer paths, then prism-verify follows automatically as a thin façade.

Mitigation posture: The wire format’s length-prefix-on-events discipline (section 8) provides forward compatibility for trace producers: a future format version may add new event payload data without breaking old verifiers, provided the variant discriminants remain unchanged. Larger format changes — adding new variant discriminants, changing the top-level structure — are normative architectural changes that require their own ADR and a version bump. Conforming implementations preserve old format versions' verification capability when bumping the format version, so that traces produced under any historic format remain verifiable. The cross-repo coordination is sequenced: uor-foundation release → prism repin and release → prism-verify follows; any out-of-order release produces a prism build failure (the foundation-side UORassembly check, per ADR-006) and is detected at compile time.

TR-07 — Compile-time content-address stability across toolchain versions

Description: The ContentFingerprint carried by a Certified<GroundingCertificate> is computed by the author’s selected Hasher over data produced by pipeline::run. The data the hasher receives includes the trace’s TraceEvent sequence; the byte representation of the events is stable per the wire format specification (section 8). However, if a future Rust toolchain version changes the layout of intermediate values that contribute to a TraceEvent payload — for instance, if a new toolchain version’s Rust ABI changes the layout of an enum the foundation uses internally — the resulting trace bytes could differ for the same input.

Architectural impact: Bit-identical reproducibility of Grounded<T> and Trace values across toolchain versions is not normatively guaranteed by the wiki. Two builds of the same author’s crate against different toolchain versions could produce traces that verify against the same Hasher but produce different ContentFingerprint values, because the input bytes the Hasher saw were different.

Mitigation posture: The wire format specification (section 8) defines the byte layout of TraceEvent payloads independently of any toolchain version. Conforming implementations of uor-foundation SHOULD produce identical trace bytes across toolchain versions for identical inputs; this is not a normative MUST because it depends on toolchain ABI stability the foundation does not control. Application authors who require cross-toolchain reproducibility pin a specific toolchain version in their crate’s rust-toolchain.toml.

TR-08 — Vocabulary insufficiency in uor-foundation forces cross-repo amendment cadence

Description: prism is closed under uor-foundation’s vocabulary (ADR-013): every type `prism exposes is derived from uor-foundation’s type-declaration vocabulary; every operation declaration composes `uor-foundation::PrimitiveOp discriminants. Consequently, a prism amendment that needs a new primitive type (a domain shape uor-foundation’s vocabulary cannot express) or a new `PrimitiveOp discriminant cannot proceed without first amending uor-foundation. The two crates live in separate repositories (UOR-Foundation/UOR-Framework for uor-foundation; UOR-Foundation/Prism for prism and prism-verify) per ADR-015.

Architectural impact: When prism needs to expand its surface in a way that requires substrate amendment, the amendment cadence is sequenced: identify the substrate gap; amend uor-foundation; release uor-foundation; repin prism; amend prism; release prism. Each step is a cross-repo coordination point. The window between the uor-foundation release and the prism release is one in which prism consumers see a uor-foundation whose vocabulary is wider than what prism exposes; this is benign (the wider vocabulary is just unused in `prism’s surface) but is observable.

Mitigation posture: The substrate is designed to be wide enough that most prism amendments are additive — they expose a new combination of existing uor-foundation vocabulary, not a new primitive. The closure property in ADR-013 is the architectural commitment that makes this possible; if prism ever needs to introduce a primitive of its own, that is the signal that the substrate’s vocabulary is insufficient and the proper amendment site is uor-foundation. Substrate stability is the architectural goal; cross-repo coordination is the cost of the substrate being a separate, slower-moving layer.

TR-09 — prism version pin lag against uor-foundation

Description: Per the cross-repo split (ADR-015), prism pins a specific uor-foundation version in its Cargo.toml. When uor-foundation releases a new version (e.g., to add a new primitive per TR-08, or to fix a substrate-level bug), prism does not automatically pick up the new version — the prism repository must be amended to repin against the new release. There may be a window in which the latest uor-foundation release contains an amendment that prism does not yet pick up.

Architectural impact: Application authors who require a uor-foundation amendment that has been released but not yet picked up by prism must wait for the prism repin. Cargo’s feature-unification will not silently bridge this gap: the author depends on prism, which pins uor-foundation@X.Y.Z; a new uor-foundation@X.Y.Z+1 is unreachable from the author’s crate until prism repins. The author cannot work around this by declaring their own uor-foundation@X.Y.Z+1 dependency, because Cargo will reject the version conflict.

Mitigation posture: prism’s release cadence is expected to follow `uor-foundation’s closely for substrate-driven amendments (per TR-08). For substrate-level bug fixes, the `prism repository’s CI should track uor-foundation releases and produce a repin PR within a short window. The architectural commitment is that prism follows uor-foundation; the operational discipline is that the follow happens promptly. A prism release that lags uor-foundation by a substantial period is an operational concern, not an architectural one, but it surfaces as the practical bottleneck for application authors awaiting substrate amendments.

Clone this wiki locally