docs(capability-schema): mark as not runtime-enforced (register #9) - #55
Merged
Merged
Conversation
2026-07-29 estate audit register item #9: `requires_user_consent` in `schemas/sourceos-capability.schema.json` has no reader — the one example fixture only ever sets it to `false`, so the true-case is never exercised even in a fixture, let alone enforced. Verified directly (2026-08-04), and the gap is broader than the original item named: EVERY declarative field in this schema is unread — `default_decision` (allow/deny/prompt/audit), `requires_user_consent`, `audit`, `privacy_impact`, `compatible_authority_domains` alike. The only two consumers (`tools/validate_json_schemas.py`, `tools/validate_control_plane_ examples.py`) check shape and `schema_version` only. This daemon's actual capability-gating code, `src/sourceos_syncd/ orchestration_events.py`, uses a completely different record shape (`capability_id`/`effect_class`/`required_policy_outcome`/ `approval_mode`) with zero connection to this schema. Did NOT wire a reader here. Forcing a unification between the two capability models without knowing which one is meant to win would be exactly the "declared enforcement that isn't" pattern the register exists to catch — orchestration_events.py's gate already works; grafting requires_user_consent onto it by guessing at intent risks either a fake pass (the field gets read but nothing branches on it, same disease) or breaking a working gate. What this PR does instead: makes the disconnect impossible to miss. A `$comment` on the schema and a README callout both state, plainly, that this file is a declarative capability catalog with no runtime consumer, name the real gate, and pose the actual open question — unify into orchestration_events.py, or is this a forward-declared catalog that predates the gate it was meant to feed? That's a design decision for a human, not an implementation guess. Verified: schema still valid JSON, both existing validators (validate_json_schemas.py, validate_control_plane_examples.py) still pass unchanged.
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
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.
docs(capability-schema): mark as not runtime-enforced (register #9)
2026-07-29 estate audit register item #9:
requires_user_consentinschemas/sourceos-capability.schema.jsonhas no reader — the oneexample fixture only ever sets it to
false, so the true-case isnever exercised even in a fixture, let alone enforced.
Verified directly (2026-08-04), and the gap is broader than the
original item named: EVERY declarative field in this schema is
unread —
default_decision(allow/deny/prompt/audit),requires_user_consent,audit,privacy_impact,compatible_authority_domainsalike. The only two consumers(
tools/validate_json_schemas.py,tools/validate_control_plane_ examples.py) check shape andschema_versiononly. This daemon'sactual capability-gating code,
src/sourceos_syncd/ orchestration_events.py, uses a completely different record shape(
capability_id/effect_class/required_policy_outcome/approval_mode) with zero connection to this schema.Did NOT wire a reader here. Forcing a unification between the two
capability models without knowing which one is meant to win would be
exactly the "declared enforcement that isn't" pattern the register
exists to catch — orchestration_events.py's gate already works;
grafting requires_user_consent onto it by guessing at intent risks
either a fake pass (the field gets read but nothing branches on it,
same disease) or breaking a working gate.
What this PR does instead: makes the disconnect impossible to miss.
A
$commenton the schema and a README callout both state, plainly,that this file is a declarative capability catalog with no runtime
consumer, name the real gate, and pose the actual open question —
unify into orchestration_events.py, or is this a forward-declared
catalog that predates the gate it was meant to feed? That's a design
decision for a human, not an implementation guess.
Verified: schema still valid JSON, both existing validators
(validate_json_schemas.py, validate_control_plane_examples.py) still
pass unchanged.