Add Capability Authority Plane contracts and diagnostic storm-control schemas

[mdheller]

Intent

Convert the macOS/BearBrowser failure lessons into canonical SourceOS typed contracts so runtime components do not repeat the opaque capability-denial, registry-failure, and diagnostic-storm anti-patterns observed in the uploaded log evidence.

This belongs in sourceos-spec because it is the shared machine-readable contract layer consumed by downstream runtimes.

Evidence-derived failure classes to model

The current log evidence shows these recurring classes:

1. Capability/permission denial loops

   • Full Disk Access/TCC-style denial
   • sandbox denied service lookup
   • locked/pre-unlock key material unavailable
   • denied pasteboard, analytics, LaunchServices/CoreServices, RunningBoard, FileProvider, network-settings, and diagnostic access

2. Broken registry / package identity plane

   • missing LaunchServices/extension records
   • invalid bundle/product identity
   • missing receipts
   • extension discovery cancellation
   • missing namespace descriptors / treatment layers

3. Diagnostic storm behavior

   • duplicate denial loops
   • retry spam without bounded state
   • network telemetry spam with nil device identifiers
   • missing causal continuity between the original denial and later degraded/crash behavior

4. Network truth ambiguity

   • Wi-Fi/radio active but no connected network
   • DNS/DHCP events with nil device identifiers
   • no route to host despite apparently satisfied path
   • broken pipe and route already exists conditions

5. Browser/runtime child-process failure

   • sandboxed WebContent/GPU/Networking helpers fail privileged lookups
   • pasteboard setup fails
   • LaunchServices/CoreServices and RunningBoard access fail
   • DB migration and plugin discovery failures surface as opaque runtime noise

Proposed new schemas

Add a capability-authority contract family under schemas/ with examples and catalog updates.

1. CapabilityContract.json

Purpose: declare what a component requires before runtime.

Required fields:

• id: urn:srcos:capability-contract:<slug>
• specVersion
• componentRef
• componentKind: app | daemon | agent | browser-child | terminal-helper | network-observer | file-monitor | extension-host | indexer | broker
• declaredCapabilities[]
• requiredBrokers[]
• minimumBootPhase
• degradedModePolicy
• userVisibleImpact
• evidenceRefs[]

2. CapabilityGrantState.json

Purpose: capture observed runtime state of each declared capability.

Required fields:

• id: urn:srcos:capability-grant-state:<slug>
• contractRef
• observedAt
• bootId
• sessionId
• permissionEpoch
• capabilityStates[]

Each capability state should include:

• capability
• requestedOperation
• subjectRef
• objectRef
• grantSource: policy | user-consent | broker | ambient-host | kernel | portal | inherited | unavailable
• decision: granted | denied | ask | degraded | unavailable | unknown
• policyRuleRef
• fallback
• userVisibleImpact
• remediationHint

3. DiagnosticStormRecord.json

Purpose: normalize repeated logs into bounded evidence.

Required fields:

• id: urn:srcos:diagnostic-storm:<slug>
• firstSeen
• lastSeen
• repeatCount
• signature
• severity
• sourceComponent
• normalizedFailureClass
• sampleEvents[]
• suppressionPolicy
• terminalState
• linkedIncidentRef

4. NetworkTruthState.json

Purpose: replace boolean online/offline status with explicit layered network truth.

Required fields:

• id: urn:srcos:network-truth:<slug>
• observedAt
• networkEpoch
• radioState
• associationState
• authenticationState
• dhcpState
• dnsState
• routeState
• captivePortalState
• internetReachability
• localMeshReachability
• vpnOrPrivacyOverlayState
• trustedPeerPathState
• evidenceRefs[]

5. RuntimeRegistryIntegrityRecord.json

Purpose: make the hidden desktop registry/package identity plane auditable.

Required fields:

• id: urn:srcos:runtime-registry-integrity:<slug>
• componentRef
• bundleOrPackageIdentity
• receiptState
• extensionRecords[]
• brokerRecords[]
• manifestDigest
• verificationVerdict: valid | degraded | missing | invalid | quarantined
• remediationHint

6. BootSessionPhaseState.json

Purpose: prevent services from running before the required boot/session phase.

Required fields:

• id: urn:srcos:boot-session-phase:<slug>
• bootId
• sessionId
• phase: sealed-boot | pre-login | post-login-locked | unlocked-user-session | degraded-session | recovery-session
• availableKeyrings[]
• availablePortals[]
• blockedComponents[]
• allowedComponents[]
• evidenceRefs[]

Acceptance tests

1. Examples validate under JSON Schema draft 2020-12.
2. schemas/README.md catalog includes the new family and URN prefixes.
3. A denied capability can be represented without ambiguity.
4. A repeated denial storm can be summarized without losing first/last/repeat count.
5. A browser child-process denied pasteboard/LaunchServices access can be represented with broker fallback.
6. A network state can distinguish radio-active/no-route/no-DNS/no-internet/local-mesh-only states.
7. A pre-unlock service attempt can be rejected as phase-ineligible with a user-readable remediation hint.
8. Runtime identity failures can distinguish missing receipt, invalid manifest, missing extension record, and quarantined plugin.

