SWT3 Design Rationale

1. Cryptographic Choices

Why SHA-256?

• FIPS 140-2 validated. Required for federal and defense adoption. Any protocol targeting GovCon, FedRAMP, or CMMC must use FIPS-approved algorithms. SHA-256 is approved under FIPS 180-4.
• Universal availability. SHA-256 is in the standard library of every major language: Python hashlib, Node.js crypto, Rust sha2, C# System.Security.Cryptography, Ruby OpenSSL, Go crypto/sha256, Java MessageDigest. No external dependency required in any language.
• Hardware acceleration. Modern x86 CPUs include the SHA-NI instruction set, making SHA-256 computation effectively free in terms of latency overhead.

Why 12 hex characters (48 bits) for fingerprint truncation?

• Collision resistance. 48 bits gives a birthday paradox threshold of approximately 2²⁴ (~16.7 million) anchors before a 50% collision probability. A typical compliance ledger produces tens of thousands of anchors per tenant per year. Even at 100,000 anchors/year for 100 years, the collision probability remains negligible.
• Human readability. 12 characters fit in a terminal column, a spreadsheet cell, and a printed assessment report without wrapping. Assessors compare fingerprints visually during site visits.
• Anchor token length. The full anchor (SWT3-E-AWS-AI-AIINF1-PASS-1774800000-c059eb5938c0) is already 50+ characters. A 64-character fingerprint would push it past 100 characters, breaking copy-paste usability.

Why HMAC-SHA256 for payload signing?

• Symmetric key simplicity. No PKI infrastructure, no certificate rotation, no revocation checking. The signing key is shared between the agent and the witness endpoint. This matches the trust model: the agent and the platform already share an API key.
• Same primitive. SHA-256 is already required for fingerprinting. HMAC-SHA256 adds no new cryptographic dependency.
• FIPS 198-1 validated. HMAC is a FIPS-approved construction.

2. Formula Design

Why the WITNESS: domain separator prefix?

• Cross-protocol collision prevention. Without a domain separator, a SHA-256 hash of unrelated data could accidentally match a valid SWT3 fingerprint. The WITNESS: prefix makes this effectively impossible.
• Unambiguous legacy detection. Pre-v1.1.0 anchors were minted without the prefix. Verifiers try the canonical formula first; if verification fails, they fall back to the legacy formula. The prefix is the disambiguation signal.
• Standard practice. Domain separation is a well-established pattern in cryptographic protocols. TLS, HKDF, and Merkle trees all use domain separators to prevent cross-context hash collisions.

Why colon-separated plaintext?

• Deterministic. The bytes of a colon-separated UTF-8 string are identical in every language and on every platform. No ambiguity.
• No serialization dependency. Constructing the input requires only string concatenation. No JSON library, no protobuf compiler, no binary encoder.
• Debuggable. A developer can construct the input by hand and verify with echo -n "WITNESS:..." | sha256sum | cut -c1-12. This is the single most important property for developer trust.

Why millisecond precision?

• Collision prevention. Two observations in the same second with identical factors would produce identical fingerprints if the timestamp used seconds. Millisecond precision makes same-second collisions extremely unlikely.
• Universal availability. Millisecond timestamps are reliably available on every platform including browsers, embedded systems, and air-gapped environments. Microseconds and nanoseconds are not available on all platforms (notably, some JavaScript runtimes truncate to milliseconds for privacy reasons).
• Dual representation. The anchor token uses epoch seconds (human-readable: 10 digits). The fingerprint uses milliseconds (cryptographic precision: 13 digits). This separation serves both audiences without compromise.

Why integer-valued floats stringify as integers?

• JSON number identity. In JSON, 1 and 1.0 are the same number. But str(1.0) in Python produces "1.0", while String(1.0) in JavaScript produces "1". Without the canonical rule, the same factors would produce different fingerprints in Python vs. JavaScript.
• The rule eliminates divergence. By requiring integer-valued floats to format as integers, all 5 SDK languages (Python, TypeScript, Rust, C#, Ruby) produce identical fingerprint input strings. This is verified by 13 shared test vectors.

3. Factor Architecture

Why exactly three factors?

• Minimum viable evidence triple. Three factors cover every compliance check pattern observed in practice:
  • Threshold comparison: "expected X, observed Y, delta Z"
  • Presence check: "required 1, found 1, delta 0"
  • Count verification: "minimum 3 guardrails, 4 active, all passed"
• Fixed-width fingerprint input. The number of factors is part of the fingerprint formula. Adding or removing factors changes the formula, breaking all existing anchors. Three is the design point; it cannot change.
• Storage efficiency. Three numeric fields fit in a single database row, a single JSON object, and a single log line. No nested structures required.

Why integer representation?

• Deterministic stringification. The integer 42 has exactly one string representation in every programming language: "42". Floating-point numbers do not have this property (IEEE 754 edge cases, locale-dependent formatting).
• Natural fit. Real-world compliance factors are naturally integer: open port counts, milliseconds of latency, token counts, guardrail counts, boolean flags (0/1).
• Fractional values via scaling. A 95.0% accuracy score is represented as 950 (per mille). This avoids floating-point entirely while preserving precision.

4. Clearing Protocol

Why exactly four levels?

• Maps to existing classification tiers. Regulated industries already operate with tiered data handling:
  • Level 0 (Retain): Unclassified / internal analytics. Full forensic capability.
  • Level 1 (Factor-Only): Standard production. Raw evidence purged, factors retained. RECOMMENDED default.
  • Level 2 (Anchor-Only): Sensitive / PII / healthcare. Factors purged after fingerprinting. Satisfies HIPAA minimum necessary.
  • Level 3 (Sovereign): Classified / defense / air-gapped. Nothing persists on the minting system. Satisfies ITAR and national sovereignty mandates.
• Discrete, not continuous. Clearing is an auditable commitment, not a configuration slider. An auditor can verify: "this system operates at Level 2." A continuous scale would require defining what 63% clearing means.

Why irreversibility as a hard requirement?

• The value proposition depends on it. SWT3's clearing guarantee is: "the data is gone, and the proof that it was correct survives." If clearing is reversible, the guarantee is hollow.
• Regulatory alignment. GDPR Article 17 (right to erasure) requires actual deletion, not soft deletion or archiving. HIPAA minimum necessary requires that data not be retained beyond its operational purpose. Both mandate irreversibility.
• Audit clarity. An assessor must be able to confirm: "at Clearing Level 2, the factors no longer exist on this system." If "soft delete" were allowed, the assessor would need to verify the deletion mechanism, the backup policy, the retention schedule, and the recovery procedure. Irreversibility eliminates this entire class of audit questions.

Why clearing is defined at the protocol level?

• Portability. The clearing level is recorded in the anchor metadata. Any SWT3-conformant system can read and understand what clearing level was applied, regardless of which platform minted the anchor.
• Vendor neutrality. If clearing were implementation-defined, each vendor could redefine "Level 1" to mean something different. Protocol-level definition prevents this. "Level 1" means the same thing everywhere.
• Interoperability. An anchor cleared at Level 2 on Platform A is understood by Platform B without coordination, negotiation, or mapping tables.

5. Anchor Format

Why a self-describing string token?

• Human-readable. An auditor can read an anchor during a site visit without any tooling. The tier, provider, domain, procedure, verdict, time, and fingerprint are all visible in the token.
• Greppable. grep SWT3- finds every anchor in a log file, a database dump, or a compliance report. No parsing required for discovery.
• Copy-pasteable. Fits in an email subject line, a Slack message, a spreadsheet cell, a terminal column, and a printed report.
• Self-contained verification. The fingerprint is embedded in the token. Given the factors, anyone can recompute the fingerprint and compare without database access.

Why normalized procedure IDs in the anchor but original IDs in the fingerprint?

• Anchor is for humans. SC76 is easier to read in a token than SC-7.6. Hyphens and dots in procedure IDs would conflict with the anchor's hyphen-separated format.
• Fingerprint is for math. The original format SC-7.6 is the canonical identifier used in compliance frameworks (NIST 800-53, CMMC). The cryptographic input must use the canonical form to ensure the fingerprint is tied to the real control ID, not a derived abbreviation.
• Lossless round-trip. The anchor can be parsed to extract the normalized ID, and the normalized ID can be expanded back to the original format using the UCT Registry. No information is lost.

6. UCT Taxonomy

Why framework-agnostic codes?

• Portability. A CRY anchor means "cryptography" whether the underlying check came from NIST SC-13, PCI-DSS Requirement 4, HIPAA encryption requirements, or ISO 27001 A.8.24. The UCT code is the bridge.
• Longevity. If NIST renames a control family in a future revision, the UCT code remains stable. Anchors minted under the current NIST mapping do not become orphaned.
• International scope. The EU AI Act, ISO 27001, SOC 2, and HIPAA do not use NIST family codes. A framework-specific taxonomy would require a separate code set for each jurisdiction. UCT provides one neutral layer that maps to all of them.

Why 3-letter codes?

• Short enough to fit in the anchor token without bloating it.
• Long enough to be semantically distinct. 2-letter codes would collide with existing identifiers (NIST families: AC, AU, CM are 2 letters; ISO clauses use 2-digit numbering).
• Alphabetic only. No digits, no special characters, no case ambiguity. Always uppercase. Unambiguous in any font, any terminal, any printed report.

Why additive-only governance?

• Anchor permanence. An anchor minted with UCT code ACC under Registry v1.0 must remain valid and meaningful under Registry v2.0, v3.0, and every future version. If a code were removed or redefined, historical anchors would lose their meaning.
• Deprecation without removal. A code may be marked as deprecated with a recommended successor, but it MUST remain valid for parsing and verification indefinitely. This allows the taxonomy to evolve without breaking the historical record.
• Precedent. This mirrors the IANA registry model: port numbers are assigned permanently. DNS record types are added but never removed. The stability of the registry is a prerequisite for the stability of the protocol.

7. Alternatives Considered and Rejected

Blockchain-based anchoring

• Latency. Block confirmation times (seconds to minutes) are incompatible with real-time inference witnessing. A compliance check that takes 15 seconds to anchor is unusable in production.
• Cost. Gas fees per anchor make high-volume witnessing (thousands of inferences per day) prohibitively expensive.
• Dependency. A blockchain dependency means the protocol cannot function in air-gapped environments, which is a core requirement for Clearing Level 3 (Sovereign).
• Unnecessary. SWT3's fingerprint achieves the same integrity guarantee using SHA-256 alone. The fingerprint is deterministic: given the same inputs, any party produces the same output. Immutability comes from the mathematics, not from a ledger.
• Not prohibited. An implementation MAY additionally anchor to a blockchain as a supplementary immutability layer. The protocol does not require or prevent it.

Certificate-based signing (X.509 / PKI)

• Infrastructure overhead. PKI requires certificate issuance, rotation, revocation checking (CRL/OCSP), and trust store management. This is a significant operational burden for a compliance SDK that aims for zero-friction adoption.
• Trust model mismatch. SWT3's signing is agent-to-platform, where both parties already share an API key. Asymmetric signing solves a problem (untrusted counterparties) that does not exist in this trust model.
• Not prohibited. Implementations that require certificate-grade assurance (e.g., cross-organization evidence exchange) can layer X.509 signing on top of the base HMAC-SHA256 signature. The protocol is extensible without being dependent.

OpenTelemetry as the native evidence format

• Mutability. OTel spans allow attributes to be added after creation. An SWT3 anchor is immutable once minted. The fingerprint seals the factors at the moment of observation. Post-creation modification breaks the fingerprint.
• No self-verification. OTel spans have no built-in mechanism for a third party to independently verify that the span data has not been altered. SWT3 fingerprints provide this by design.
• No clearing semantics. OTel has no concept of data sovereignty or controlled purging. Spans are retained or dropped, with no protocol-level guarantee about what persists and what is destroyed.
• Complementary, not competing. SWT3 exports TO OTel via the optional OTel exporter. Anchors appear as OTel spans in Datadog, Grafana, Jaeger, and other observability tools. SWT3 is the evidence source; OTel is a distribution channel.

8. Infrastructure-Layer Witnessing

Why a two-layer architecture for NVIDIA Dynamo?

• Adoption layer (Layer 1). A Python decorator (@witness_endpoint()) that works with any async generator endpoint. Zero imports from NVIDIA code. Duck-types OpenAI-compatible request/response formats. Users add one decorator, set one environment variable (SWT3_DSN), and witnessing begins. This minimizes integration friction and works with or without the Dynamo runtime.
• Infrastructure layer (Layer 2). A Dynamo-native @service class (WitnessInterceptor) that registers via depends(), injects compliance metadata into Dynamo's nvext request extensions, and publishes metrics through Dynamo's MetricsRegistry (swt3_witness_total, swt3_clearing_level). This provides infrastructure-team visibility without modifying application code.
• Patent defensibility. Layer 1 proves the pattern works without any Dynamo-specific code. Layer 2 demonstrates deep integration with the infrastructure runtime. Together they cover both the general method and the specific embodiment.

Why the SWT3_DSN connection string?

• Single-env-var deployment. Infrastructure teams managing hundreds of endpoints need exactly one configuration touch point. The DSN pattern (used by Sentry, Supabase, and database drivers) is well-understood by DevOps teams.
• Fallback to individual variables. When DSN is not set, the adapter falls back to SWT3_ENDPOINT, SWT3_API_KEY, and SWT3_TENANT_ID. This supports environments where URL-embedded credentials are not permitted.
• Graceful no-op. If neither DSN nor individual variables are set, the decorator passes through without error. This allows developers to add the decorator in development and activate witnessing in production by setting the environment variable.

Why duck-typing over explicit Dynamo imports?

• Testability. Layer 1 can be tested without GPUs, without the Dynamo runtime, and without NVIDIA hardware. Tests use plain Python dictionaries that match the expected interface shape.
• Portability. The same decorator works on vLLM, TGI, or any other inference server that exposes async generator endpoints. The witnessing pattern is not locked to a single vendor's runtime.
• Dependency hygiene. Zero external imports means zero supply chain risk from the witnessing layer. The adapter adds no transitive dependencies to the user's environment.