Skip to content

INTEROPERABILITY_SPEC.md

Latest commit

 

History

History
391 lines (296 loc) · 15.9 KB

INTEROPERABILITY_SPEC.md

File metadata and controls

391 lines (296 loc) · 15.9 KB
Raw

SecureToolKit Interoperability Specification

1. Meaning of interoperability

SecureToolKit interoperability means that independent implementations execute the same accepted protocol semantics over the same language-neutral fixture corpus and produce identical semantic observations.

It does not mean that in-memory objects, ABI, source APIs, exception types, hash-table iteration, object layout, private constructors, pointer identities, or performance measurements are identical. It does not define a production wire format or permit artifacts to cross process or trust boundaries.

For Phase 7 v1, protocol compatibility is proven only when Swift, Rust, and .NET all pass the complete required corpus and every pair produces an identical semantic projection for every fixture.

2. Required independence

The three implementations MUST be independently owned codebases. They MAY share the official fixture corpus, specification text, and accepted reference results. They MUST NOT share protocol implementation source, generated production model types, opaque boundary instances, or one implementation's serialized controlled artifacts.

An adapter MAY be generated from the fixture schema, but generation MUST NOT generate the implementation's protocol logic or expected result. An implementation MUST NOT call another implementation to obtain a result.

The same team MAY operate the runners. Organizational independence is desirable but is not itself a semantic requirement; code-path independence is required.

3. Adapter boundary

Each implementation supplies one conformance adapter. The adapter has exactly these semantic responsibilities:

  1. validate that it supports the fixture and profile versions;
  2. map the language-neutral typed fixture tree to native untrusted drafts, explicit Host inputs, controlled construction paths, and independent Validation expectations;
  3. invoke exactly one named transition;
  4. observe the complete native result without mutation;
  5. map the observation back to the neutral typed tree and stable-failure record;
  6. expose no raw pointer, runtime hash, process address, stack trace, or language-specific error text; and
  7. report unsupported or incomplete mapping honestly.

The adapter MUST NOT:

  • repair malformed input;
  • normalize values unless the protocol transition requires normalization;
  • substitute a different version or transition;
  • construct controlled artifacts through test-only or unchecked paths for a positive case;
  • copy Validation expectations from the artifact under validation;
  • infer authority, response, time, or missing state;
  • retry after failure;
  • consume, execute, persist, network, or call a model; or
  • compare against the Expected Result before invoking the implementation.

A malformed-fixture harness may create otherwise unrepresentable negative input only through test linkage. It MUST remain unreachable from production linkage and MUST NOT manufacture a positive controlled artifact.

4. Native type mapping

Every adapter MUST publish a mapping table from each neutral type label to one native semantic type. The table identifies:

  • the native type or closed variant;
  • whether input is untrusted, Host-controlled, or a controlled artifact;
  • the permitted constructor transition;
  • exact field correspondence;
  • set, tuple, list, optional, and record behavior;
  • integer and explicit-time domain;
  • stable-failure mapping; and
  • native access-control mechanism.

Native names are non-normative. Multiple neutral types MUST NOT be collapsed when the contract defines distinct typed version, identifier, role, evidence, or artifact families, even if their stored scalar representation is identical.

In particular, every typed v1 family remains distinguishable. Passing a Challenge version where an Artifact version is expected MUST reject in all three implementations.

5. Opaque Host-domain mapping

Opaque Host Capability Boundary identity cannot be compared by raw bytes across processes or languages. Fixtures therefore use symbolic boundary slots such as domain-a and domain-b.

For each fixture, an adapter MUST:

  1. create one genuine native opaque boundary for each distinct slot;
  2. map every repeated occurrence of one slot to the same native boundary instance or exact native domain identity;
  3. map different slots to independently created boundaries even when all descriptive fields are equal;
  4. retain the native boundary independently of artifacts; and
  5. export only the symbolic slot in the neutral observation.

Role Authorities and Host-controlled evidence use the same slot relationship. The comparator checks equality and inequality relationships among slots, not pointer values or native descriptions.

An adapter that reconstructs a boundary from artifact content is non-conforming.

6. Controlled-construction mapping

Fixture input distinguishes these source classes:

untrusted
hostInput
controlledPredecessor
independentExpectation
malformedTestOnly

