Skip to content

docs(capability-schema): mark as not runtime-enforced (register #9) - #55

Merged
mdheller merged 1 commit into
mainfrom
docs/capability-schema-not-runtime-enforced
Aug 4, 2026
Merged

docs(capability-schema): mark as not runtime-enforced (register #9)#55
mdheller merged 1 commit into
mainfrom
docs/capability-schema-not-runtime-enforced

Conversation

@mdheller

@mdheller mdheller commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

docs(capability-schema): mark as not runtime-enforced (register #9)

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.

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.
@mdheller
mdheller merged commit 4e1f396 into main Aug 4, 2026
4 checks passed
@mdheller
mdheller deleted the docs/capability-schema-not-runtime-enforced branch August 4, 2026 19:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant