From b603f62ba8a01830a784e829108ed2139a7e52f1 Mon Sep 17 00:00:00 2001 From: Michael Heller <21163552+mdheller@users.noreply.github.com> Date: Sat, 18 Jul 2026 17:11:26 -0400 Subject: [PATCH] feat: add CapabilityContract, CapabilityGrantState, ExactnessArtifactRecord, StaleStateRecord, LocalReasoningFailure schemas + Systema contract mappings + State Integrity program (closes #92, #97, #83, #103) --- .../systema-capability-radius.md | 31 +++++ .../systema-membrane-boundary.md | 31 +++++ .../systema-projection-loss.md | 29 +++++ .../systema-source-confidence.md | 32 +++++ docs/sourceos-state-integrity-program.md | 103 ++++++++++++++++ examples/capabilitycontract.bearbrowser.json | 32 +++++ .../capabilitygrantstate.bearbrowser.json | 43 +++++++ ...actnessartifactrecord.package-version.json | 16 +++ ...ocalreasoningfailure.string-exactness.json | 20 ++++ .../stalestaterecord.checksum-mismatch.json | 13 ++ schemas/CapabilityContract.json | 113 ++++++++++++++++++ schemas/CapabilityGrantState.json | 107 +++++++++++++++++ schemas/ExactnessArtifactRecord.json | 90 ++++++++++++++ schemas/LocalReasoningFailure.json | 98 +++++++++++++++ schemas/StaleStateRecord.json | 94 +++++++++++++++ 15 files changed, 852 insertions(+) create mode 100644 docs/contract-additions/systema-capability-radius.md create mode 100644 docs/contract-additions/systema-membrane-boundary.md create mode 100644 docs/contract-additions/systema-projection-loss.md create mode 100644 docs/contract-additions/systema-source-confidence.md create mode 100644 docs/sourceos-state-integrity-program.md create mode 100644 examples/capabilitycontract.bearbrowser.json create mode 100644 examples/capabilitygrantstate.bearbrowser.json create mode 100644 examples/exactnessartifactrecord.package-version.json create mode 100644 examples/localreasoningfailure.string-exactness.json create mode 100644 examples/stalestaterecord.checksum-mismatch.json create mode 100644 schemas/CapabilityContract.json create mode 100644 schemas/CapabilityGrantState.json create mode 100644 schemas/ExactnessArtifactRecord.json create mode 100644 schemas/LocalReasoningFailure.json create mode 100644 schemas/StaleStateRecord.json diff --git a/docs/contract-additions/systema-capability-radius.md b/docs/contract-additions/systema-capability-radius.md new file mode 100644 index 0000000..37c79cb --- /dev/null +++ b/docs/contract-additions/systema-capability-radius.md @@ -0,0 +1,31 @@ +# Systema: Capability Radius Mapping to SourceOS Typed Contracts + +## What Systema defines + +Systema's `capability_radius_profile.yaml` models the bounded scope within which an agent or component may exercise capabilities: a spatial/contextual radius beyond which capability requests are automatically denied, regardless of individual capability grants. + +## Existing SourceOS/SociOS coverage + +| Systema concept | SourceOS/SociOS schema | Key fields | +|---|---|---| +| Agent capability scope bound | `AgentCapabilityLease` | `scopedCapabilities`, `contextConstraints`, `expiresAt` | +| Session-scoped capability | `AgentSession` | `grantRefs`, `scopeRef` | +| Component-level radius | `CapabilityContract` | `declaredCapabilities[].fallback` | +| Runtime enforcement | `CapabilityGrantState` | `capabilityStates[].decision` | +| Policy-governed radius | `ExecutionDecision` | `verdict`, `policyRef`, `scopeRef` | +| Radius violation evidence | `LocalReasoningFailure.failureClass: policy-inference-bypass` | suppresses out-of-radius mutation | + +## Gap: radius boundary document + +Systema's radius profile is a named, versioned, reusable boundary document. The closest match is `CapabilityPolicy`, which governs a set of grant rules. A Systema radius profile maps directly to a `CapabilityPolicy` with a `radiusScope` annotation — no new schema required. + +## Mapping rules + +1. Systema `capability_radius.scope` → `AgentCapabilityLease.contextConstraints` (agent) or `CapabilityContract.declaredCapabilities` (component). +2. Systema radius violation → `CapabilityGrantState.capabilityStates[].decision: denied` + `policyRuleRef` pointing to the radius policy + emit `LocalReasoningFailure.failureClass: policy-inference-bypass` with `suppressMutation: true`. +3. Systema radius expiry → `AgentCapabilityLease.expiresAt`; post-expiry attempts → `CapabilityGrantState.decision: unavailable`. +4. Cross-device radius extension → requires new `AgentCapabilityLease` with `grantRefs` from the target device's policy fabric; no ambient inheritance. + +## No new schemas required + +Systema capability-radius semantics are fully covered by `AgentCapabilityLease`, `CapabilityContract`, `CapabilityGrantState`, `CapabilityPolicy`, `ExecutionDecision`, and `LocalReasoningFailure`. diff --git a/docs/contract-additions/systema-membrane-boundary.md b/docs/contract-additions/systema-membrane-boundary.md new file mode 100644 index 0000000..ce8572b --- /dev/null +++ b/docs/contract-additions/systema-membrane-boundary.md @@ -0,0 +1,31 @@ +# Systema: Membrane Boundary Mapping to SourceOS Typed Contracts + +## What Systema defines + +Systema's `membrane_boundary_profile.yaml` defines isolation boundaries between system zones: what may cross a membrane (data, events, capability grants), under what conditions, and what evidence is required to authorize a crossing. + +## Existing SourceOS/SociOS coverage + +| Systema concept | SourceOS/SociOS schema | Key fields | +|---|---|---| +| Capability crossing authorization | `CapabilityContract` + `CapabilityGrantState` | `declaredCapabilities`, `decision`, `grantSource` | +| Policy-governed event admission | `ExecutionDecision` | `policyRef`, `verdict`, `rationale` | +| Component isolation boundary | `CapabilityContract.minimumBootPhase` | phase-gating before crossing | +| Sandboxed child process limits | `CapabilityGrantState.capabilityStates[].grantSource: broker` | broker-mediated crossing | +| Cross-device sync admission | `SyncConflictRecord` + `SyncCycleReceipt` | governed crossing record | +| Agent capability radius | `AgentCapabilityLease` | `scopedCapabilities`, `expiresAt`, `revokedAt` | + +## Gap: membrane crossing event record + +Systema's membrane boundary profile can emit a crossing event with a before/after zone label that has no direct match in current schemas. Additive resolution: `SourceChannelEnvelope.channelPolicy` already captures routing authorization; a `membraneCrossingRef` annotation on `EventEnvelope` (optional string) can link to the governing `CapabilityGrantState` or `ExecutionDecision` without a new schema. + +## Mapping rules + +1. Systema membrane `denied` crossing → `CapabilityGrantState.capabilityStates[].decision: denied` + emit `DiagnosticStormRecord` if repeated. +2. Systema membrane `admitted` crossing → `CapabilityGrantState.capabilityStates[].decision: granted`, reference `ExecutionDecision` as policyRuleRef. +3. Agent membrane crossings → `AgentCapabilityLease` governs; Systema capability-radius is the outer bound. +4. Boot-phase membrane → `CapabilityContract.minimumBootPhase` enforced by `BootSessionPhaseState`. + +## No new schemas required + +All membrane boundary semantics are expressible through `CapabilityContract`, `CapabilityGrantState`, `ExecutionDecision`, `AgentCapabilityLease`, `BootSessionPhaseState`, `SourceChannelEnvelope`, and `DiagnosticStormRecord`. diff --git a/docs/contract-additions/systema-projection-loss.md b/docs/contract-additions/systema-projection-loss.md new file mode 100644 index 0000000..be05821 --- /dev/null +++ b/docs/contract-additions/systema-projection-loss.md @@ -0,0 +1,29 @@ +# Systema: Projection Loss Mapping to SourceOS Typed Contracts + +## What Systema defines + +Systema's `projection_loss_profile.yaml` models the degradation between a source truth and its projected representation: information loss during transformation, summarization, embedding, or model inference. A `projectionLoss` score of 0.0 is lossless; 1.0 is total loss. + +## Existing SourceOS/SociOS coverage + +| Systema concept | SourceOS/SociOS schema | Key fields | +|---|---|---| +| Render-time projection state | `ReasoningAssay` | `projectedState`, `assay()` (recomputed from axes — not stored) | +| Transformation evidence | `ProvenanceRecord` | `transformationRef`, `method` | +| Session context boundary | `SessionReceipt` | `contextRef`, `boundaryPolicy` | +| Memory hydration staleness | `LocalReasoningFailure` | `contextHydrationBoundary.staleSinceEventTime` | + +## Gap: projection-loss scalar on emitted artifacts + +Systema tracks a per-artifact `projectionLoss` that has no direct field in current schemas. Additive resolution: `ReasoningAssay.binding` already encodes verifiability strength (a proxy for projection integrity). For cases where a numeric score is needed, add an optional `projectionLossScore: number` to `ReasoningReceipt.assay` — backward-compatible, not required. + +## Mapping rules + +1. Systema `projectionLoss > 0.3` on a model-derived value targeting an exactness-sensitive field → `LocalReasoningFailure.failureClass: stale-context-injection` must be raised. +2. Systema `projectionLoss > 0.7` → `ReasoningAssay.projectedState` must be `bad`; downstream systems must not apply the value to durable state. +3. Systema summarization boundary events map to `LocalReasoningFailure.contextHydrationBoundary.boundaryViolated: true`. +4. Lossless projections (score 0.0, cryptographic source) → `ExactnessArtifactRecord.admissionPolicy: cryptographic-proof`. + +## No new schemas required + +Projection-loss semantics are covered by `ReasoningAssay`, `ReasoningReceipt`, `LocalReasoningFailure`, and `ExactnessArtifactRecord`. Systema adapters emit these rather than separate projection-loss schemas. diff --git a/docs/contract-additions/systema-source-confidence.md b/docs/contract-additions/systema-source-confidence.md new file mode 100644 index 0000000..43c9578 --- /dev/null +++ b/docs/contract-additions/systema-source-confidence.md @@ -0,0 +1,32 @@ +# Systema: Source Confidence Mapping to SourceOS Typed Contracts + +## What Systema defines + +Systema's `source_confidence_profile.yaml` models the trustworthiness of a data source across axes: recency, provenance, verifiability, and authority. It produces a scalar confidence score and a named confidence tier (`high`, `medium`, `low`, `unverified`). + +## Existing SourceOS/SociOS coverage + +The following schemas already carry source-confidence semantics: + +| Systema concept | SourceOS/SociOS schema | Key fields | +|---|---|---| +| Source provenance | `ProvenanceRecord` | `sourceRef`, `authorityRef`, `method`, `verifiedAt` | +| Confidence score on an event | `EventEnvelope` | `integrity`, `actor`, `authorityRef` | +| Verifier attestation | `ValidatorReceipt` | `decision`, `confidence`, `verifierRef`, `evidenceRefs` | +| Release-time source quality | `ReleaseReceipt` | `buildEvidenceRef`, `signatureRef` | +| Assay verdict | `ReasoningAssay` | `binding`, `method`, `agreement`, `authority`, `projectedState` | + +## Gap: runtime source-confidence metadata on local objects + +Systema's `source_confidence_profile.yaml` can emit per-object confidence tiers that are not currently surfaced in `ProvenanceRecord` or `EventEnvelope`. Additive resolution: annotate `StaleStateRecord.stalenessRisk` and `ExactnessArtifactRecord.stalenessRisk` with the Systema confidence tier as an optional `sourceConfidenceTier` field (no breaking changes). + +## Mapping rules + +1. Systema `confidence >= 0.85` → `ExactnessArtifactRecord.admissionPolicy: verifier-required` is satisfiable with `ValidatorReceipt`. +2. Systema `confidence < 0.5` → `StaleStateRecord.stalenessClass: stale-context-injection` should be emitted. +3. Systema `tier: unverified` + exactness-sensitive field → `LocalReasoningFailure.failureClass: string-exactness-violation` must be raised and `suppressMutation: true`. +4. Systema confidence axes map to `ReasoningAssay` axes: recency→`binding`, authority→`authority`, verifiability→`verifier`. + +## No new schemas required + +All Systema source-confidence semantics can be expressed through the existing `ProvenanceRecord`, `ValidatorReceipt`, `ReasoningAssay`, `StaleStateRecord`, and `ExactnessArtifactRecord` schemas. Systema adapters should emit these records rather than creating parallel ProCybernetica confidence schemas. diff --git a/docs/sourceos-state-integrity-program.md b/docs/sourceos-state-integrity-program.md new file mode 100644 index 0000000..43a799b --- /dev/null +++ b/docs/sourceos-state-integrity-program.md @@ -0,0 +1,103 @@ +# SourceOS State Integrity Implementation Program + +## Decision: Implementation Home + +**`SourceOS-Linux/sourceos-syncd`** is the implementation home for the SourceOS State Integrity daemon (`sourceos-syncd`). The repo exists and is seeded. MVP scope is locked below. + +## What This Is + +Not commodity file sync. The local-first state integrity layer: provenance, repair, profile isolation, policy-governed replication, and agent-operable state. Every object the SourceOS estate manages — files, packages, configs, models, agent sessions, boot profiles — has a record that answers the ten questions below. No object is mutable by model inference alone. + +## The Ten Questions Every Object Must Answer + +1. What is this object? (identity + schema) +2. Which schema governs it? (schema registry) +3. Who or what last changed it? (actor registry + provenance) +4. Which device and profile own it? (device identity + enrollment profile) +5. Is it safe to sync? (conflict record + stale-state record) +6. Why is it blocked? (policy decision + diagnostic record) +7. What conflicts exist? (sync conflict record) +8. What can be repaired automatically? (repair plan, autoRepairEligible) +9. What requires human review? (repair plan, requiresHumanReview) +10. What data is durable vs rebuildable? (durability classification) + +## MVP Scope (locked) + +The MVP can be declared done when it can answer all ten questions for at least one file object and one agent actor path from structured state (not filesystem scan). + +### MVP Object Model +- **LocalObjectRecord**: id, schemaRef, actorRef, deviceRef, durabilityClass, syncPolicy, stalenessRisk +- **ActorRecord**: id, kind (human | agent | daemon | ci), identityRef, sessionRef +- **SchemaRecord**: id, $id (JSON Schema), version, governingPolicy +- **LocalEventLog**: append-only JSONL, one entry per mutation, keyed by objectId + actorId + timestamp +- **ConflictRecord**: uses `SyncConflictRecord` from sourceos-spec +- **RepairPlan**: id, objectRef, steps[], autoRepairEligible, requiresHumanReview + +### MVP CLI Surface +``` +sourceos-syncd status # overall estate health +sourceos-syncd doctor # per-object staleness report +sourceos-syncd object # answer the ten questions for one object +sourceos-syncd repair # execute autoRepairEligible repair plans +sourceos-syncd log # show append-only event log for one object +``` + +### MVP Adapters (one each) +- **File/workspace object adapter**: index a file under `~/.sourceos/objects/` +- **Agent actor path**: record agent session mutations via `AgentSession` + `ProvenanceRecord` + +### MVP Policy Hook (one) +- On mutation attempt: check `ExactnessArtifactRecord.admissionPolicy`; if `verifier-required`, demand a `ValidatorReceipt` before committing + +### MVP Conflict Type (one) +- `checksum-mismatch` on a local file — detected on read, resolved by re-download or user review + +### MVP Repair Path (one) +- Derived index corruption: re-index from source file, emit `StaleStateRecord` with `autoRepairEligible: true`, execute repair, emit `ValidatorReceipt` + +### MVP Observability +- Emit `OpsHistoryEvent` on every state transition +- Emit `DiagnosticStormRecord` on repeated failures (> 3 in 60s window) + +### MVP Status Surfaces +- `SourceOS-Linux/TurtleTerm`: show per-object status in agent reliability session monitor +- `SourceOS-Linux/sourceos-shell`: `sourceosctl status` reads from `sourceos-syncd status` + +## Lane Ownership + +| Lane | Repo | +|---|---| +| Boot integrity | `SourceOS-Linux/sourceos-boot` | +| Developer tooling | `SourceOS-Linux/sourceos-devtools` | +| Workspace surface | `SocioProphet/sourceos-workspace` | +| Agent plane | `SocioProphet/agentplane` | +| Policy | `SocioProphet/policy-fabric` | +| Memory | `SocioProphet/memory-mesh` | +| Cloud/fog shell | `SocioProphet/cloudshell-fog` | +| Terminal | `SourceOS-Linux/TurtleTerm` | +| Observability | `SourceOS-Linux/sourceos-syncd` | +| Model artifacts | `SourceOS-Linux/sourceos-model-carry` | + +## Typed Contract References (all in sourceos-spec) + +- `StaleStateRecord` — staleness detection +- `ExactnessArtifactRecord` — exactness-sensitive field admission +- `LocalReasoningFailure` — reasoning-derived errors, suppression +- `SyncConflictRecord` — conflict representation +- `SyncCycleReceipt` — sync operation evidence +- `ValidatorReceipt` / `ValidatorDecision` — deterministic verification +- `ProvenanceRecord` — actor + mutation lineage +- `OpsHistoryEvent` — state transition observability +- `DiagnosticStormRecord` — repeated failure suppression +- `AgentCapabilityLease` — agent mutation scope +- `PolicyDecision` — admission gate decisions +- `DeviceIdentity` — per-device object ownership +- `RepairPlan` — (to be added as thin wrapper over existing repair schemas) + +## What Is Not MVP + +- Multi-device sync (post-MVP) +- Full estate rollout (post-MVP: `sourceos-syncd #2`) +- Noise-budget engine (`sourceos-syncd #8`) +- Operator narrative dashboard (`sourceos-syncd #9`) +- Metadata Coherence Plane epic (`sourceos-syncd #23`) diff --git a/examples/capabilitycontract.bearbrowser.json b/examples/capabilitycontract.bearbrowser.json new file mode 100644 index 0000000..da3c1a9 --- /dev/null +++ b/examples/capabilitycontract.bearbrowser.json @@ -0,0 +1,32 @@ +{ + "id": "urn:srcos:capability-contract:bearbrowser-main-v0-1", + "type": "CapabilityContract", + "specVersion": "v0.1", + "componentRef": "ai.socioprophet.BearBrowser", + "componentKind": "app", + "declaredCapabilities": [ + { + "capability": "full-disk-access", + "requiredFor": "indexing user documents for local search", + "fallback": "degraded", + "userVisibleImpact": "Document search will not index files outside the browser download directory." + }, + { + "capability": "pasteboard", + "requiredFor": "copy/paste between browser and native apps", + "fallback": "skip", + "userVisibleImpact": "Clipboard integration will be unavailable." + }, + { + "capability": "network", + "requiredFor": "web browsing and mesh connectivity", + "fallback": "degraded", + "userVisibleImpact": "Browser will operate in offline/local-only mode." + } + ], + "requiredBrokers": ["com.apple.TCC", "com.apple.lsd"], + "minimumBootPhase": "unlocked-user-session", + "degradedModePolicy": "continue-limited", + "userVisibleImpact": "Some BearBrowser features will be unavailable if capabilities are not granted.", + "evidenceRefs": ["urn:srcos:diagnostic-storm:bearbrowser-tcc-denials-2025-q4"] +} diff --git a/examples/capabilitygrantstate.bearbrowser.json b/examples/capabilitygrantstate.bearbrowser.json new file mode 100644 index 0000000..b1a7c74 --- /dev/null +++ b/examples/capabilitygrantstate.bearbrowser.json @@ -0,0 +1,43 @@ +{ + "id": "urn:srcos:capability-grant-state:bearbrowser-main-v0-1-boot-20260101", + "type": "CapabilityGrantState", + "specVersion": "v0.1", + "contractRef": "urn:srcos:capability-contract:bearbrowser-main-v0-1", + "observedAt": "2026-01-01T09:00:00Z", + "bootId": "boot-20260101-abc123", + "sessionId": "session-mdheller-001", + "permissionEpoch": "tcc-epoch-2026-01-01", + "capabilityStates": [ + { + "capability": "full-disk-access", + "requestedOperation": "read", + "subjectRef": "ai.socioprophet.BearBrowser", + "objectRef": "/Users/mdheller/Documents", + "grantSource": "user-consent", + "decision": "denied", + "policyRuleRef": "urn:srcos:policy:tcc-default-deny", + "fallback": "degraded", + "userVisibleImpact": "Document search limited to ~/Downloads.", + "remediationHint": "Grant Full Disk Access in System Settings > Privacy & Security." + }, + { + "capability": "pasteboard", + "requestedOperation": "read", + "subjectRef": "ai.socioprophet.BearBrowser.WebContent", + "objectRef": "com.apple.pasteboard", + "grantSource": "broker", + "decision": "denied", + "fallback": "skip", + "userVisibleImpact": "Clipboard paste from web pages unavailable.", + "remediationHint": "This is a sandboxed child process limitation." + }, + { + "capability": "network", + "requestedOperation": "connect", + "subjectRef": "ai.socioprophet.BearBrowser.Networking", + "objectRef": "mesh.socioprophet.ai", + "grantSource": "ambient-host", + "decision": "granted" + } + ] +} diff --git a/examples/exactnessartifactrecord.package-version.json b/examples/exactnessartifactrecord.package-version.json new file mode 100644 index 0000000..d9bedca --- /dev/null +++ b/examples/exactnessartifactrecord.package-version.json @@ -0,0 +1,16 @@ +{ + "id": "urn:srcos:exactness-artifact:noetica-pkg-version-0-4-23", + "type": "ExactnessArtifactRecord", + "specVersion": "v0.1", + "artifactKind": "version", + "value": "0.4.23", + "sourceKind": "package-db", + "verifierRef": "urn:srcos:validator-receipt:brew-info-noetica-0-4-23", + "admissionPolicy": "verifier-required", + "validityInterval": { + "validFrom": "2026-07-01T00:00:00Z", + "refreshPolicy": "on-package-update" + }, + "stalenessRisk": "none", + "contextObjectRef": "urn:srcos:package:noetica" +} diff --git a/examples/localreasoningfailure.string-exactness.json b/examples/localreasoningfailure.string-exactness.json new file mode 100644 index 0000000..7eaf3a2 --- /dev/null +++ b/examples/localreasoningfailure.string-exactness.json @@ -0,0 +1,20 @@ +{ + "id": "urn:srcos:local-reasoning-failure:model-hallucinated-package-name-20260718", + "type": "LocalReasoningFailure", + "specVersion": "v0.1", + "failureClass": "string-exactness-violation", + "affectedObjectRef": "urn:srcos:package:noetica", + "affectedField": "name", + "incorrectValue": "noetica-ai", + "expectedValueHint": "noetica (verified via brew info noetica)", + "detectedAt": "2026-07-18T14:00:00Z", + "detectedBy": "urn:srcos:component:sourceos-devtools-validator", + "contextHydrationBoundary": { + "contextWindowId": "ctx-turn-42", + "staleSinceEventTime": "2026-07-10T00:00:00Z", + "hydrationSource": "model-cache", + "boundaryViolated": true + }, + "verifierRef": "urn:srcos:validator-receipt:brew-name-check-noetica", + "suppressMutation": true +} diff --git a/examples/stalestaterecord.checksum-mismatch.json b/examples/stalestaterecord.checksum-mismatch.json new file mode 100644 index 0000000..1a277cc --- /dev/null +++ b/examples/stalestaterecord.checksum-mismatch.json @@ -0,0 +1,13 @@ +{ + "id": "urn:srcos:stale-state:agent-machine-bin-checksum-mismatch-20260718", + "type": "StaleStateRecord", + "specVersion": "v0.1", + "objectRef": "urn:srcos:artifact:agent-machine-bin-0-3-1", + "stalenessClass": "checksum-mismatch", + "observedAt": "2026-07-18T14:30:00Z", + "eventTime": "2026-07-18T14:25:00Z", + "validFrom": "2026-07-01T00:00:00Z", + "repairPlanRef": "urn:srcos:repair-plan:re-download-agent-machine-bin", + "autoRepairEligible": true, + "evidenceRefs": ["urn:srcos:validator-receipt:sha256-check-agent-machine-bin-20260718"] +} diff --git a/schemas/CapabilityContract.json b/schemas/CapabilityContract.json new file mode 100644 index 0000000..ec4954c --- /dev/null +++ b/schemas/CapabilityContract.json @@ -0,0 +1,113 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/CapabilityContract.json", + "title": "CapabilityContract", + "description": "Declares what capabilities a SourceOS component requires before runtime, enabling policy-governed preflight checks and degraded-mode fallback planning.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "componentRef", + "componentKind", + "declaredCapabilities", + "minimumBootPhase", + "degradedModePolicy" + ], + "properties": { + "id": { + "type": "string", + "description": "URN of this contract. Format: urn:srcos:capability-contract:", + "pattern": "^urn:srcos:capability-contract:.+" + }, + "type": { + "type": "string", + "const": "CapabilityContract" + }, + "specVersion": { + "type": "string", + "description": "Schema version.", + "const": "v0.1" + }, + "componentRef": { + "type": "string", + "description": "URN or bundle identifier of the component this contract covers." + }, + "componentKind": { + "type": "string", + "description": "Kind of component.", + "enum": [ + "app", + "daemon", + "agent", + "browser-child", + "terminal-helper", + "network-observer", + "file-monitor", + "extension-host", + "indexer", + "broker" + ] + }, + "declaredCapabilities": { + "type": "array", + "description": "All capabilities this component may request at runtime.", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["capability", "requiredFor", "fallback"], + "properties": { + "capability": { + "type": "string", + "description": "Capability identifier, e.g. full-disk-access, network, pasteboard, keychain." + }, + "requiredFor": { + "type": "string", + "description": "Human-readable description of what feature needs this capability." + }, + "fallback": { + "type": "string", + "enum": ["degraded", "unavailable", "skip"], + "description": "Behavior when capability is not granted." + }, + "userVisibleImpact": { + "type": "string", + "description": "What the user observes when this capability is denied." + } + } + } + }, + "requiredBrokers": { + "type": "array", + "description": "Broker services this component depends on.", + "items": { "type": "string" } + }, + "minimumBootPhase": { + "type": "string", + "description": "Earliest boot/session phase in which this component may activate.", + "enum": [ + "sealed-boot", + "pre-login", + "post-login-locked", + "unlocked-user-session", + "degraded-session", + "recovery-session" + ] + }, + "degradedModePolicy": { + "type": "string", + "enum": ["continue-limited", "refuse-start", "emit-receipt-and-exit"], + "description": "What the component does when required capabilities are unavailable." + }, + "userVisibleImpact": { + "type": "string", + "description": "Top-level user-visible impact summary when any required capability is denied." + }, + "evidenceRefs": { + "type": "array", + "description": "URNs of evidence or incidents that informed this contract.", + "items": { "type": "string" } + } + } +} diff --git a/schemas/CapabilityGrantState.json b/schemas/CapabilityGrantState.json new file mode 100644 index 0000000..d6c34fb --- /dev/null +++ b/schemas/CapabilityGrantState.json @@ -0,0 +1,107 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/CapabilityGrantState.json", + "title": "CapabilityGrantState", + "description": "Captures the observed runtime grant state for each declared capability in a CapabilityContract, enabling policy audit and repair-plan linkage.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "contractRef", + "observedAt", + "bootId", + "capabilityStates" + ], + "properties": { + "id": { + "type": "string", + "description": "URN of this grant state record. Format: urn:srcos:capability-grant-state:", + "pattern": "^urn:srcos:capability-grant-state:.+" + }, + "type": { + "type": "string", + "const": "CapabilityGrantState" + }, + "specVersion": { + "type": "string", + "const": "v0.1" + }, + "contractRef": { + "type": "string", + "description": "URN of the CapabilityContract this record evaluates." + }, + "observedAt": { + "type": "string", + "format": "date-time", + "description": "When this grant state was observed." + }, + "bootId": { + "type": "string", + "description": "Boot session identifier." + }, + "sessionId": { + "type": "string", + "description": "User session identifier." + }, + "permissionEpoch": { + "type": "string", + "description": "Opaque epoch token representing the permission state at observation time." + }, + "capabilityStates": { + "type": "array", + "description": "Per-capability observed grant outcome.", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["capability", "decision"], + "properties": { + "capability": { + "type": "string", + "description": "Capability identifier matching the CapabilityContract." + }, + "requestedOperation": { + "type": "string", + "description": "Specific operation attempted (read, write, open, connect, etc.)." + }, + "subjectRef": { + "type": "string", + "description": "Component or process requesting the capability." + }, + "objectRef": { + "type": "string", + "description": "Resource or service targeted." + }, + "grantSource": { + "type": "string", + "enum": ["policy", "user-consent", "broker", "ambient-host", "kernel", "portal", "inherited", "unavailable"], + "description": "How the grant was (or was not) obtained." + }, + "decision": { + "type": "string", + "enum": ["granted", "denied", "ask", "degraded", "unavailable", "unknown"], + "description": "Observed grant decision." + }, + "policyRuleRef": { + "type": "string", + "description": "URN of the policy rule that produced this decision." + }, + "fallback": { + "type": "string", + "enum": ["degraded", "unavailable", "skip"], + "description": "Actual fallback applied." + }, + "userVisibleImpact": { + "type": "string", + "description": "What the user observed as a result." + }, + "remediationHint": { + "type": "string", + "description": "Actionable hint for restoring the capability." + } + } + } + } + } +} diff --git a/schemas/ExactnessArtifactRecord.json b/schemas/ExactnessArtifactRecord.json new file mode 100644 index 0000000..811190a --- /dev/null +++ b/schemas/ExactnessArtifactRecord.json @@ -0,0 +1,90 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/ExactnessArtifactRecord.json", + "title": "ExactnessArtifactRecord", + "description": "Metadata record for an exactness-sensitive artifact (ID, filename, checksum, signature, version, package name, config field, boot/release ref) that must not be derived from model text alone. Carries the deterministic verifier receipt that authorized its value.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "artifactKind", + "value", + "verifierRef", + "admissionPolicy" + ], + "properties": { + "id": { + "type": "string", + "description": "URN of this exactness record. Format: urn:srcos:exactness-artifact:", + "pattern": "^urn:srcos:exactness-artifact:.+" + }, + "type": { + "type": "string", + "const": "ExactnessArtifactRecord" + }, + "specVersion": { + "type": "string", + "const": "v0.1" + }, + "artifactKind": { + "type": "string", + "description": "Class of exactness-sensitive artifact.", + "enum": [ + "id", + "filename", + "checksum", + "signature", + "version", + "package-name", + "yaml-field", + "toml-field", + "json-field", + "config-field", + "boot-ref", + "release-ref", + "schema-ref" + ] + }, + "value": { + "type": "string", + "description": "The exact string value. Must originate from a deterministic source, not model inference." + }, + "sourceKind": { + "type": "string", + "enum": ["filesystem", "package-db", "registry", "network", "user-input", "cryptographic"], + "description": "How the value was obtained." + }, + "verifierRef": { + "type": "string", + "description": "URN of the ValidatorReceipt that confirmed this value by deterministic check." + }, + "admissionPolicy": { + "type": "string", + "enum": ["verifier-required", "user-confirmed", "cryptographic-proof"], + "description": "Policy governing how this value may be admitted into mutable state." + }, + "validityInterval": { + "type": "object", + "additionalProperties": false, + "properties": { + "validFrom": { "type": "string", "format": "date-time" }, + "validUntil": { "type": "string", "format": "date-time" }, + "refreshPolicy": { + "type": "string", + "enum": ["never", "on-boot", "on-package-update", "on-network-change", "ttl-based"] + } + } + }, + "stalenessRisk": { + "type": "string", + "enum": ["none", "low", "medium", "high", "stale"], + "description": "Current staleness assessment." + }, + "contextObjectRef": { + "type": "string", + "description": "URN of the parent object (file, package, config) this artifact belongs to." + } + } +} diff --git a/schemas/LocalReasoningFailure.json b/schemas/LocalReasoningFailure.json new file mode 100644 index 0000000..c94a7a7 --- /dev/null +++ b/schemas/LocalReasoningFailure.json @@ -0,0 +1,98 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/LocalReasoningFailure.json", + "title": "LocalReasoningFailure", + "description": "Records a local-first reasoning failure: a case where a model-derived value was presented as authoritative for an exactness-sensitive field, or where stale/contaminated context produced an incorrect output. Links to repair evidence and prevents the failure from being silently overwritten.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "failureClass", + "affectedObjectRef", + "detectedAt" + ], + "properties": { + "id": { + "type": "string", + "description": "URN of this failure record. Format: urn:srcos:local-reasoning-failure:", + "pattern": "^urn:srcos:local-reasoning-failure:.+" + }, + "type": { + "type": "string", + "const": "LocalReasoningFailure" + }, + "specVersion": { + "type": "string", + "const": "v0.1" + }, + "failureClass": { + "type": "string", + "enum": [ + "string-exactness-violation", + "checksum-mismatch", + "stale-context-injection", + "memory-contamination", + "conflicting-local-facts", + "schema-drift", + "counting-error", + "policy-inference-bypass" + ], + "description": "Class of reasoning failure." + }, + "affectedObjectRef": { + "type": "string", + "description": "URN of the object or artifact affected by the failure." + }, + "affectedField": { + "type": "string", + "description": "Specific field within the object that contains the erroneous value." + }, + "incorrectValue": { + "type": "string", + "description": "The model-derived or stale value that was incorrectly admitted." + }, + "expectedValueHint": { + "type": "string", + "description": "The correct value if known, or a pointer to where it can be determined." + }, + "detectedAt": { + "type": "string", + "format": "date-time", + "description": "When the failure was detected." + }, + "detectedBy": { + "type": "string", + "description": "Component or verifier that detected the failure." + }, + "contextHydrationBoundary": { + "type": "object", + "additionalProperties": false, + "description": "Memory/context hydration boundary metadata — what context was in scope when the failure occurred.", + "properties": { + "contextWindowId": { "type": "string" }, + "staleSinceEventTime": { "type": "string", "format": "date-time" }, + "hydrationSource": { "type": "string", "enum": ["memory-mesh", "local-index", "model-cache", "session-state", "unknown"] }, + "boundaryViolated": { "type": "boolean" } + } + }, + "repairPlanRef": { + "type": "string", + "description": "URN of repair plan that addresses this failure." + }, + "verifierRef": { + "type": "string", + "description": "URN of the deterministic verifier that confirmed the failure." + }, + "sourceChannelRef": { + "type": "string", + "description": "URN of the SourceChannelEnvelope that carried this failure for propagation." + }, + "suppressMutation": { + "type": "boolean", + "description": "When true, downstream components must not apply the incorrect value to durable state.", + "default": true + } + } +} diff --git a/schemas/StaleStateRecord.json b/schemas/StaleStateRecord.json new file mode 100644 index 0000000..3857cb0 --- /dev/null +++ b/schemas/StaleStateRecord.json @@ -0,0 +1,94 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/StaleStateRecord.json", + "title": "StaleStateRecord", + "description": "Records stale-state and validity-interval metadata for a SourceOS local object, distinguishing observed time, event time, and valid time, and linking to any repair plan.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "objectRef", + "stalenessClass", + "observedAt" + ], + "properties": { + "id": { + "type": "string", + "description": "URN of this stale-state record. Format: urn:srcos:stale-state:", + "pattern": "^urn:srcos:stale-state:.+" + }, + "type": { + "type": "string", + "const": "StaleStateRecord" + }, + "specVersion": { + "type": "string", + "const": "v0.1" + }, + "objectRef": { + "type": "string", + "description": "URN of the object whose state is stale." + }, + "stalenessClass": { + "type": "string", + "enum": [ + "validity-expired", + "checksum-mismatch", + "source-newer", + "conflict-detected", + "repair-pending", + "unresolvable" + ], + "description": "Why this object is considered stale." + }, + "observedAt": { + "type": "string", + "format": "date-time", + "description": "When the staleness was observed (observed time)." + }, + "eventTime": { + "type": "string", + "format": "date-time", + "description": "When the underlying event that caused staleness occurred." + }, + "validFrom": { + "type": "string", + "format": "date-time", + "description": "Start of the validity interval for the recorded state." + }, + "validUntil": { + "type": "string", + "format": "date-time", + "description": "End of the validity interval. Null means indefinite." + }, + "conflictRecord": { + "type": "object", + "additionalProperties": false, + "description": "Local-first contradiction record when two sources disagree.", + "properties": { + "localValue": { "type": "string" }, + "remoteValue": { "type": "string" }, + "conflictingSourceRef": { "type": "string" }, + "resolutionPolicy": { + "type": "string", + "enum": ["local-wins", "remote-wins", "manual-review", "verifier-arbitrates"] + } + } + }, + "repairPlanRef": { + "type": "string", + "description": "URN of the repair plan that addresses this stale-state record." + }, + "autoRepairEligible": { + "type": "boolean", + "description": "Whether the stale state can be repaired without human review." + }, + "evidenceRefs": { + "type": "array", + "items": { "type": "string" }, + "description": "URNs of evidence artifacts that detected or described the staleness." + } + } +}