[jeremi]

Pull Request

Summary

Adds read-only external views to BReg. A registry can show and filter
selected facts another institution keeps, through an Adapter projection,
while it stores only its own facts and the identifiers that link them.
Owning area: BReg (registry-breg, registry-bregctl), with the Adapter
projection contract it reads through.

Rebased onto #2630. #2630 added BREG-SEC-203 (the journal tells OAuth
clients apart), so this PR's invariants move to BREG-SEC-204 to 207 with
their negative tests, and external view reads take #2630's per-client
request audit context.

• Views and links. A package declares external record types,
  projections (live or indexed, one or many) and views whose links read
  through them. Indexed views list, filter, sort and count over a kept
  copy; live views read on demand.
• Authority changes rebind; operational changes do not. A projection's
  binding and grant fingerprints cover the pack contract, the operation
  and the allowed fields, and a changed cache lifetime starts a fresh
  epoch. Renewing a grant cutoff, replacing a CA bundle, moving an
  endpoint or changing acquisition limits keeps the cache. Each projection
  is checked on its own, so a mismatch takes only its views offline.
• Deployment configuration is the only cutoff. Removing a binding and
  restarting stops acquisition; its views answer source.unavailable.
  bregctl external-projection withdraw purges retained values but does
  not stop acquisition. Backups exclude projection data, so a restore
  starts with no source values, as on a fresh install.
• One cache lifetime, which a deployment may shorten but never extend.
  A successful source response marked no-store never enters the store
  and removes the previous snapshot. A no-store on an error, a redirect
  or the challenge that starts a credential refresh changes nothing, so a
  refresh that fails keeps the previous snapshot. A credential failure
  during an acquisition fails the projection, even when a route step
  catches it.
• Operator commands: bregctl external-projection inspect|withdraw|rotate,
  doctor checks with the grant horizon, and monitoring codes.
• Link keys. A record with no link key is covered, with no outside
  value, and is never sent to the source. A malformed key (over 512 bytes,
  surrounding white space, a control character) is never sent either: that
  record alone reads as having no outside value, the refresh and live reads
  count and log it as invalid-key, and lists, filters, sorts and counts
  keep serving the other records. Writing a malformed key to a field an
  external view links from is refused as request.invalid on create,
  patch, action, proposal, batch and import writes; proposals and action
  input are refused when submitted, before anything is stored. The same
  value in a field no view links from is accepted.
• Decimals from an external source are served as JSON strings on live
  and indexed paths. Integers keep their exact digits; other numbers are
  spelled without an exponent, so one very small or very large value no
  longer fails its batch.
• Continuations. A cursor is issued only for a sort value the next page
  accepts. A page whose last row carries a sort value too long to resume
  from answers source.unavailable with no nextCursor, after the earlier
  pages were served.
• Scale. Refresh and label pages are bounded to their continuation,
  and indexed reads look up each root's snapshot by primary key. Scale and
  recovery runners live under products/breg/loadtest/external-views/.

Evidence

Run locally against a disposable PostgreSQL database.

On the branch head, after the rebase onto #2630:

Claim	Command	Result
Formatting	cargo fmt --all -- --check	pass
Lints	cargo clippy -p registry-breg -p registry-bregctl --all-targets -- -D warnings (one run, as CI lints affected packages together)	pass
BReg library tests against PostgreSQL, including external projection maintenance	cargo test -p registry-breg --lib --features postgres-test,tooling,schema	768 passed, 1 ignored
BReg write paths and external views	cargo test -p registry-breg --features postgres-test --test postgres_mutation; the same with --test external_views	20 passed; 8 passed
Product contracts, including SEC-207 traceability	products/breg/scripts/check-contracts.sh; products/adapter/scripts/check-contracts.sh	pass. On macOS the webhook receiver test needs the FIPS crypto library on the loader path; the Adapter corpus holds 191 members, including adapter.pack.projection-invalid
Identifier catalog	products/identifiers/scripts/check.sh	32 passed
Load-test runners	python3 -B -m unittest test_runners test_scale in products/breg/loadtest/external-views/	10 passed

cargo clippy -p registry-breg --all-targets --features postgres-test
now stops on a type_complexity lint in tests/postgres_migration.rs
that is already on main; CI does not lint that feature set.

On an earlier head of this branch, before the rebase; CI runs them on this
head:

Claim	Command	Result
Adapter engine	cargo clippy -p registry-adapter-engine --all-targets -- -D warnings; cargo test -p registry-adapter-engine	pass; 408 passed
Full BReg PostgreSQL suite	products/breg/scripts/test-postgres.sh	1,236 passed, 0 failed, 9 ignored (opt-in: installed Node/Python packages, 5 perf benchmarks, generated consoles, the geojson example)
bregctl	cargo clippy -p registry-bregctl --all-targets -- -D warnings; cargo test -p registry-bregctl --test cli; cargo test -p registry-bregctl --lib	pass; 186 passed; 629 passed (the lib run needs a short TMPDIR on macOS for one socket path test)
Docs site pages changed here	npm run check in docs/site	pass (markdownlint 0, Vale 0 errors, astro check 0 errors, built links pass)

Tests covering the review fixes:

