diff --git a/docs/adr/ADR-0011-canonical-json-and-version-compatibility.md b/docs/adr/ADR-0011-canonical-json-and-version-compatibility.md new file mode 100644 index 0000000..3cf0b5b --- /dev/null +++ b/docs/adr/ADR-0011-canonical-json-and-version-compatibility.md @@ -0,0 +1,158 @@ +# ADR-0011 — Canonical JSON and Version Compatibility + +- **Status:** Proposed; acceptance blocked by D-006 and D-023 +- **Date:** 2026-08-10 +- **Decision owner:** Protocol maintainer (`@chefmrfrizzle`) +- **Required reviewer:** Independent interoperability/security reviewer + +## Context + +Valoris needs stable bytes before it can safely define content identifiers or +signatures. Ordinary JSON is not stable enough: parsers can differ on duplicate +names, unsafe numbers, Unicode, and negative zero, and a schema's validator +dialect is not the same thing as a protocol release. + +This proposal is based on [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785.html), +its [verified errata](https://www.rfc-editor.org/errata/rfc8785), +[RFC 7493](https://www.rfc-editor.org/rfc/rfc7493.html), +[JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html), +and [Semantic Versioning 2.0.0](https://semver.org/). RFC 8785 is informational, +so this ADR must identify the exact Valoris profile rather than imply standards +status it does not have. + +## Proposed decision + +### Strict input profile + +A hash-critical Valoris JSON object would be eligible for canonicalization only +after a strict parser and the exact referenced schema establish all of the +following: + +1. Input is UTF-8 JSON without a byte-order mark. +2. Object member names are unique. Duplicate-name rejection happens before a + language runtime can overwrite or merge values. +3. Strings contain valid interoperable Unicode and are preserved as parsed; + canonicalization performs no Unicode normalization. +4. A strict decoder maps each JSON number token to binary64 using the exact + conversion and rounding behavior required by the canonicalization profile. + The source number token is retained through validation so implementations + can test boundary and alias cases before discarding it. +5. Negative zero is rejected, implementing verified RFC 8785 erratum 7920. +6. Exact integers outside `[-9007199254740991, 9007199254740991]`, quantities + whose meaning depends on their source spelling, and decimal quantities whose + domain cannot tolerate binary64 rounding use schema-defined strings, not + JSON numbers. +7. The object conforms to an immutable, explicitly identified schema resource. +8. Unknown fields fail unless the schema defines an explicit extension point. + Hash-critical processors do not silently drop or reinterpret extensions. + +Canonical output would use the RFC 8785 transformation: ECMAScript-compatible +primitive serialization, recursive object-property sorting by UTF-16 code +units, array order preserved, no insignificant whitespace, and UTF-8 encoding. + +Canonicalization commits to the parsed numeric value, not to the original JSON +number spelling. Equivalent spellings such as `1`, `1.0`, and `1e0` are therefore +expected to converge. The protocol cannot determine a sender's "intended" +value after parsing. Any domain that needs lexical fidelity, decimal arithmetic, +units-preserving quantities, or exact values outside the safe integer range must +use a schema-defined string form. Golden vectors must expose rounding aliases +on both sides of every admitted boundary. + +The exact canonicalization-profile identifier is not selected by this ADR. It +must be carried in, or unambiguously bound by, any content-identifier or +signature context so the same bytes cannot be reinterpreted under another +profile. + +### Version dimensions + +Four values have different jobs and must not be conflated: + +- `$schema` identifies the JSON Schema dialect used by a schema document; +- `$id` gives an immutable identity to a schema resource; +- `protocol_version` identifies the Valoris protocol interpretation; +- `schema_version` identifies the canonical object's schema release. + +Those field names are conceptual until schemas are designed. No consumer may +resolve a floating `latest` schema when verifying historical evidence. + +Valoris would apply Semantic Versioning to a documented public compatibility +surface with stricter hash-history rules: + +- **Major:** any incompatible interpretation, required-field, canonical-byte, + commitment-scope, or verification change. +- **Minor:** an explicitly backward-compatible capability added at a declared + extension point. Existing canonical objects retain their original bytes and + meaning, but an older verifier does not infer that it can accept a newer minor + object. +- **Patch:** editorial clarification or correction that does not change the set + of accepted instances, canonical bytes, field meaning, or verification + result. A behavioral fix requires a new schema resource and non-patch release. + +Every producer declares an exact emitted version. Every verifier declares the +exact versions it accepts. Compatibility is an explicit matrix, not lexical +version comparison or best-effort parsing. Unknown major versions, unknown +critical extensions, missing historical schemas, and ambiguous downgrades fail +closed. + +Semantic Versioning labels are release metadata, not proof of wire +compatibility. The compatibility matrix is authoritative for each producer, +consumer, object type, extension point, and verification operation. A newer +minor release can be backward-compatible for producers while still requiring an +older security verifier to reject objects containing semantics it cannot +evaluate. + +### Historical interpretation + +Released schema resources and canonicalization profiles are immutable. A new +release may deprecate an old profile for new issuance while retaining a bounded, +auditable verifier capable of interpreting historical objects under their +original rules. Migration creates a new object and an explicit relationship to +its predecessor; it never changes the predecessor's bytes or identity. + +Historical interpretability is not current acceptability. A verifier must +report separately that an old object parses and verifies under its original +profile and whether current policy still trusts that profile for the requested +operation. Deprecated code paths must be isolated and unavailable for new +issuance. + +## Required evidence before acceptance + +1. Golden vectors cover nested sorting, array preservation, escaping, UTF-8, + UTF-16 ordering, duplicate names, invalid Unicode, negative zero, equivalent + number spellings, binary64 rounding aliases, numeric boundaries, unsafe + integers, and schema/version mismatches. +2. At least two independently maintained language implementations produce the + same bytes or the same rejection for every vector. +3. A compatibility matrix demonstrates major, minor, patch, extension, + downgrade, and historical-resolution behavior. +4. An independent reviewer approves the parser boundary, numeric domain, + canonicalization profile, and denial-of-service limits. +5. ADR-0012 supplies non-ambiguous domain separation and commitment scope before + any content identifier or signature is implemented. + +## Consequences + +- Hash-critical input becomes deliberately narrower than ordinary JSON. +- Some convenient native numeric values must be represented by typed strings. +- Implementations need a strict pre-parser rather than trusting default JSON + decoding behavior. +- Historical verification requires an immutable schema/profile archive. +- Additive evolution is possible only through designed extension points. + +## Alternatives not selected + +- **Raw producer bytes:** preserves formatting accidents and does not give + semantic interoperability. +- **Default language JSON serializer:** property order, number rendering, and + invalid-input handling differ across runtimes. +- **Floating schema URLs:** make historical meaning depend on mutable state. +- **Normalize Unicode before hashing:** changes author-provided code points and + can make distinct inputs collapse unexpectedly. +- **CBOR as an immediate replacement:** may be evaluated later, but would not + remove the need to specify numeric, version, and commitment semantics. + +## Non-goals + +This ADR does not define JSON schemas, choose hash or signature algorithms, +define identifier wire syntax, implement canonicalization, or approve any +security or scientific policy. diff --git a/docs/adr/ADR-0012-content-identifiers-and-signature-suite-agility.md b/docs/adr/ADR-0012-content-identifiers-and-signature-suite-agility.md new file mode 100644 index 0000000..3598886 --- /dev/null +++ b/docs/adr/ADR-0012-content-identifiers-and-signature-suite-agility.md @@ -0,0 +1,158 @@ +# ADR-0012 — Content Identifiers and Signature-Suite Agility + +- **Status:** Proposed; every cryptographic choice is `BLOCKED_UNVERIFIED` under D-007 and D-017 +- **Date:** 2026-08-10 +- **Decision owner:** Protocol maintainer (`@chefmrfrizzle`) +- **Required reviewer:** Independent cryptography reviewer + +## Context + +Valoris must avoid identifiers whose algorithm or canonicalization assumptions +are implicit, and signatures whose names omit security-relevant parameters. +Content identity, event identity, signer identity, and authorization are +different claims. + +The proposal follows the agility principles in +[RFC 7696 / BCP 201](https://www.rfc-editor.org/rfc/rfc7696.html), the move to +fully specified algorithm identifiers in +[RFC 9864](https://www.rfc-editor.org/rfc/rfc9864.html), the named-information +model and limitations in [RFC 6920](https://www.rfc-editor.org/rfc/rfc6920.html), +and the protected-metadata pattern in +[RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html). It does not adopt any +one of those wire formats. + +## Proposed decision + +### Distinct identifier classes + +The protocol would assign different types and namespaces to: + +- **content identifier:** commitment to canonical object content; +- **event identifier:** identity of an occurrence in an event source; +- **key identifier:** lookup hint for a specific verification key; +- **actor/controller identifier:** identity used in authorization policy; +- **delegation identifier:** immutable reference to an authority grant. + +Software must not compare, substitute, or infer authority across these classes. +A content identifier demonstrates only a digest relationship to declared bytes; +it is not proof of authorship, permission, freshness, or confidentiality. + +### Self-describing content commitment + +A content identifier's interpreted structure would bind, without ambiguous +concatenation: + +1. a Valoris content-identifier profile and version; +2. an object domain/type and schema version; +3. a canonicalization profile; +4. a digest algorithm/profile identifier that fixes every parameter, including + whether truncation is permitted and the exact output length; +5. a canonical identifier encoding; and +6. the digest value. + +The digest preimage would use explicit domain separation for the Valoris +protocol, object type, schema version, and canonicalization profile. The exact +framing, wire grammar, digest algorithm, digest length, truncation policy, and +text/binary encoding are all `BLOCKED_UNVERIFIED`. They must be frozen by golden +vectors and reviewed before an identifier is emitted. Digest length is never an +attacker-selected runtime option: a permitted length belongs to a separately +registered profile. + +Objects cannot contain their own content identifier inside the bytes used to +derive that identifier. References, signatures, and envelope fields require an +explicit commitment-scope table so there is no circular or accidental omission. + +### Fully specified signature suites + +A signature-suite identifier would identify every security-relevant choice, +including algorithm parameters and the signature-envelope profile. It may not +be a generic label whose concrete operation is inferred from key type. A key is +bound to its permitted suite, controller, purpose, and lifecycle state. + +Verification-affecting metadata—including suite, key identifier, signer or +controller, content identifier, canonicalization profile, protocol context, +creation time, expiry when present, nonce when present, and purpose—must be +inside the protected commitment. The exact envelope remains +`BLOCKED_UNVERIFIED`. + +An envelope parser would reject duplicate signature labels, duplicate protected +parameters, unprotected copies of protected parameters, ambiguous key lookup, +and signatures that can be moved between envelope positions or object types. +The acceptance policy must identify the exact signature set and threshold +required for the operation; "at least one valid signature" is not a safe +default. + +Verifiers use an application policy allowlist. Unknown, ambiguous, deprecated +for the relevant time, or context-incompatible suites fail closed. There is no +opportunistic negotiation or fallback to a weaker algorithm. + +Algorithm or suite selection is bound to the protected evidence and to an +independently obtained verifier policy version. A signer cannot authorize a new +algorithm merely by naming it in signed content. If algorithm information is +available from the envelope, key, registry, or policy in more than one place, +every resolved value must agree or verification fails. + +### Transition and deprecation + +Algorithm registry entries are immutable. A policy may stop new signing with a +suite while retaining historical verification long enough to interpret existing +evidence. A transition may require dual signatures or dual content commitments, +but the acceptance rule, cutover times, and downgrade protections must be +explicit. Two digests do not become the same identifier merely because a +migration relates them. + +Transition evidence must itself resist stripping. If policy requires both an +old and a new suite, removing either signature or its required-suite declaration +causes failure. If policy accepts either suite during a window, that exact +window and policy version must be external to attacker-controlled content and +auditable. A weak historical signature cannot satisfy a current-operation gate +merely because it remains parseable. + +Emergency deprecation, key rotation, compromise handling, cryptoperiods, +retention, and verification after retirement belong to the key-lifecycle policy +required by D-017. [NIST SP 800-57 Part 1 Rev. 5](https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final) +and the current final [SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) +must be considered at decision time. The draft Rev. 3 is a watch item, not an +accepted basis. + +## `BLOCKED_UNVERIFIED` choices + +No choice is made for: + +- digest algorithm, output length, multihash/CID use, identifier encoding, or + wire grammar; +- signature algorithm, parameter set, key format, key identifier derivation, + random-number requirements, or hardware-key policy; +- signature envelope, countersignature, timestamp authority, nonce strategy, + transparency mechanism, or revocation-status format; +- mandatory-to-implement suite set, transition window, dual-signature rule, or + historical-verification lifetime. + +## Required evidence before acceptance + +1. A threat model covers collision, second-preimage, algorithm confusion, + downgrade, key substitution, parser differential, replay, and compromised + key scenarios. +2. Cross-language vectors cover domain separation, every committed field, + malformed prefixes, wrong or truncated lengths, duplicate parameters, + signature reordering/stripping, unknown suites, and transition cases. +3. Independent cryptography review approves the exact constructions and key + lifecycle. +4. At least two implementations verify the same positive and negative vectors. +5. Deprecation and emergency-rotation exercises preserve historical evidence + without permitting new use of a retired suite. + +## Alternatives not selected + +- **Bare hex digest:** omits algorithm, profile, type, and encoding context. +- **Algorithm inferred from digest length:** ambiguous and unsafe for migration. +- **Generic algorithm names interpreted from the key:** creates algorithm + confusion and prevents precise policy. +- **Single forever algorithm:** removes a safe migration path. +- **Runtime algorithm negotiation:** adds downgrade risk to deterministic + verification. + +## Non-goals + +This ADR authorizes no cryptographic implementation, production key, signing +service, schema, worker, payment mechanism, or accepted security policy. diff --git a/docs/adr/ADR-0013-event-identity-delegation-and-revocation.md b/docs/adr/ADR-0013-event-identity-delegation-and-revocation.md new file mode 100644 index 0000000..c466928 --- /dev/null +++ b/docs/adr/ADR-0013-event-identity-delegation-and-revocation.md @@ -0,0 +1,181 @@ +# ADR-0013 — Event Identity, Delegation, and Revocation + +- **Status:** Proposed; identity and cryptographic mechanisms are `BLOCKED_UNVERIFIED` under D-024 and D-017 +- **Date:** 2026-08-10 +- **Decision owner:** Protocol maintainer (`@chefmrfrizzle`) +- **Required reviewers:** Independent security/identity reviewer and institutional IT reviewer + +## Context + +An append-only protocol needs to distinguish an occurrence from its payload, an +executing actor from the authority on whose behalf it acts, and cryptographic +validity from authorization. It also needs revocation without rewriting old +evidence. + +This proposal draws event-identity semantics from +[CloudEvents 1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md), +UUID constraints from [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html), +delegation concepts from [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html), +revocation/status concepts from [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009.html) +and [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662.html), and authorization +hardening from [RFC 9700](https://www.rfc-editor.org/rfc/rfc9700.html). It does +not adopt OAuth, JWT, CloudEvents, UUIDv7, or a W3C credential format. + +## Proposed decision + +### Event identity + +An event occurrence is uniquely identified within its source by the pair +`event_source` and `event_id`. These names are conceptual until schemas exist. +Event identity is independent of the event payload's content identifier. + +The source is a security boundary, not a producer-chosen free-form collision +escape. A future policy must authorize stable source namespaces, canonicalize +their identifiers, bind a producer to its permitted source, and reject source +rebinding. Otherwise, the same producer could evade deduplication by changing +`event_source`, or another producer could impersonate a trusted namespace. + +- A retransmission that the producer declares to be the same occurrence retains + the same event identity and is deduplicated. Payload equality alone does not + prove that two deliveries represent the same occurrence. +- A new attempt, observation, decision, correction, or transformation receives + a new event identity and references its cause or predecessor. +- A correction never overwrites the earlier event. It appends a superseding or + corrective event and preserves both. +- Event identifiers are opaque. Timestamp ordering, if encoded, is not trusted + as causal or authorization evidence. + +Source and event identifiers must not contain secrets or unnecessary personal, +tenant, host, network, or laboratory information. Time-ordered identifiers can +leak creation time and activity volume; that privacy tradeoff is part of the +blocked identifier decision. + +An event would declare its source, identifier, type/version, data-schema +identity, subject, actor, content commitment, occurrence time, recording time, +and applicable causation/correlation/predecessor links. Exact fields and schema +are not decided here. + +UUIDv7 is only a candidate. The identifier format remains blocked until +collision, privacy leakage, concurrency, monotonicity, and clock-rollback tests +are complete. + +### Authority and delegation + +The protocol would record separately: + +- **subject/principal:** whose authority or resource is affected; +- **actor/delegate:** who or what executed the action; +- **issuer/delegator:** authority granting the delegation; +- **controller/key:** evidence used to authenticate the actor; and +- **policy decision:** why the authenticated actor was authorized for this + action at this time. + +Delegation and impersonation are distinct. An actor chain remains visible; a +system may not erase the delegate and represent the action as if the subject +performed it directly. + +Every delegation hop would explicitly bind a delegator, delegate, permitted +capabilities/actions, resource constraints, audience, purpose, not-before and +expiry bounds, parent delegation, maximum depth, and further-delegation rule. +Child authority must be a subset of valid parent authority. No delegation is +implicit, transitive by default, perpetual by omission, or widened by an +unrecognized field. + +"Subset" requires a formal, canonical comparison for action, resource, audience, +purpose, time, and delegation depth. Wildcards, exclusions, case differences, +Unicode aliases, URI normalization, and incomparable constraint languages are +common escalation paths. A verifier that cannot prove every child dimension is +no broader than its parent fails closed. The absence of an explicit +further-delegation grant means redelegation is forbidden. + +Authentication is never sufficient authorization. Verification must establish +the key's allowed purpose, actor/controller relationship, complete delegation +chain, audience, scope, time, resource, replay status, and revocation state. + +Authorization is bound to the exact event, operation, policy version, delegation +chain, and evaluated status evidence. If authorization and execution are +separated, the policy must define whether status is rechecked at execution and +how a stale authorization decision expires; otherwise revocation races create a +time-of-check/time-of-use bypass. + +### Revocation and historical trust + +Revocation is an append-only event targeting an exact key, delegation, or +capability identifier. It records issuer, authority, effective time or interval, +reason class, and predecessor where applicable. A revocation may cascade only +when the governing policy says exactly which descendants become invalid. + +The revocation issuer must prove authority over the target and revocation +purpose. The event separately records issuance time, claimed effective time, +observation/recording time, and the time authority or evidence used for each. +Backdated, future-dated, or late-observed revocations are not silently trusted; +policy must state how they affect decisions made before the revocation was +observable. + +Verification reports at least two separate conclusions: + +1. **cryptographic validity:** whether the evidence verifies under the declared + suite and key material; and +2. **authorization/trust status:** whether the key, delegation, purpose, and + policy were acceptable at the relevant event or execution time, including + any later compromise determination. + +A later revocation does not silently mutate an old event. A compromise policy +may declare a key untrusted for an explicit earlier interval, but that is a new, +auditable policy conclusion linked to the preserved cryptographic evidence. + +Historical reports must identify the query perspective: trust as known at the +original decision time, trust as known at a later audit time, and current trust +can differ. `occurred_at`, signer creation time, recording time, revocation +effective time, and verifier observation time are not interchangeable, and no +one of them is trusted merely because it is signed. + +High-risk operations fail closed when required status or delegation evidence is +unavailable. Exact caching, offline operation, freshness, availability, privacy, +and recovery behavior remain blocked. + +Actor and delegation chains can expose employment, collaboration, funding, and +institutional relationships. The future model must minimize public identifiers, +separate public proof from restricted audit evidence, define retention and +access, and prevent status lookups from becoming a correlation channel. No +selective-disclosure or status mechanism is selected here. + +## `BLOCKED_UNVERIFIED` choices + +No choice is made for identity provider, actor identifier, key/controller +document, credential/token format, event-ID format, delegation wire format, +status list or introspection service, hardware authenticator, recovery process, +or cryptographic suite. + +## Required evidence before acceptance + +1. Tests cover retry deduplication, source rebinding, concurrent creation, + corrections, transformations, clock rollback, ID collisions, timestamp and + volume leakage, and identifier correlation. +2. Authorization matrices cover subject/actor separation, nested delegation, + audience and purpose mismatch, expiry, parent narrowing, forbidden + escalation, wildcard/normalization ambiguity, incomparable constraints, + redelegation, replay, and incomplete chains. +3. Revocation tests cover prospective revocation, compromise intervals, + cascading policy, stale/unavailable status, backdating, future dating, + time-of-check/time-of-use races, recovery, and historical replay from each + declared query perspective. +4. Projection rebuilds reproduce the same state solely from append-only events. +5. Independent security/identity and institutional IT reviewers approve the + model and operational failure behavior. + +## Alternatives not selected + +- **Content hash as event ID:** collapses distinct occurrences with identical + payloads. +- **Account ID as actor, subject, and key:** hides delegation and prevents safe + rotation. +- **Implicit role inheritance:** creates invisible privilege escalation. +- **Delete revoked records:** destroys auditability and historical explanation. +- **Assume token revocation cascades automatically:** external standards do not + provide that guarantee without explicit policy. + +## Non-goals + +This ADR does not define schemas, adopt an identity stack, implement auth, +select cryptography, approve security policy, or authorize production events. diff --git a/docs/adr/ADR-0014-reproduction-independence-profiles.md b/docs/adr/ADR-0014-reproduction-independence-profiles.md new file mode 100644 index 0000000..981543e --- /dev/null +++ b/docs/adr/ADR-0014-reproduction-independence-profiles.md @@ -0,0 +1,121 @@ +# ADR-0014 — Reproduction Independence Profiles + +- **Status:** Proposed; policy adoption remains `BLOCKED_OWNER` under D-019 +- **Date:** 2026-08-10 +- **Decision owner:** Protocol maintainer (`@chefmrfrizzle`) +- **Required reviewers:** Independent security reviewer, institutional IT reviewer, and workload-domain reviewer + +## Context + +"Ran twice" is not the same as independently reproduced. Independence can vary +by person, organization, implementation, environment, hardware, and data. A +single label that hides those dimensions would overstate scientific evidence. + +The [National Academies](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science) +and [ACM artifact-review policy](https://www.acm.org/publications/policies/artifact-review-and-badging-current) +use carefully defined but not identical reproduction/replication vocabulary. +Valoris therefore needs explicit local terms and a mapping to external claims. + +## Proposed decision + +Every reproduction assertion would record, rather than infer: + +- human operator identity and conflict disclosure; +- controlling organization and common-control relationship; +- sponsor, funding, employment, and supervision relationships relevant to + independence; +- implementation provenance and whether code was independently written; +- execution environment, operating system, architecture, and dependency lock; +- physical/virtual hardware and infrastructure operator; +- data/input source and whether it was independently acquired; +- verification policy, reviewer identity, and domain qualifications; and +- communications or assistance received from the original authors. + +The evidence would then report each dimension plus one of these proposed local +profiles: + +| Profile | Minimum claim | +|---|---| +| **I0 — Replay** | Same controlling party may reuse the same implementation, data, and environment. Demonstrates repeat execution only. | +| **I1 — Second-environment confirmation** | Same controlling party and artifacts run in a materially different declared machine/environment. Useful portability evidence, but not independent-person reproduction. | +| **I2 — External-operator reproduction** | A different qualified human outside the original author's direct control uses separate credentials and environment. Author implementation and data may be used and must be disclosed. Organizational, funding, and common-control independence remain separate dimensions. | +| **I3 — Independent-implementation reproduction** | I2 plus an independently developed implementation of the declared method, with provenance showing it was not a repackaging of author code. This label establishes implementation independence only; it does not by itself establish organizational or funding independence. | +| **I4 — External replication/validation** | An independent team uses independently acquired data, experiment, or study design to address the same scientific question under domain-specific policy. Outside the first technical slice. | + +These labels are proposals, not adopted policy. A result receives only the +highest profile for which every required dimension has evidence. Missing or +conflicting evidence lowers the claim or leaves it unclassified; it never +defaults upward. + +A second GitHub account, process, agent, container, or machine under the same +human or organizational control does not establish independent-person or +independent-organization review. Account separation can satisfy a repository +workflow control while remaining I0 or I1 scientific evidence. + +No proposed profile currently authorizes the unqualified product claim +"independently reproduced." I1 must be described only as second-environment +confirmation. I2 establishes an external operator but can still involve shared +organizational control, funding, supervision, or conflicts. I3 adds +implementation independence but can retain those same conflicts. D-019 must +define the minimum dimensional evidence for any unqualified independence claim. +Scientific acceptance and external validation remain separate decisions even +after I2 or I3 succeeds. + +The profile label is never a substitute for its dimension vector. Interfaces +and receipts must display material common-control and conflict disclosures next +to the label and must not hide a failed dimension behind an aggregate score. + +Independence evidence can itself be sensitive. The future policy must minimize +personal data, prefer scoped attestations over publishing raw identity or +employment records, separate public claims from restricted conflict evidence, +and define access, retention, appeal, and correction paths. Those mechanisms are +not selected here. + +## Benchmark application + +For the proposed `spglib` benchmark: + +- the existing one-machine repeated runs are I0 evidence; +- a run by the maintainer on Linux-x86_64 would be I1 if the environment is + materially different and fully recorded; +- I2 requires a qualified person outside the maintainer's direct control, but + does not by itself establish organizational or funding independence; +- I3 additionally requires an independently developed implementation or + independently justified equivalent method; and +- I4 is not claimed by a synthetic symmetry-classification fixture. + +D-019 still decides the accepted definitions and D-018 still decides scientific +acceptance. This ADR does not resolve either decision. + +## Required evidence before acceptance + +1. Independent reviewers test the profiles against university, contract lab, + cloud, sponsor-funded, open-source, and solo-founder scenarios. +2. Conflict-of-interest and common-control rules have objective disclosure and + escalation paths without collecting unnecessary personal data or exposing + restricted relationship evidence publicly. +3. The selected benchmark is executed on the approved second-machine matrix and + reviewed by a named domain expert. +4. UI and receipts expose dimensional evidence and never compress an I0/I1 run + into an independence claim. +5. Appeals, disputes, compromised identities, and undisclosed relationships + create append-only counterevidence rather than deleting earlier receipts. + +## Alternatives not selected + +- **Binary independent/not-independent field:** conceals which dimensions + actually changed. +- **Different machine equals independent:** confuses portability with human and + organizational independence. +- **Different account equals independent:** account separation does not prove a + different controller. +- **External operator equals fully independent:** the operator can still share + employer, funding, supervision, infrastructure, or implementation dependence. +- **Successful reproduction equals scientific acceptance:** computational + consistency is necessary evidence, not a vote that makes a claim true. + +## Non-goals + +This ADR does not approve independence policy, scientific-acceptance policy, +identity verification, a benchmark, payment eligibility, or production +implementation. diff --git a/docs/phase-0/DECISION_REGISTER.md b/docs/phase-0/DECISION_REGISTER.md index dba1df3..884da99 100644 --- a/docs/phase-0/DECISION_REGISTER.md +++ b/docs/phase-0/DECISION_REGISTER.md @@ -9,8 +9,8 @@ Status values: `ACCEPTED`, `PROPOSED`, `DEFERRED`, `BLOCKED` | D-003 | ACCEPTED | Give every important claim a Counterexample Track. | ADR-0007; failure evidence remains permanent. | | D-004 | ACCEPTED | Use an append-only event/receipt record as canonical history; treat graphs and dashboards as rebuildable projections. | Prevents a graph database or dashboard from becoming an unverifiable single source of truth. | | D-005 | ACCEPTED | Keep deterministic protocol validation in the core and probabilistic/AI assistance at the edge. | Agents propose; policy and executable gates decide. | -| D-006 | PROPOSED | Constrain hash-critical JSON to RFC 8785-compatible I-JSON and ship cross-language golden vectors before signatures. | Resolve numeric-domain restrictions and implementation availability in Phase 1. | -| D-007 | PROPOSED | Use algorithm-prefixed content identifiers and signature-suite identifiers to preserve cryptographic agility. | Exact hash/signature suite is `BLOCKED_UNVERIFIED` pending security review and test vectors. | +| D-006 | PROPOSED | Constrain hash-critical JSON to RFC 8785-compatible I-JSON and ship cross-language golden vectors before signatures. | ADR-0011 proposes strict input constraints, including rejection of negative zero under verified RFC 8785 erratum 7920. Acceptance awaits D-023. | +| D-007 | PROPOSED | Use algorithm-prefixed content identifiers and fully specified signature-suite identifiers to preserve cryptographic agility. | ADR-0012 is proposed. Exact identifier grammar, hash, signature suite, envelope, and key format remain `BLOCKED_UNVERIFIED` pending D-017 security review and test vectors. | | D-008 | ACCEPTED | Map exported provenance to W3C PROV-DM while keeping protocol events as the internal transaction model. | Supports interoperability without forcing RDF/PROV into the trusted execution path. | | D-009 | ACCEPTED | Start with one safe public/synthetic computational-materials benchmark. | Final benchmark choice requires sourced comparison, rights review, and a reproducibility budget. | | D-010 | ACCEPTED | Use risk-adaptive, sandbox-first onboarding. | Participants earn only the permissions needed for a verified first task. | @@ -20,12 +20,14 @@ Status values: `ACCEPTED`, `PROPOSED`, `DEFERRED`, `BLOCKED` | D-014 | DEFERRED | Sponsor accounting and contribution attribution. | Model off-chain only after receipt and replay invariants pass. | | D-015 | DEFERRED | Any settlement rail. | Requires accepted accounting, duplicate protection, refunds, budget ceilings, and legal review. | | D-016 | DEFERRED | Confidential-computing attestations and zero-knowledge techniques. | Add only for a demonstrated threat/customer requirement; do not use cryptography as decoration. | -| D-017 | BLOCKED | Production signature suite and key lifecycle. | Requires threat-model review, rotation/revocation design, test vectors, and multi-language implementation evidence. | +| D-017 | BLOCKED | Production signature suite and key lifecycle. | ADR-0012 and ADR-0013 define proposal boundaries only. Every concrete cryptographic choice remains `BLOCKED_UNVERIFIED`; acceptance requires threat-model review, rotation/revocation design, test vectors, and multi-language implementation evidence. | | D-018 | BLOCKED | Scientific acceptance policy for the first workload. | Requires the selected benchmark and a named domain reviewer. | -| D-019 | BLOCKED | Independence policy for reproduction. | Must define organizational, operator, implementation, environment, and data independence for the first workload. | +| D-019 | BLOCKED | Independence policy for reproduction. | ADR-0014 proposes dimensional evidence and I0–I4 labels, but no profile is accepted. Must define organizational, operator, implementation, environment, hardware, control/funding, and data independence for the first workload. | | D-020 | BLOCKED | Production retention periods. | Requires data owners, customer obligations, legal review, and storage architecture. | | D-021 | BLOCKED | Adopt the pinned `spglib` wurtzite workload as the first technical benchmark. | ADR-0010 is proposed. Requires a named computational-crystallography reviewer to approve the exact input convention, tolerance/challenge suite, discrete outputs, and technical claim boundary. | | D-022 | BLOCKED | Freeze the first benchmark environment and second-machine matrix. | Requires exact runtime/dependency/artifact hashes plus successful macOS-arm64 and Linux-x86_64 evidence; D-019 must decide whether that evidence is independently reproduced. | +| D-023 | BLOCKED | Adopt the canonical JSON and protocol/schema compatibility profile. | ADR-0011 is proposed. Requires strict-parser and compatibility tests, immutable historical resolution, identical golden-vector results from two independent language implementations, and interoperability/security review. | +| D-024 | BLOCKED | Adopt the event identity, delegation, and revocation model. | ADR-0013 is proposed. Event-ID format, identity stack, delegation/status representation, offline/freshness behavior, and all cryptographic mechanisms remain `BLOCKED_UNVERIFIED` pending security/identity and institutional IT review. | ## Decision ownership @@ -36,13 +38,20 @@ Status values: `ACCEPTED`, `PROPOSED`, `DEFERRED`, `BLOCKED` | D-011 | Protocol maintainer (`@chefmrfrizzle`) | Institutional security/IT design partner. | `BLOCKED_OWNER`: design-partner reviewer not assigned. | | D-017 | Protocol maintainer (`@chefmrfrizzle`) | Independent security/cryptography reviewer. | `BLOCKED_OWNER`: reviewer not assigned; no production signature suite may be selected. | | D-018 | Protocol maintainer (`@chefmrfrizzle`) | Named computational-materials domain reviewer. | `BLOCKED_OWNER`: reviewer not assigned and the proposed benchmark is not adopted. | -| D-019 | Protocol maintainer (`@chefmrfrizzle`) | Independent security reviewer and institutional IT reviewer. | `BLOCKED_OWNER`: both reviewer roles are unassigned. | +| D-019 | Protocol maintainer (`@chefmrfrizzle`) | Independent security reviewer, institutional IT reviewer, and workload-domain reviewer. | `BLOCKED_OWNER`: all reviewer roles are unassigned; account or machine separation under common control cannot satisfy them. | | D-020 | Protocol maintainer (`@chefmrfrizzle`) | Data owner and qualified legal/privacy reviewer. | `BLOCKED_OWNER`: both decision authorities are unassigned. | | D-021 | Protocol maintainer (`@chefmrfrizzle`) | Independent computational-crystallography reviewer. | `BLOCKED_OWNER`: reviewer not assigned; see ADR-0010 and `BENCHMARK_SELECTION.md`. | | D-022 | Protocol maintainer (`@chefmrfrizzle`) | Reproduction reviewer under the future D-019 policy. | `BLOCKED_EVIDENCE`: reviewer/matrix not approved and no Linux-x86_64 run exists. | +| D-023 | Protocol maintainer (`@chefmrfrizzle`) | Independent interoperability/security reviewer. | `BLOCKED_OWNER` and `BLOCKED_EVIDENCE`: reviewer is unassigned and two-language golden-vector/compatibility evidence does not exist. | +| D-024 | Protocol maintainer (`@chefmrfrizzle`) | Independent security/identity reviewer and institutional IT reviewer. | `BLOCKED_OWNER`: both reviewer roles are unassigned; all concrete identity, status, and cryptographic mechanisms remain `BLOCKED_UNVERIFIED`. | The protocol maintainer owns assignment and evidence collection but cannot substitute for a required independent authority. +For Prompt 3, the interoperability/security, cryptography, identity/institutional +IT, and computational-materials methodology seats must be held by separate +qualified people outside the maintainer's control. `@11BUSD` is disclosed as the +same operator and is ineligible for all four seats. + ## Solo-maintainer governance exception (Prompt 1 / Prompt 2 only) `@11BUSD` approval can satisfy GitHub's separate-account enforcement for repository workflow gating, but it does **not** constitute independent-person assurance. @@ -57,9 +66,13 @@ Not allowed with this exception: - approving production retention/legal gates (D-020), - authorizing confidential customer/production workload promotion. -## Required next ADRs +## Required next ADR actions -1. Canonical serialization, identifier, and cryptographic agility profile. -2. First benchmark and domain acceptance policy. -3. Identity, delegation, and independence model. -4. Canonical event log and projection consistency model. +1. Review ADR-0011 and ADR-0012 without selecting cryptographic suites or + implementing schemas. +2. Assign the independent owners and produce evidence required by D-023 and + D-017. +3. Review ADR-0013 and ADR-0014 without adopting security, scientific- + acceptance, or reproduction-independence policy. +4. Draft the canonical event-log and projection-consistency ADR only after the + event-identity model has independent review. diff --git a/docs/phase-0/LEARNING_EPISODE-0005.md b/docs/phase-0/LEARNING_EPISODE-0005.md new file mode 100644 index 0000000..d446aed --- /dev/null +++ b/docs/phase-0/LEARNING_EPISODE-0005.md @@ -0,0 +1,43 @@ +# LearningEpisode 0005 — Canonicalization, Identity, and Independence Review + +- **Trigger:** Prompt 2 PR #3 was approved by `@11BUSD` on exact head + `f657bd11a713999fb0e667a14284f9810c620bba`, had no review conversations, + passed the required repository-baseline check, remained public, and merged + without administrator bypass as main commit + `d379b76e29c453ad514141a28029e821be89c16e`. +- **Inputs:** Current primary RFC, NIST, W3C, JSON Schema, CloudEvents, + National Academies, and ACM specifications and policies recorded in + `PROMPT_3_SPECIFICATION_REVIEW.md`; existing Phase 0 invariants and blocked + decisions. +- **Observation:** A canonicalizer is unsafe without a strict input boundary. + Verified RFC 8785 erratum 7920 identifies negative zero as an ambiguity because + `-0` canonicalizes as `0`. Duplicate members, invalid Unicode, and lossy + numbers create additional parser-differential risks. +- **Observation:** Current RFC 9864 guidance favors fully specified algorithm + identifiers over generic identifiers interpreted from key context. Algorithm + labels alone do not supply safe agility, key lifecycle, or downgrade policy. +- **Observation:** Event occurrence identity, payload content identity, actor, + subject, key, and authorization are different concepts. Delegation must remain + visible, and standards do not make revocation propagation automatic. +- **Observation:** External authorities use related but non-identical meanings + for reproduction and replication. Scientific claims therefore need + dimensional evidence, not a binary label. +- **Failure evidence preserved:** Negative zero collapsing to zero; duplicate + names interpreted differently; unsafe integers rounded before hashing; + algorithm confusion or downgrade; content hash treated as authority; retries + double-counted as new events; delegation escalation; revocation rewriting + history; and same-controller accounts or machines presented as independent. +- **Decision:** Draft ADR-0011 through ADR-0014 and add D-023/D-024. Keep every + concrete cryptographic choice `BLOCKED_UNVERIFIED`, keep D-019 blocked, and + make no schema or implementation change. +- **Rejected shortcuts:** Selecting a familiar signature suite without a threat + model; inferring an algorithm from key or digest length; treating UUID time as + causal truth; assuming authentication grants authorization; or treating + repository account separation as scientific independence. +- **Validation required next:** Independent owners, strict-parser and + cross-language golden vectors, a compatibility matrix, cryptographic threat + model and lifecycle review, delegation/revocation test matrices, and + benchmark-specific independent reproduction evidence. +- **Promotion decision:** Prompt 3 documentation may be reviewed in a draft PR. + No security, scientific-acceptance, or independence policy is accepted or + eligible to merge under the solo-maintainer exception. diff --git a/docs/phase-0/LEARNING_EPISODE-0006.md b/docs/phase-0/LEARNING_EPISODE-0006.md new file mode 100644 index 0000000..cf7a214 --- /dev/null +++ b/docs/phase-0/LEARNING_EPISODE-0006.md @@ -0,0 +1,34 @@ +# LearningEpisode 0006 — Prompt 3 Independent-Review Gate Preparation + +- **Trigger:** Audit Prompt 3 PR #4 on exact head + `47439b5d311eb30ac5db59be05f8b6696f093620` without implementing or accepting + policy. +- **Gate evidence:** Repository public; baseline green; PR draft and + `REVIEW_REQUIRED`; zero requested reviewers, submitted reviews, conversation + comments, or review threads. +- **Inputs:** Every primary source cited by ADR-0011 through ADR-0014, current + NIST publication status, CloudEvents release status, repository governance, + and the thread-aware GitHub review read. +- **Observation:** The sources supported the overall proposal direction, but the + text left material ambiguity in numeric conversion, minor-version acceptance, + algorithm transition stripping, event source authority, delegation subset + comparison, revocation time perspectives, status TOCTOU, identifier privacy, + and unqualified independence language. +- **Failure evidence preserved:** Different numeric tokens aliasing after + binary64 conversion; a newer minor accepted by inference; a truncated digest + or stripped transition signature; source rebinding; wildcard/normalization + delegation escalation; backdated revocation; stale authorization at execution; + timestamp/relationship correlation; and an external operator presented as + fully independent despite shared control or funding. +- **Decision:** Correct documentation only; add a source-by-source audit and four + distinct independent-review seats; keep D-017, D-019, D-023, and D-024 + blocked; keep every cryptographic selection `BLOCKED_UNVERIFIED`. +- **Independence disclosure:** This audit was performed by Codex for the + maintainer and is not R1–R4 independent approval. `@11BUSD` is controlled by + the same human as the owner and is ineligible for those seats. +- **Validation required next:** Green checks on the corrected head, named and + conflict-checked R1–R4 reviewers, exact-head reviews, resolved threads, and + review of plans rather than implementation. +- **Promotion decision:** The review gate remains `BLOCKED_OWNER`. Do not merge + security, cryptographic, scientific-acceptance, or independence policy and do + not begin Prompt 4 implementation. diff --git a/docs/phase-0/PROMPT_3_REVIEW_GATE.md b/docs/phase-0/PROMPT_3_REVIEW_GATE.md new file mode 100644 index 0000000..ed0b3fe --- /dev/null +++ b/docs/phase-0/PROMPT_3_REVIEW_GATE.md @@ -0,0 +1,134 @@ +# Prompt 3 Independent-Review Gate + +- **Gate status:** `BLOCKED_OWNER`; no independent approval exists +- **Audit date:** 2026-08-10 +- **PR:** [#4](https://github.com/chefmrfrizzle/valoris/pull/4) +- **Audited head:** `47439b5d311eb30ac5db59be05f8b6696f093620` +- **Audit role:** Maintainer-side preparation by Codex; not independent review +- **Implementation authority:** None + +## Exact-head evidence before corrections + +The GitHub connector and authenticated CLI agreed that, at the start of this +gate: + +- `chefmrfrizzle/valoris` had `visibility: public`; +- PR #4 was open and draft on exact head + `47439b5d311eb30ac5db59be05f8b6696f093620`; +- the `Repository baseline` check had completed successfully; +- `reviewDecision` was `REVIEW_REQUIRED`; +- no reviewer was requested and no review had been submitted; and +- the thread-aware GraphQL read returned zero conversation comments and zero + review threads. + +The audit below therefore targets the requested exact head, but it cannot pass +the independent-review gate. Documentation corrections create a new head that +must receive fresh, exact-head review from every required independent seat. + +## Primary-source claim audit + +| Source cited by Prompt 3 | Verification result | Qualification or correction | +|---|---|---| +| [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785.html) | Confirmed: I-JSON input, ECMAScript number serialization, recursive UTF-16 property ordering, preserved array order, and UTF-8 output. | It is Informational, not Standards Track. The ADR already discloses that status. | +| [Verified erratum 7920](https://www.rfc-editor.org/errata/eid7920) | Confirmed: `-0` serializes as `0`; a parser should error and stop. | Rejecting negative zero is a justified proposed narrowing. | +| [RFC 7493](https://www.rfc-editor.org/rfc/rfc7493.html) | Confirmed: UTF-8, no surrogate/noncharacter strings, unique decoded member names, and binary64 interoperability limits. | It recommends a general must-ignore evolution pattern, while ADR-0011 intentionally proposes stricter fail-closed behavior for hash-critical objects. The divergence is explicit and needs reviewer approval. | +| [JSON Schema Draft 2020-12 Core](https://json-schema.org/draft/2020-12/json-schema-core.html) | Confirmed: `$schema` identifies the dialect/meta-schema and `$id` identifies a schema resource by canonical URI. | The published core page is an informational Internet-Draft snapshot; it must not be described as an IETF RFC. | +| [Semantic Versioning 2.0.0](https://semver.org/) | Confirmed: major/minor/patch meanings depend on a defined public API and released contents are immutable. | Corrected ADR-0011: SemVer labels are not wire-compatibility proof and an older verifier does not infer acceptance of a newer minor version. | +| [RFC 7696 / BCP 201](https://www.rfc-editor.org/rfc/rfc7696.html) | Confirmed: protocols using cryptography need a mechanism to identify suites, identifiers alone are insufficient, selection must resist downgrade, registries retain/deprecate entries, and mandatory sets should stay small. | Corrected ADR-0012 to bind policy/suite selection and stripping-resistant transition rules. | +| [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864.html) | Confirmed: it deprecates polymorphic JOSE/COSE registrations, creates fully specified identifiers, and requires single-algorithm key use unless multi-use is proven secure. | Scope is JOSE/COSE algorithms. Valoris uses the principle as design evidence and does not claim RFC 9864 standardizes a Valoris suite or digest identifier. | +| [RFC 6920](https://www.rfc-editor.org/rfc/rfc6920.html) | Confirmed: named-information identifiers include hash-algorithm context and do not prove authority or confidentiality. | It is architectural precedent, not adoption of its URI/wire format. | +| [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) | Confirmed with qualification: signature parameters are covered by the signature base; algorithms may be resolved from several sources; disagreement must fail; runtime `alg` signaling is specifically cautioned. | Corrected the research summary so it does not imply `alg` is always present or always the preferred signal. | +| [NIST SP 800-57 Part 1 Rev. 5](https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final) | Confirmed current final general key-management guidance as of the audit date. | It supplies review criteria, not a suite choice. | +| [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) and [Rev. 3 initial public draft](https://csrc.nist.gov/pubs/sp/800/131/a/r3/ipd) | Confirmed: Rev. 2 remains the final publication; Rev. 3 remains an initial public draft with the comment period closed. | Rev. 3 is only a watch item. Every concrete choice remains `BLOCKED_UNVERIFIED`. | +| [CloudEvents 1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) | Confirmed: `source` plus `id` is unique for each distinct event; a resent duplicate may reuse the ID. | Corrected ADR-0013 so retransmission identity is a producer declaration, not an inference from byte equality, and added source-rebinding controls. | +| [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html) | Confirmed: UUIDv7 is time ordered and generators must handle entropy, batches, counters, monotonicity, and rollover. | UUIDv7 remains only a candidate; timestamp/activity leakage and source privacy were added to the blocked review. | +| [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html) | Confirmed: delegation keeps actor and principal distinct; token exchange does not create automatic lifecycle linkage and revocation propagation is optional policy. | OAuth/token exchange is vocabulary evidence only, not an adopted credential format. | +| [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009.html) and [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662.html) | Confirmed: revocation can invalidate related tokens under policy; active status combines issuance, expiry, revocation, and context validity. | Corrected ADR-0013 to distinguish issuance, effective, observed, and audit times and to require revocation authority. | +| [RFC 9700 / BCP 240](https://www.rfc-editor.org/rfc/rfc9700.html) | Confirmed: sender constraint, audience restriction, resource validation, and replay resistance reduce token misuse. | Used as security guidance only; OAuth is not selected. | +| [W3C Controlled Identifiers 1.0](https://www.w3.org/TR/controller-document/) | Confirmed current W3C Recommendation: verification methods have purpose relationships, and controller assertions are not automatically true. | Corrected ADR-0013 to require policy authorization beyond key possession and to treat source/controller assertions as claims requiring validation. | +| [National Academies 2019](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science) | Confirmed: computational reproducibility uses the same input data, computational steps, methods, code, and conditions; replicability uses new studies/data addressing the same question. | Valoris profiles must declare local vocabulary and cannot collapse computational reproduction into scientific acceptance. | +| [ACM Artifact Review and Badging v1.1](https://www.acm.org/publications/policies/artifact-review-and-badging-current) | Confirmed: Results Reproduced can use author artifacts; Results Replicated does not use author-supplied artifacts; both require a person/team other than the authors. | Corrected ADR-0014: an external operator or independent implementation does not establish organizational, funding, or full independence. | + +## Findings resolved in the proposal text + +1. **P1 — Untestable numeric intent:** Replaced “intended value” with a + specified token-to-binary64 boundary, explicit lexical-fidelity limitations, + and required rounding-alias vectors. +2. **P1 — Overstated independence:** Removed the proposal that I2 could support + the unqualified phrase “independently reproduced.” Renamed it + external-operator reproduction and preserved organization/funding/control as + separate evidence. +3. **P1 — Revocation-time ambiguity:** Separated issuance, effective, + observation, decision, execution, and audit perspectives; added authority, + backdating, and time-of-check/time-of-use requirements. +4. **P1 — Source-rebinding and delegation escalation:** Added governed source + namespaces and fail-closed subset comparison across wildcard, exclusion, + case, Unicode, URI, time, purpose, and audience dimensions. +5. **P1 — Downgrade and stripping:** Added fixed digest-profile lengths, + duplicate/ambiguous envelope rejection, exact signature-set policy, + external policy binding, and stripping-resistant dual-suite transitions. +6. **P2 — Version overclaim:** Clarified that SemVer is release metadata and the + explicit compatibility matrix controls security-verifier acceptance. +7. **P2 — Privacy gaps:** Added identifier timestamp/activity leakage, + actor/delegation correlation, conflict-evidence minimization, restricted + audit access, retention, and appeal requirements. +8. **P2 — RFC 9421 overgeneralization:** Clarified that `alg` may be resolved in + several ways and runtime signaling is a documented confusion risk. + +These corrections make the proposals safer to review; they do not accept any +decision or satisfy any independent-review requirement. + +## Required independent reviewer seats + +All seats are unfilled. They must be held by separate qualified people outside +the maintainer's control, with conflicts disclosed. One person cannot approve +multiple seats for this gate. + +| Seat | Minimum qualification | Decisions/ADRs | Required review evidence | +|---|---|---|---| +| R1 — Interoperability/security | Demonstrated cross-language JSON/parser/canonicalization and protocol-versioning experience, including security-bound serialization. | ADR-0011; D-023 | Exact-head approval; source audit; numeric/parser vectors and compatibility-matrix review. | +| R2 — Cryptography | Professional protocol-cryptography, algorithm-agility, signature, and key-lifecycle expertise independent of the author. | ADR-0012; D-007/D-017 | Exact-head approval; threat model; construction and transition review. No algorithm selection is authorized by this PR. | +| R3 — Identity/institutional IT | Identity, authorization/delegation, revocation/status, privacy, and institutional integration experience. If no one person covers both identity security and institutional operations, split this seat into two reviewers. | ADR-0013; D-024 | Exact-head approval; delegation matrix; time/revocation, availability, privacy, and operational review. | +| R4 — Computational-materials methodology | Independent computational crystallographer/materials scientist able to assess the proposed `spglib` workload and scientific-claim boundary. | ADR-0014; D-018/D-019/D-021/D-022 | Exact-head approval of terminology only, plus later benchmark evidence. This PR cannot approve scientific acceptance. | + +`@11BUSD` is the same disclosed human operator as the repository owner. That +account may provide GitHub account separation only where ADR-0009 permits it; +it is not eligible for R1–R4 and supplies no independent-person evidence. + +## Unresolved decisions + +- **D-023:** no reviewer, strict-parser implementation, two-language golden + vectors, immutable schema archive, or compatibility matrix. +- **D-007/D-017:** no threat model, suite/hash/encoding selection, key lifecycle, + transition policy, test vectors, or cryptography reviewer. All choices remain + `BLOCKED_UNVERIFIED`. +- **D-024:** no accepted event source/ID, identity provider, delegation/status + representation, time authority, offline/freshness policy, privacy mechanism, + or identity/institutional reviewer. +- **D-019:** independence labels remain proposed; no accepted common-control, + funding, conflict, privacy, or product-language rule and no domain reviewer. +- **D-018/D-021/D-022:** benchmark adoption, scientific acceptance, frozen + environment, Linux-x86_64 evidence, and second-machine classification remain + blocked. + +## Safe prerequisites for Prompt 4 + +Prompt 4 must not begin schema or cryptographic implementation. The safe next +gate is: + +1. publish the corrected documentation-only head and obtain a green baseline; +2. assign R1–R4 to named, distinct, qualified people with conflict disclosures; +3. obtain reviews anchored to that exact final head and resolve every thread; +4. keep PR #4 draft and do not merge policy merely because documentation review + is green; +5. have R1 approve a non-executable golden-vector **plan** and compatibility- + matrix **plan**; +6. have R2 approve a threat-model **plan** while every suite choice stays + `BLOCKED_UNVERIFIED`; +7. have R3 approve delegation/revocation/time/privacy test matrices; and +8. have R4 approve only the benchmark terminology and domain-review plan, not + scientific acceptance. + +Only after those prerequisites may a later prompt propose a tightly scoped, +non-production conformance-fixture phase. Production schemas, signing, auth, +workers, payments, and infrastructure remain out of scope. diff --git a/docs/phase-0/PROMPT_3_SPECIFICATION_REVIEW.md b/docs/phase-0/PROMPT_3_SPECIFICATION_REVIEW.md new file mode 100644 index 0000000..f7f7455 --- /dev/null +++ b/docs/phase-0/PROMPT_3_SPECIFICATION_REVIEW.md @@ -0,0 +1,113 @@ +# Prompt 3 Specification Review + +- **Status:** Research complete; proposals remain unaccepted +- **Date:** 2026-08-10 +- **Scope:** Canonical JSON, compatibility, identifiers, signature agility, + event identity, delegation, revocation, and reproduction independence +- **Implementation authority:** None + +## Boundary + +This review prepares ADRs. It does not select a production hash or signature +suite, define schemas, implement a signing envelope, approve an identity +provider, or adopt scientific-acceptance or reproduction-independence policy. +All cryptographic choices remain `BLOCKED_UNVERIFIED` under D-017. + +The statements below are deliberately separated into sourced facts, protocol +proposals, and unresolved decisions. A proposal is not an accepted protocol +rule until its ADR, compatibility evidence, and required independent reviews +are complete. + +## Primary-source findings + +### Canonical JSON and versioning + +| Sourced fact | Protocol implication, not yet accepted | +|---|---| +| [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785.html) builds JSON Canonicalization Scheme (JCS) on I-JSON, ECMAScript number serialization, recursive UTF-16 property ordering, preserved array order, and UTF-8 output. | A hash-critical JSON profile can be narrow and testable, but calling output "canonical" is unsafe until all input restrictions are enforced before hashing. | +| [RFC 8785 verified errata](https://www.rfc-editor.org/errata/rfc8785) clarify that negative zero is valid JSON but serializes as `0`, and recommend rejecting `-0` to prevent ambiguity. | The proposed profile rejects negative zero rather than allowing two parsed inputs to collapse to one canonical value. | +| [RFC 7493](https://www.rfc-editor.org/rfc/rfc7493.html) requires UTF-8, unique object names, interoperable Unicode, and a restricted numeric domain; it recommends strings for exact integers outside the binary64 interoperable range. | Duplicate names, invalid Unicode, non-finite numbers, lossy numbers, and unsafe integers must fail before canonicalization. Larger exact integers or decimals require schema-defined string representations. | +| [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) uses `$schema` to identify a dialect and `$id` to identify a schema resource. | Validator dialect, immutable schema-resource identity, protocol version, and instance schema version must be distinct concepts. | +| [Semantic Versioning 2.0.0](https://semver.org/) defines major, minor, and patch changes relative to a declared public API and says released versions must not be modified. | Valoris must first define the compatibility surface. Hash or interpretation changes cannot be smuggled into a patch release. | + +### Identifiers and cryptographic agility + +| Sourced fact | Protocol implication, not yet accepted | +|---|---| +| [RFC 7696 / BCP 201](https://www.rfc-editor.org/rfc/rfc7696.html) requires explicit algorithm or suite identifiers for agility, cautions that identifiers alone are insufficient, and recommends small, changeable mandatory-to-implement sets. | Every digest and signature must be interpreted through an allowlisted, versioned profile; an algorithm label alone does not make a construction safe. | +| [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864.html) deprecates polymorphic JOSE/COSE algorithm identifiers in favor of fully specified identifiers and recommends single-algorithm keys. | Signature-suite identifiers must bind all security-relevant parameters. Generic names that change meaning from key context are not acceptable. No concrete suite is selected here. | +| [RFC 6920](https://www.rfc-editor.org/rfc/rfc6920.html) includes the hash algorithm in a named-information identifier and warns that a content digest provides integrity, not authority or confidentiality. | Content identifiers need algorithm and profile context and must never be treated as signatures, permissions, or secrecy controls. | +| [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) defines protected signature parameters such as creation, expiry, key identifier, nonce, and application tag; it permits algorithm resolution from several locations and requires disagreement to fail. It warns that runtime `alg` signaling can enable confusion or substitution. | Comparable Valoris metadata must be integrity-protected and checked against an application allowlist. Suite resolution must agree across every source and should not be attacker-negotiated. This is design guidance, not adoption of HTTP Message Signatures. | +| [NIST SP 800-57 Part 1 Rev. 5](https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final) covers key lifecycle and compromise handling. [SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) remains the current final transition guidance; [Rev. 3](https://csrc.nist.gov/pubs/sp/800/131/a/r3/ipd) is an initial public draft. | Algorithm selection cannot precede a key lifecycle, transition plan, threat model, and current standards review. Draft guidance is tracked but not represented as final. | + +### Event identity, delegation, and revocation + +| Sourced fact | Protocol implication, not yet accepted | +|---|---| +| [CloudEvents 1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) defines an event by the combination of `source` and `id`; a retransmission may reuse that identity. | Event occurrence identity must be separate from payload content identity. A retry is not automatically a new scientific occurrence. | +| [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html) standardizes UUIDs, including time-ordered UUIDv7, while requiring generators to address randomness, counters, clocks, and rollback. | UUIDv7 is only a candidate. Event-ID syntax remains blocked until collision, privacy, concurrency, and clock-rollback behavior is tested. | +| [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html) distinguishes delegation from impersonation, represents current and prior actors, and notes that revocation propagation is not automatic. | Subject authority and executing actor must be recorded separately; every delegation hop needs explicit scope and revocation semantics. OAuth/JWT is not selected as the wire format. | +| [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009.html) defines revocation and possible cascading invalidation; [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662.html) defines an active-state query; [RFC 9700](https://www.rfc-editor.org/rfc/rfc9700.html) recommends audience restriction, least privilege, replay protection, and sender-constrained credentials. | Revocation is an explicit state transition, status availability is security-relevant, and authorization must be bounded to audience, purpose, resources, and time. | +| [W3C Controlled Identifiers 1.0](https://www.w3.org/TR/controller-document/) separates verification methods from purpose-specific verification relationships. | Possessing a key is not sufficient authority for every event type; key purpose and controller authorization must both be evaluated. | + +### Reproduction independence + +| Sourced fact | Protocol implication, not yet accepted | +|---|---| +| The [National Academies report](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science) defines computational reproducibility around the same data, methods, code, and conditions, while replicability addresses a new study aimed at the same question. | Valoris must state its local vocabulary and independently record changes in operator, organization, implementation, environment, hardware, and data. | +| The [ACM artifact-review policy](https://www.acm.org/publications/policies/artifact-review-and-badging-current) distinguishes results reproduced by another team using author artifacts from results replicated using independently developed artifacts. | A single word cannot carry every independence claim. The evidence must identify who reproduced what, using whose implementation and data. | + +## Proposed decision map + +| Topic | Proposed ADR | Current disposition | Acceptance evidence | +|---|---|---|---| +| Canonical JSON constraints | ADR-0011 | `PROPOSED`; D-006 and D-023 remain open | Strict-parser tests and identical golden bytes in at least two independent language implementations, including verified errata cases. | +| Version compatibility | ADR-0011 | `BLOCKED` under D-023 | Explicit compatibility matrix, historical resolver, downgrade tests, and protocol/security review. | +| Algorithm-prefixed identifiers | ADR-0012 | `BLOCKED_UNVERIFIED` under D-007 | Threat model, domain-separated preimage vectors, collision analysis, parsing tests, and cross-language evidence. | +| Signature-suite agility | ADR-0012 | `BLOCKED_UNVERIFIED` under D-017 | Independent cryptography review, key lifecycle, fully specified suites, transition vectors, and implementation evidence. | +| Event identity | ADR-0013 | `BLOCKED` under D-024 | Collision/privacy/retry/correction tests and projection-rebuild evidence. | +| Delegation and revocation | ADR-0013 | `BLOCKED_UNVERIFIED` under D-024 and D-017 | Independent security/identity review, explicit actor-chain tests, compromise-time tests, and status-availability policy. | +| Reproduction independence | ADR-0014 | `BLOCKED_OWNER` under D-019 | Independent security, institutional IT, and domain review; benchmark-specific second-machine evidence. | + +## Cross-cutting failure cases to preserve + +1. `-0` and `0` collapsing to identical bytes without rejection. +2. Duplicate JSON member names interpreted differently by two parsers. +3. A numeric token rounded or aliased before the application checks whether its + domain permits binary64 semantics. +4. A producer relabeling canonical bytes under another schema or + canonicalization profile. +5. A generic signature algorithm interpreted differently from key context. +6. Algorithm downgrade or an unknown suite accepted by fallback behavior. +7. A content digest accepted as proof that an authorized actor produced it. +8. A retry counted as a distinct event or a correction overwriting history. +9. A delegate obtaining wider authority than its parent. +10. Revocation silently rewriting the historical record rather than expressing + signing-time validity and current trust separately. +11. A second account, process, or machine under the same control presented as an + independent reproducer. +12. An event producer evading deduplication by rebinding its source namespace. +13. Delegation widened through wildcard, exclusion, case, Unicode, or URI + normalization differences. +14. A revocation race between authorization and execution, or a backdated + revocation interpreted without an explicit audit-time perspective. +15. An external operator presented as fully independent despite shared + organization, funding, supervision, implementation, or infrastructure. + +## Unresolved decisions and owners + +- **D-023 — Canonicalization and version compatibility:** protocol maintainer; + requires an independent interoperability/security reviewer and two-language + golden-vector evidence. +- **D-007 / D-017 — Content identifiers and signatures:** protocol maintainer; + requires an independent cryptography reviewer. Exact algorithms, encodings, + key formats, signature envelopes, and transition schedules are + `BLOCKED_UNVERIFIED`. +- **D-024 — Event identity, delegation, and revocation:** protocol maintainer; + requires an independent security/identity reviewer and an institutional IT + reviewer. +- **D-019 — Reproduction independence:** protocol maintainer; requires the + independent reviewers already named in the decision register plus a domain + reviewer for the selected workload. + +No solo-maintainer exception converts any of these into accepted policy. diff --git a/docs/phase-0/README.md b/docs/phase-0/README.md index fd613a4..68eb41b 100644 --- a/docs/phase-0/README.md +++ b/docs/phase-0/README.md @@ -16,10 +16,20 @@ Phase 0 turns the original architecture ideas into a buildable decision boundary - `INNOVATION_GUARDRAILS.md` — expansion guardrails and stop criteria. - `NEXT_BUILD_PROMPTS.md` — copy-ready prompts sequenced behind explicit gates. - `BENCHMARK_SELECTION.md` — sourced four-candidate scorecard, one narrow recommendation, reproducibility budget, and blocked owners. +- `PROMPT_3_SPECIFICATION_REVIEW.md` — current primary-specification findings, + proposal/fact separation, failure cases, and blocked decision owners for + canonicalization, identity, cryptographic agility, and independence. +- `PROMPT_3_REVIEW_GATE.md` — exact-head audit evidence, source-by-source + verification, resolved proposal defects, and four unfilled independent-review + seats. - `LEARNING_EPISODE-0001.md` — evidence record for this work episode. - `LEARNING_EPISODE-0002.md` — readiness-review failures, fixes, and promotion blocker. - `LEARNING_EPISODE-0003.md` — review-feedback corrections and the research-only governance exception. - `LEARNING_EPISODE-0004.md` — benchmark research and the C/Python lattice-convention counterexample. +- `LEARNING_EPISODE-0005.md` — Prompt 3 standards findings and preserved + ambiguity, downgrade, revocation, and independence counterexamples. +- `LEARNING_EPISODE-0006.md` — Prompt 3 gate audit and the corrected + numeric/version, downgrade, delegation/time, privacy, and independence risks. - `audit/UX_AUDIT.md` — screenshot-backed review of the existing prototype. ## Exit criteria diff --git a/schemas/README.md b/schemas/README.md index 6bc7fba..cbe5559 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -17,3 +17,13 @@ Planned canonical objects: - ChangeProposal Phase 0 defines canonical serialization and golden cross-language vectors before hash-dependent production behavior. + +Prompt 3 produced proposal-only design records: + +- `docs/adr/ADR-0011-canonical-json-and-version-compatibility.md` +- `docs/adr/ADR-0012-content-identifiers-and-signature-suite-agility.md` +- `docs/adr/ADR-0013-event-identity-delegation-and-revocation.md` +- `docs/adr/ADR-0014-reproduction-independence-profiles.md` + +They do not authorize schema implementation. D-023 and D-024 are blocked, and +every cryptographic mechanism remains `BLOCKED_UNVERIFIED` under D-017.