[DO NOT MERGE — pending owner review] Add cross-language contracts standard - #5
Open
adelphi-liong wants to merge 11 commits into
Open
[DO NOT MERGE — pending owner review] Add cross-language contracts standard#5adelphi-liong wants to merge 11 commits into
adelphi-liong wants to merge 11 commits into
Conversation
📝 WalkthroughWalkthroughAdds 17 cross-language contract documents covering configuration, authentication, onboarding, routing, protocols, errors, telemetry, serialization, and platform identity. Adds upstream-change classification and proof evidence for the c0-contracts generation 5 review. ChangesC0 contract specifications
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/standards/contracts/config.md`:
- Around line 34-43: Update the configuration contract to define behavior when
multiple environment aliases normalize to the same key, such as
ATOMI_ERRORPORTAL__HOST and ATOMI_ERROR_PORTAL__HOST. Require duplicate
normalized aliases to be rejected during environment parsing or schema
composition, rather than relying on enumeration order; if an existing
deterministic precedence rule is intended, document it explicitly instead.
- Around line 8-10: Clarify the configuration contract so build-only secrets are
not treated as values in the artifact-frozen Layer C tree. Update the Layer C
definition and the secret handling rules to either place build-only inputs
outside the persisted configuration tree or define an explicit non-serializing
path excluded from final merged-tree validation, while preserving startup
validation for all persisted configuration.
In `@docs/standards/contracts/deeplinks.md`:
- Around line 44-51: Define the canonical parameter-encoding algorithm in the
deeplink contract before requiring URI equality, including UTF-8 conversion,
Unicode normalization, the exact unreserved-byte set, hexadecimal casing, and
behavior for already-encoded input. Add shared cross-language test vectors
covering reserved characters, Unicode values, and values containing slashes, and
require browser/mobile fixtures to use them.
In `@docs/standards/contracts/discovery.md`:
- Around line 86-93: Make the discovery URL validation requirements explicit:
every URL from A, B, or C must parse successfully as HTTPS and match a baked
cluster or rescue root by exact hostname-boundary-aware comparison. Replace any
raw string suffix check with parsed URL hostname validation, while preserving
the existing behavior that one invalid URL rejects the entire document.
In `@docs/standards/contracts/hostnames.md`:
- Around line 29-34: Update the previewPetname collision-handling rule to avoid
accepting a suffix that can map multiple manifest digests: extend the base32hex
digest suffix beyond three characters until it uniquely identifies the
allocation, or reject the allocation before creating DNS records or certificates
when uniqueness cannot be established. Preserve the unchanged stored name for
non-colliding allocations and keep the full digest out of all hostname-related
names.
In `@docs/standards/contracts/onboarding.md`:
- Around line 90-91: Update the OnboardSync transaction requirement in the
onboarding contract to define an idempotent outbox or saga for the Logto
Management API claim write, since it cannot share the local database
transaction. Specify the persisted state after claim-write failure and the
reconciliation/retry behavior, including safe handling of repeated attempts.
In `@docs/standards/contracts/otel.md`:
- Around line 16-54: Document the zero-exporter behavior for the canonical otel
configuration when logs, metrics, or traces are enabled but all corresponding
exporters are disabled. Explicitly define whether this state is a valid no-op, a
startup error, or an implicit SDK default, and make the rule apply consistently
across TypeScript/Bun, C#/.NET, and Go.
In `@docs/standards/contracts/problems.md`:
- Around line 61-63: Define in docs/standards/contracts/problems.md:61-63
whether uncatalogued RFC 9457 problems are permitted as a temporary fail-loud
exception, then update docs/standards/contracts/problem-catalog.md:36-47 to
express the same decision consistently, including the uncatalogued update loop
and expected client behavior; make no unrelated documentation changes.
In `@docs/standards/contracts/results.md`:
- Around line 13-16: Define the canonical wire representation for Result<Unit,
E> in the results contract, including the explicit success payload and its
decoding requirements. Update the unit-success guidance around the existing
success/error prohibition so all encoders and decoders must accept and interpret
the same representation, without allowing an empty or ambiguous object.
In `@docs/standards/contracts/serialization.md`:
- Around line 13-18: Update the temporal serialization contract table to define
one closed grammar across all codecs: replace broad ISO 8601 duration support
with lossless fixed-unit mappings or explicitly introduce a calendar-period type
for month/year values, specify canonical UTC RFC 3339 fractional-second
precision and rounding, and add cross-language fixtures covering calendar units,
fractional-second boundaries, and invalid representations.
In `@docs/standards/contracts/tokens.md`:
- Around line 12-16: Update the refresh-token contract near the token rotation
rules to define atomic handling for concurrent refresh requests: serialize
refresh operations per token or provide idempotent results for duplicate
in-flight uses, while preserving theft detection for reuse after rotation
completes. State the required server-side behavior so legitimate concurrent
requests do not invalidate the token family.
In `@docs/standards/contracts/webhooks.md`:
- Around line 47-49: Define non-null schemas and validation rules for
providerEventId, providerTimestamp, and providerSequence in the webhook
contract, while retaining their nullable forms. Use the existing serialization
contract for RFC 3339 timestamp representation and large-sequence encoding, and
specify the provider event ID’s string type.
- Around line 90-99: Update the webhook signing specification to explicitly
define HMAC-SHA256 with key=key and message=ASCII(t) || 0x2e ||
exact-body-bytes. Add a fixed cross-language test vector documenting the key,
timestamp, exact body bytes, and expected lowercase v1 signature.
In
`@proof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/final-clean.md`:
- Line 1: Add a top-level Markdown H1 heading as the first line of
final-clean.md, placing the existing review metadata after it so the document
satisfies markdownlint MD041.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 3b0cc7c6-5d7a-4d84-8ed1-5473635e4d75
📒 Files selected for processing (22)
UPSTREAM-CHANGES.mddocs/standards/contracts/app-handoff.mddocs/standards/contracts/config.mddocs/standards/contracts/deeplinks.mddocs/standards/contracts/discovery.mddocs/standards/contracts/home-claim.mddocs/standards/contracts/hostnames.mddocs/standards/contracts/index.mddocs/standards/contracts/infisical-paths.mddocs/standards/contracts/onboarding.mddocs/standards/contracts/otel.mddocs/standards/contracts/problem-catalog.mddocs/standards/contracts/problems.mddocs/standards/contracts/results.mddocs/standards/contracts/serialization.mddocs/standards/contracts/sit-conventions.mddocs/standards/contracts/tokens.mddocs/standards/contracts/webhooks.mdproof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/adherence-loop.mdproof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/final-clean.mdproof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/manifest.mdproof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/proof-results.md
Address four unresolved review findings on the C0 contract pages. config: build-operation-only secrets are no longer a Layer C member. They sit outside the persisted merged tree entirely, so the no-serialization rule stops contradicting artifact freezing while final-tree startup validation still covers all persisted configuration. The Faro upload-key reference boundary is retained and its prefixed name is marked a convention, not a bound key. config: prefixed environment names that normalize to one canonical path are now rejected deterministically during parsing/composition, naming every colliding source in sorted order, instead of resolving by enumeration order. deeplinks: define canonical per-component encoding end to end (NFC, UTF-8, the 66 unreserved ASCII bytes, uppercase percent hex, no pre-encoded input special case) and add shared cross-language vectors for reserved characters, Unicode, and slash-containing values that generated browser and mobile fixtures consume. discovery: URLs from Docs A/B/C must parse as HTTPS without userinfo, and the parsed hostname is compared to baked cluster/rescue roots label by label. Raw string suffix checks are prohibited; whole-document rejection is retained. hostnames: petname collisions extend the base32hex digest prefix until unique, bounded by a proper digest prefix and a 63-octet label, and refuse before DNS or certificate creation instead of accepting an ambiguous three-character suffix. Non-colliding stored names and full-digest exclusion are unchanged.
Follow-up to 7c3cf81 after integration review found two authority mismatches. Neither correction changes the defect the original commit closed. config: the C0 goal §3 places build-time secrets at the Layer C boundary, so saying they are outside Layer C altogether overshot. Layer C now explicitly carries two kinds of input: persisted build values, which enter the merged tree and freeze into the artifact, and ephemeral build-operation-only secrets, which are excluded from the merged and persisted tree and consumed out-of-band by the build step. The no-serialization rule and final-tree startup validation over all persisted configuration are unchanged. hostnames: concepts/environments.md R-P9 FINAL fixes the collision suffix at exactly the first three base32hex digest characters, with grammar <noun>-<verb>-<noun>[-<3-base32hex-digest-chars>]. Extension until unique is therefore not lawful. The suffix is restored to exactly three characters, and a suffixed name already held by another live differing digest now refuses loudly before DNS, certificate, redirect-URI, or discovery-entry creation, which is the same fail-closed outcome by the ruled mechanism.
Replace the open ISO 8601 duration reference with one closed fixed-duration grammar that TypeScript, .NET TimeSpan, Go time.Duration and Dart Duration all represent losslessly at millisecond precision, bounded to 9223372036854 ms. Calendar year, month and week designators are rejected, and a calendar period needs a separately named type rather than a wider grammar. Define the canonical UTC RFC 3339 instant form, its millisecond fractional precision, and truncation toward the past as the single narrowing rule, then add compact duration and instant vectors covering calendar units, fractional boundaries and the magnitude bound. Define atomic refresh rotation with serialization or idempotent coalescing for legitimate concurrent use of one refresh token, while keeping family invalidation for reuse after rotation completes. Close the non-null schemas for providerEventId, providerTimestamp and providerSequence, retaining their explicit nullable forms. State the delivery HMAC operands by name and add a fixed cross-language signature vector computed with openssl and rechecked independently. Add an H1 to the recorded final clean pass so it satisfies MD041.
Preserve C0 section 12 exactly: reuse after rotation completes is theft. Drop the post-completion coalescing reuse window and the lost-response retry example. Only presentations the server admitted while the predecessor was still active, that is in flight before the atomic rotation commit, may be serialized or coalesced onto the winning result. Neither behavior may outlive the commit: no rotation result is retained for replay, and any presentation beginning after the commit is reuse that MUST invalidate the family.
A serialized waiter necessarily receives its result at or after the atomic rotation commit, so the previous wording that neither behavior may outlive the commit was too strong. Eligibility closes at the commit; delivery to an already-admitted caller may finish afterwards. A caller whose presentation begins after the commit still may not join that rotation or receive its cached result.
adelphi-liong
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TypeScript, C#, Go, and Dart
OpenTelemetry, result, deep-link, app-handoff, onboarding, discovery,
webhook, identity, and SIT contracts
bundle
Validation
pre-commit run --all-filesarm and byte-identical restoration
Bun/helium's YAML + class-transformer/class-validator stack, and Go/tin's
Viper/mapstructure stack
verification rules: clean with no findings
Proof
The repository-owned bundle is under
proof-evidence/c0-contracts/20260731T095702Z-eb161e356d77623015d0f762ab5c5f54a8593b1b/.C0 is classified under S30 as contract/spec-only, so no executable probe matrix
or product pyramid applies.
Summary by CodeRabbit
Documentation
Tests