docs: add executable architecture model and Cargo wrapper - #623
Conversation
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
36242c1 to
cb97787
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb97787c6b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| cargo test --locked -p <changed-crate> # then the workspace if platform crates changed | ||
| ``` | ||
|
|
||
| In Codex-managed worktrees, invoke Cargo through `scripts/cargo-codex`. The |
There was a problem hiding this comment.
The reviewed commit has no Signed-off-by trailer (git interpret-trailers --parse returns no trailers), so it does not satisfy the repository's mandatory DCO policy and cannot pass the contribution gate. Recreate the commit with git commit -s or otherwise add a valid sign-off before merging.
AGENTS.md reference: AGENTS.md:L75-L77
Useful? React with 👍 / 👎.
|
|
||
| host applicationHost 'Single application host' { | ||
| network runtime 'Private runtime network' { | ||
| relay = instanceOf registryStack.relay.server |
There was a problem hiding this comment.
When this view is used as the documented single-node production target, this single Relay instance receives both edge traffic and the Notary consultation relationship, but the cited deployment guide explicitly requires one public Relay and one private consultation Relay (single-node-compose-behind-proxy.mdx:24-29). Collapsing them erases a deployment and trust boundary that the architecture model is intended to preserve; represent the two Relay instances separately and associate each lane with its corresponding state and traffic.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| @@ -0,0 +1,11 @@ | |||
| #!/bin/sh | |||
There was a problem hiding this comment.
This commit combines the scripts/cargo-codex contributor-tooling change and root agent guidance with the separately owned docs/site/ architecture model and its CI wiring. Split the Cargo-wrapper work into its own signed commit so the docs change remains scoped to one owning area and can be reviewed and reverted independently.
AGENTS.md reference: AGENTS.md:L84-L85
Useful? React with 👍 / 👎.
| network data 'Private data and state network' { | ||
| sourceMount = state 'Registry source mount or private binding' | ||
| relayState = instanceOf registryStack.relay.correctnessState | ||
| notaryState = instanceOf registryStack.notary.correctnessState |
There was a problem hiding this comment.
When operators use this as the documented production target, the data network shows only the two PostgreSQL correctness stores, while the cited deployment guide separately requires durable storage for PostgreSQL and for each product's anti-rollback state (single-node-compose-behind-proxy.mdx:44). Because neither modeled datastore includes anti-rollback state, the diagram presents an incomplete persistence boundary that could lead an implementation to omit the files needed for safe startup and upgrades; add the per-product anti-rollback stores explicitly.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| #!/bin/sh | ||
| set -eu | ||
|
|
||
| repo_root=$(git rev-parse --show-toplevel) |
There was a problem hiding this comment.
For a later change that touches only scripts/cargo-codex, the repository path classifier currently returns every gate as false, including an empty Rust matrix, and no workflow invokes the wrapper. That allows the newly mandated Codex Cargo entry point to become non-executable or fail before cargo without any required check noticing; route this path to a job that executes at least scripts/cargo-codex --version and cover that routing in test_ci_changes.py.
AGENTS.md reference: AGENTS.md:L47-L52
Useful? React with 👍 / 👎.
| keyProvider = externalSystem 'Signing provider' { | ||
| #external |
There was a problem hiding this comment.
In the documented single-node target, Notary consumes an operator-supplied private JWK (single-node-compose-behind-proxy.mdx:120-124), and the cited implementation builds LocalJwkEnv signers inside SigningKeyRegistry; it is not an external software system. Modeling every signing provider as externalSystem and instantiating it under institution-managed dependencies therefore invents a separate runtime/custody boundary for the default target. Represent the local signer inside Notary and reserve an external dependency for configurations such as an actually remote key provider.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
1 participant
What changed
AGENTS.mdWhy
The repository needs a reviewable, executable cross-product architecture model that supplements the narrative docs without replacing the source, specifications, or OpenAPI contracts. Codex-managed Rust worktrees also need a consistent wrapper for the build settings already used to stay within CI and local cache limits.
Impact
Maintainers can explore the model with
npm run architecture:devand validate it withnpm run check:architecture. The model is experimental and is not published with the Starlight site. The Cargo wrapper changes contributor tooling only and does not affect production runtime behavior.Architecture evidence reviewed
The model resolves claims against the RS architecture requirements and implementation evidence including:
docs/site/src/content/docs/spec/rs-arc-g.mdxcrates/registry-relaycrates/registry-notary-servercrates/registry-platform-auditandcrates/registry-platform-oidcdocs/site/src/content/docs/operate/single-node-compose-behind-proxy.mdxdocs/site/src/content/docs/operate/retention-and-persistent-state.mdxThe deployment diagram represents documented target guidance. It is not a claim of verified production topology or shipped generated artifacts.
Security, trust, and privacy claims remain subject to the Tier-C maintainer sign-off described in
docs/site/architecture/README.md.Validation
npm cinpm auditnpm test(267 tests passed)npm run checkpython3 .github/scripts/test_ci_changes.py(26 tests passed)scripts/cargo-codex --versiongit diff --check origin/main...HEAD