The source class is test metadata and does not enter protocol values. Adapters MUST route each node through the matching native construction boundary.

  • untrusted enters only validation or draft parsing.
  • hostInput enters an authorized Host path with genuine retained authority.
  • controlledPredecessor must be produced by an earlier controlled transition in fixture setup, not memberwise construction.
  • independentExpectation must be retained separately before the artifact is supplied to Validation.
  • malformedTestOnly is available only to negative fixtures through the isolated harness.

The setup trace is part of adapter evidence. A result obtained through an incorrect source class is invalid even if its field values match.

7. Semantic projection

Cross-language comparison uses the following exact projection from each Fixture Result:

  1. fixtureID;
  2. fixtureDigest;
  3. status;
  4. reason;
  5. Expected Result;
  6. Actual Observation executionState;
  7. Actual Observation outcome;
  8. artifactType and complete artifact typed tree;
  9. exact Stable Failure;
  10. equality relation;
  11. ordered values;
  12. boundary position;
  13. determinism;
  14. side-effect state; and
  15. repeatCountExecuted.

Implementation, environment, runner, duration, resident memory, report ID, report digest, result digest, and allowed diagnostic tokens are excluded from semantic equality. They remain required report evidence.

Two projections are identical only when every included typed value is exactly equal after component resolution and symbolic boundary mapping. Missing values, additional values, alternative error categories, and semantically similar outputs are mismatches.

8. Exact comparison rules

8.1 Records and variants

Record equality compares the exact language-neutral type and every declared field. Field declaration or memory order is ignored after controlled construction. Missing, additional, or duplicated fields in a result are a mismatch.

Closed variants compare family and token. A same-spelling token from another family is not equal.

8.2 Identifiers, strings, integers, times, and bytes

  • identifiers and strings compare exact ASCII octets;
  • signed and unsigned integers compare exact domain and mathematical value;
  • explicit times compare exact epoch-second value;
  • Booleans compare exact value; and
  • bytes compare exact octets.

No trimming, case folding, Unicode normalization, numeric coercion, or time-zone conversion is permitted.

8.3 Sets, tuples, and lists

  • controlled sets compare exact unique normalized member sequence;
  • malformed raw set input preserves occurrences for rejection tests;
  • tuples and protocol-ordered lists compare exact order and duplicates; and
  • non-authoritative native iteration order is never exported.

8.4 Complete equality

Same identifiers, same canonicalization-v1 bytes, same policy outcome, same scope size, or display equivalence never replace complete equality. Mutations inside imported frozen components remain visible through component digest and resolved typed structure.

8.5 Failures

Failures compare exact stable reason, exact safe field or absence, and exact public limit or absence. Language exception types and messages are ignored and MUST NOT appear in the projection.

8.6 Ordering and precedence

The comparator verifies normalized ordering and first-failure precedence against the fixture. If two implementations reject the same fixture for different stable reasons, they are incompatible even when both fail closed.

9. Canonicalization-v1 comparison

Frozen canonicalization-v1 fixtures are the only cases requiring exact byte output equality. Swift, Rust, and .NET MUST reproduce every accepted positive vector byte-for-byte and reject every negative vector.

Phase 7 artifacts have no canonical bytes or wire format. The Conformance JSON typed tree MUST NOT be confused with canonicalization v1 or used as production serialization.

10. Cross-language execution matrix

For one official comparison, the Board requires these runs:

Run Corpus Profile Requirement
Swift semantic Exact corpus digest p1-6-v1, p7-v1 Every active semantic fixture
Rust semantic Same digest p1-6-v1, p7-v1 Same fixture IDs
.NET semantic Same digest p1-6-v1, p7-v1 Same fixture IDs
Swift performance Same digest and reference environment Both profiles Every active performance fixture
Rust performance Same digest and environment Both profiles Same fixture IDs
.NET performance Same digest and environment Both profiles Same fixture IDs

Semantic runs MAY occur on different supported operating systems or architectures because semantic projection excludes environment-specific data. Performance differential evidence requires the same physical or equivalently provisioned environment and identical runner limits. Timing ratios are informational; each implementation independently must remain within the fixed budget.

11. Pairwise and tri-language proof

The comparator evaluates these pairs in this exact order:

swift-rust
swift-dotnet
rust-dotnet

For every active fixture:

  1. all three fixture and corpus digests MUST match;
  2. all three results MUST be present;
  3. all three statuses MUST be PASS;
  4. each pair's semantic projection MUST be identical; and
  5. no report may contain a skipped, unsupported, incomplete, failed, or omitted mandatory fixture.