• link keys: a_root_without_a_link_key_is_covered_and_reads_absent and
  the invalid-key refresh and live-read tests in external_runtime.rs;
  invalid_label_selectors_are_unavailable_without_failing_the_rest_of_the_label_batch;
  an_unlinked_root_reads_as_a_complete_empty_related_collection;
• link keys on write: a_malformed_link_key_is_refused_when_a_patch_proposal_is_prepared,
  a_malformed_link_key_is_refused_when_a_create_proposal_is_prepared,
  a_malformed_link_key_is_refused_when_an_action_builds_its_effect_document,
  and the_write_path_refuses_a_malformed_link_key_on_the_linked_field_only
  (red when the write-time check is removed);
• decimals: exponent_range_decimals_are_served_as_plain_strings;
• continuations: a_cursor_is_issued_only_for_a_sort_value_it_will_accept;
• acquisition: a_caught_failure_of_the_initial_authorization_fails_the_acquisition,
  a_replayed_response_that_is_not_data_cannot_forbid_retention,
  a_202_marked_no_store_keeps_the_previous_snapshot (each red when the
  guarded line is reverted);
• bounded pages and index use: the dense-scope EXPLAIN tests in
  external_label_acquisition.rs and
  an_indexed_read_looks_up_each_root_snapshot_by_its_primary_key;
• operator codes and readiness: external_projection_failures_each_carry_one_code,
  a_refused_runtime_configuration_is_reported_as_status_reports_it,
  external_projection_operations_report_database_prerequisites_with_the_shared_codes,
  a_moved_activation_is_reported_as_not_ready.

The planner-shape tests depend on PostgreSQL planner behaviour (default
selectivity, collation match); comments in the tests say so. They forbid
a plain Sort and bound rows read, and allow an Incremental Sort.

Notes

• Malformed link keys: a key stored before its field was linked by a
  view keeps reading as no outside value until it is corrected; the
  refresh report and logs give the count. A proposal stored before the
  link carries its key to Apply, where the write is refused as
  request.invalid. Drafts validate inputs, not entity fields, so a draft
  accepts a malformed key until it is submitted. A mutation in an action
  hook's answer is refused as hook.proposal.mutation_refused, and
  history-migration SQL steps write without the check; reads guard those
  rows. An invalid label key still leaves only that related row without
  its label.
• Decimal precision: a source decimal is read as a double, so a value
  with more than about 15 significant digits is rounded before BReg serves
  it. BReg does not accept decimal strings from a source.
• $skiptoken length: a cursor payload may reach 8 KiB, which is about
  11 KiB once encrypted and base64url-encoded in the URL. A proxy with an
  8 KiB request-line limit refuses such a next page. Only sorts over long
  text values reach that size; a deployment that sorts on them should
  raise the proxy limit.
• no-store on an unaccepted 2xx: egress honours no-store on any 2xx,
  including a status the pack does not accept, so such a response removes
  the previous snapshot. This fails closed (data the source asked not to
  keep is dropped), and is left as it is.
• CodeQL: three high rust/cleartext-storage-database alerts point into
  #[cfg(test)] PostgreSQL test modules (external_view_query.rs,
  external_projection.rs, external_label_acquisition.rs); they are
  test fixtures, not runtime storage, and are to be dismissed as used in
  tests.
• Adapter corpus: the registered adapter.pack.projection-invalid
  code had no bad-authoring corpus member, so the Adapter contracts failed
  at their last step. This push adds the member (an exact projection
  whose selector and record key name different schemes) and its README
  row.
• Rust policy: the failing check on this PR is fixed by the dependency
  update in Support Studio review, action dates, and workflow timing #2630.
• Overlap with Support Studio review, action dates, and workflow timing #2630 on 11 files (Cargo.lock, BReg API and model,
  registry-bregctl/src/lib.rs, the CLI docs catalogue, the security
  matrix and traceability files, the authoring schema). Whichever merges
  second rebases.
• Compatibility: bregctl external-projection reports a refused
  runtime file with the same codes and exit status (1) as bregctl status.
  external-projection.unavailable is now the doctor warning only.
• Backups: the backup page shows the four --exclude-table-data
  options for packages with indexed projections; restore assumes them.
• Follow-ups filed: bregctl dev: a detached supervisor can inherit another start's output pipe, hanging parallel installed-dev tests #2631 (dev supervisor pipe inheritance hang),
  test(breg): the source successor test and frozen_rhai_package leak a container, a volume and a temp dir every run #2632 (test leaks), evidencectl dev: reading a state file refuses a valid file renamed over between lookup and open #2633 (evidencectl state read false refusal).
• Found, not in this PR: products/breg/scripts/test-postgres.sh does
  not run registry-breg --lib, so the external projection maintenance
  PostgreSQL tests run only in CI, and they need the tooling feature
  (with postgres-test alone the filter matches nothing). Clippy with
  postgres-test,tooling,schema --all-targets fails on a type-complexity
  lint in crates/registry-breg/tests/postgres_migration.rs, code already
  on main.

DCO

• Every commit includes a Signed-off-by trailer.
• I reviewed the submitted changes and am responsible for the contribution.

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-10T18:38:34.326253Z	11af7b1	New commits

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b12fb60c29

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a4459da23

ℹ️ 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".