Downstream consumers

• SourceOS-Linux/sourceos-shell: runtime doctor and shell diagnostics.
• SocioProphet/meshrush: network truth and graph-traversal capability evidence.
• BearBrowser/TurtleTerm surfaces when they land in their final runtime home.
• SocioProphet/prophet-platform: evidence receipts, FogStack readiness, office/browser diagnostics.

Initial implementation slice

• Add the six schemas.
• Add one example per schema.
• Update schemas/README.md.
• Add a minimal validator/checker if this repo already has validation tooling.
• Do not overfit to macOS names; preserve generic SourceOS contract semantics and allow platform-specific mappings through evidence refs and adapters.

[mdheller]

Parsed log loop/cadence findings

I parsed the uploaded macOS/BearBrowser log as an ordered event stream rather than a category bag.

Scope parsed:

• Structured events: 4,723
• Window: 22:35:44.321–22:37:54.947
• Span: ~130.6 seconds
• Interpretation: multiple overlapping loops, with clear phase transitions from permission denial -> network/identity degradation -> registry/experiment maintenance storms -> BearBrowser/WebKit child-process failure loops.

Dominant loop signatures

Signature	Count	First → Last	Span	Median cadence	Max events in 1s	Meaning
experiment:triald_system:missing_namespace_descriptor	492	22:37:00.211 → 22:37:18.801	18.6s	4.5ms	136	triald_system missing treatment namespace descriptors
experiment:triald:missing_namespace_descriptor	492	22:37:02.457 → 22:37:21.543	19.1s	4.5ms	136	triald user/session process repeats same missing descriptor loop
registry:deleted:lsbundle_record_missing	201	22:37:00.207 → 22:37:19.058	18.9s	9.6ms	51	LaunchServices bundle/extension registry storm
capability_denial:blockblock:fda_tcc	176	22:35:44.322 → 22:37:54.664	130.3s	556ms	2	BlockBlock repeatedly retries without Full Disk Access
capability_denial:kernel:user_permission_connect	176	22:35:44.321 → 22:37:54.664	130.3s	557ms	2	Kernel mirrors the same permission-denied polling loop
experiment:triald_system:missing_file_read	168	22:37:00.210 → 22:37:18.799	18.6s	8.7ms	42	triald_system missing-file sweep
experiment:triald:missing_file_read	168	22:37:02.456 → 22:37:21.542	19.1s	16.1ms	42	triald missing-file sweep
network:mdns:ipv4_broken_pipe	166	22:36:00.607 → 22:37:53.986	113.4s	0.19ms burst median	17	mDNS sends hit repeated broken pipes
security_verdict:lulu:no_current_verdict	151	22:35:59.628 → 22:37:54.447	114.8s	24.1ms	35	LuLu sees flows but cannot attach verdicts
maintenance:deleted:process_test_failures_null	131	22:37:00.510 → 22:37:22.912	22.4s	25.6ms	22	deleted emits null processTestFailures loop
network_observer:symptomsd:unexpected_radio_technology	99	22:35:59.639 → 22:36:23.637	24.0s	0.15ms burst median	33	radio/baseband identity unknown loop
network_observer:wifianalyticsd:ioreporter_failure	83	22:36:04.028 → 22:37:51.962	107.9s	0.04ms burst median	9	Wi-Fi analytics IOReporter/group sampling failure
network:mdns:platform_send_udp_broken_pipe	82	22:36:16.974 → 22:37:50.977	94.0s	0.25ms burst median	28	mDNSPlatformSendUDP broken-pipe storm
registry:pkd:extension_point_record_missing	47	22:37:00.777 → 22:37:20.442	19.7s	4.3ms	9	PlugInKit extension-point registry failure
network_observer:symptomsd:nil_device_id	45	22:36:02.662 → 22:37:53.987	111.3s	1.6ms burst median	15	symptomsd cannot record DNS/DHCP because device identity is nil
browser:bearbrowser:webcontent_invalid_connection_id	45	22:37:03.136 → 22:37:27.909	24.8s	0.04ms burst median	18	BearBrowser WebContent repeatedly operates on invalid XPC connection

Critical chronological transitions