Pairwise identity is necessary but not sufficient when the third implementation is unavailable. Official tri-language compatibility requires all three pairs for all required fixtures.

12. Reference-result use

Each implementation first compares to the Board-approved Reference Result. It then participates in pairwise comparison. Reference equality cannot excuse a pairwise mismatch, and pairwise agreement cannot override a Reference Result.

If all implementations disagree with one Reference Result in the same way, the fixture is quarantined for protocol-owner review. Implementations MUST NOT silently change expected output. The active corpus cannot claim completion until the discrepancy is resolved through a new accepted fixture revision or governing erratum.

No implementation is designated semantically privileged. Swift is the frozen reference implementation for Phase 1–6 history, but its output does not override the accepted language-independent contract.

13. Version compatibility proof

Each implementation publishes a Version Support record containing every semantic and representation version family and the exact supported values.

Compatibility requires:

  • exact v1 support for every family required by the claimed profile;
  • identical rejection for absent, zero, malformed, future, and cross-family values;
  • no version negotiation, latest selection, fallback, upgrade, or downgrade;
  • correct separation of Phase 6 and Phase 7 Authorization; and
  • identical UNSUPPORTED_VERSION reporting when a profile is truthfully not claimed.

An implementation that claims p7-v1 but lacks any required v1 family is INCOMPLETE_IMPLEMENTATION, not an interoperable subset.

14. Regression compatibility proof

Every historical and Phase 7 regression fixture is mandatory. Compatibility reports MUST retain fixture IDs across suite releases. A result that changes after implementation refactoring is a regression unless an accepted corpus revision and governing decision explain the change.

The comparator MUST separately report regression totals so a new positive fixture cannot hide a lost security repair.

15. Nondeterminism detection

Fixtures with repeatCount > 1 run from equivalent fresh input state. The adapter exports every observation. The runner compares all repeats before emitting the final Actual Observation.

Differences in outcome, stable failure, controlled fields, normalized ordering, or equality are FAIL/nondeterministic. Timing and memory variation do not constitute semantic nondeterminism.

Parallel runner execution MUST reproduce the same Fixture Result sequence and semantic projections as serial ASCII-ID execution. Otherwise the runner or implementation is not acceptable for official comparison.

16. Performance comparison

Performance compatibility means only that every implementation completes within the fixture's absolute sanity budget. Identical duration, allocation pattern, thread count, or speed is not required.

The comparison report MAY include ratios for the same environment. A ratio does not affect semantic compatibility and MUST NOT be used to relax an absolute budget. Performance tuning is outside this specification.

17. Partial, unavailable, and failed implementations

  • A missing adapter mapping is INCOMPLETE_IMPLEMENTATION.
  • A missing required version in a claimed profile is INCOMPLETE_IMPLEMENTATION.
  • A wholly unclaimed profile is UNSUPPORTED_VERSION.
  • An operator or environment exclusion is SKIPPED.
  • A semantic mismatch, timeout, crash, leak, side effect, or nondeterminism is FAIL.

These statuses are useful evidence but never compatibility success. Results MUST remain in the report and aggregate according to the report specification.

18. Compatibility evidence bundle

An official interoperability evidence bundle contains exactly:

  1. the canonical suite manifest and corpus digest;
  2. governing-artifact identities and hashes;
  3. one complete Swift conformance report;
  4. one complete Rust conformance report;
  5. one complete .NET conformance report;
  6. one complete Cross-Language Comparison record;
  7. each adapter's native type and constructor mapping;
  8. constructor-reachability and independent-expectation evidence;
  9. invariant, field, transition, boundary, version, and regression traceability;
  10. environment and runner records; and
  11. privacy and prohibited-side-effect review results.

Every file is listed by path, byte count, and SHA-256 in an evidence manifest. Checksums establish reproducibility only. This specification defines no signature, trust anchor, attestation, or certification authority.

19. Protocol compatibility decision

Independent implementations prove Phase 7 v1 protocol compatibility only when:

  • every implementation's report is structurally valid and overall PASS;
  • each selected set equals the complete active mandatory fixture set;
  • every semantic projection is identical across all three pairs;
  • every canonicalization-v1 byte vector matches;
  • every stable failure, ordering, equality, boundary, invariant, and regression behavior matches;
  • no required fixture is unavailable, unsupported, incomplete, skipped, or failed; and
  • the evidence bundle is complete and references one exact corpus digest.

This decision establishes semantic interoperability only. Production remains NO-GO until all frozen production prerequisites are implemented and approved.