1. 22:35:44 — BlockBlock enters a permission-denied polling loop. It repeats every ~0.56s for the whole captured window.
2. 22:35:47 — SearchParty CloudKit zone creation begins retrying under network loss.
3. 22:35:58 — LuLu extension identity/provisioning fails: unsatisfied entitlement + no matching profile.
4. 22:35:59 — LuLu starts no-verdict flow-closure storms; syspolicyd/trustd hit unconnected/closed socket paths.
5. 22:36:02 — mDNS/symptomsd/wifivelocityd enter network-observer failure mode: broken pipe, nil device ID, notification-service invalidation, ticker not active.
6. 22:36:15 — Wi-Fi analytics explicitly says device has not been unlocked since boot, then exits with nil analytics client. This is a boot/session phase gate breach.
7. 22:36:16–22:36:20 — Wi-Fi state becomes internally contradictory: radio active, no connected network, GET SSID failures, route/no-route failures, captive credentials missing, route already exists.
8. 22:36:19–22:36:21 — AppSSO, FindMy, FileProvider, preferences, pasteboard, and receipt checks show registry/config/desktop-service failure.
9. 22:37:00 — deleted/triald/pkd/LaunchServices enter high-frequency registry/experiment maintenance storm.
10. 22:37:02–22:37:03 — BearBrowser/WebKit child-process graph begins failing: analyticsd denied, CoreServices/LaunchServices denied, pasteboard denied, RunningBoard denied, invalid product/bundle identity, networkd settings denied, extension discovery cancelled, database migration/foreign-key failures.
11. 22:37:13–22:37:27 — the BearBrowser WebContent launch-failure sequence repeats with new child PIDs, proving this is not a single child failure but a respawn/retry loop.
12. 22:37:09+ — AppleKeyStore locked errors appear inside deleted, confirming some maintenance work is touching locked/pre-unlock material.

New contracts to add to this issue

The initial six schemas are still valid. Add these additional contract records or sub-record families:

RetryLoopFingerprint

Captures:

• signature
• sourceComponent
• firstSeen
• lastSeen
• count
• medianIntervalMs
• maxEventsPerSecond
• retryClass: polling | burst | backoff | sweep | respawn | unknown
• terminalState: resolved | still-looping | suppressed | quarantined | escalated | unknown
• policyValidity: expected | unexpected | denied-correctly | denied-but-noisy | invalid-retry

RuntimeIdentityGraph

Captures PID/helper/process identity continuity:

• app id
• package/bundle id
• executable digest
• helper kind
• audit-token identity
• broker relationship
• parent/child process relationship
• profile/session id
• identity-verification verdict

This directly targets invalid product id, couldn't get app identifier for audit token, Two equal instances have unequal identities, and invalid bundle records.

DesktopServiceBrokerState

Captures brokered access to:

• pasteboard
• LaunchServices / app opener
• CoreServices equivalent
• FileProvider equivalent
• notification broker
• extension registry
• intents/shortcut broker
• network-settings broker
• credential prompt broker

This prevents browser/terminal children from directly discovering missing authority through crashes.

BrowserLaunchTransaction

Captures browser launch as an atomic preflight:

1. app identity valid
2. profile store valid
3. helper identities valid
4. desktop brokers available/degraded
5. extension registry scanned/quarantined
6. network truth snapshot captured
7. WebContent/GPU/Networking spawn allowed
8. child process attested
9. page load begins

If any gate fails, the browser enters named degraded mode before spawning child processes.

MaintenanceEpoch

Captures background sweeps:

• cache delete
• trial/config refresh
• cleanup/deleted
• backup
• indexing
• plugin scanning
• cloud purge

Fields should include allowedDuringInteractiveLaunch, emissionBudget, lockRequirements, bootPhaseRequirement, and suppressionPolicy.

SecurityVerdictState

Captures network/security flow verdict availability:

• allow
• deny
• ask
• defer
• no-verdict-provider
• provider-invalid
• provider-not-ready
• policy-unavailable
• evidence-insufficient

This makes LuLu-style “No current verdict available” a typed security state, not a string in a storm.

Acceptance-test additions

1. A BlockBlock-like denied capability loop must collapse into one RetryLoopFingerprint with count/cadence, not hundreds of unrelated rows.
2. A LuLu-like invalid extension must chain: identity failure -> provider invalid -> no-verdict state.
3. A mDNS/symptomsd degraded network must represent radio active + no connected network + nil device ID + no route + DNS/DHCP observer failure.
4. A deleted/triald maintenance sweep must be represented as a MaintenanceEpoch with storm budgets.
5. A BearBrowser WebContent respawn loop must produce a BrowserLaunchTransaction failure before child-process crashes repeat.
6. A locked/pre-unlock access attempt must be rejected by BootSessionPhaseState, not retried until unlock/session transition.

Implementation priority

Priority order after parsing:

1. RetryLoopFingerprint
2. SecurityVerdictState
3. NetworkTruthState
4. RuntimeIdentityGraph
5. DesktopServiceBrokerState
6. BrowserLaunchTransaction
7. MaintenanceEpoch
8. DiagnosticStormRecord
9. RuntimeRegistryIntegrityRecord
10. BootSessionPhaseState

The revised scope is no longer just capability contracts. It is a full transparent runtime-causality layer.