Draft: add fog patch fragments and semantic seed

asyncapi.fog.patch.yaml

@@ -0,0 +1,146 @@
+# Additive AsyncAPI patch fragment for the Fog Layer.
+# Merge this file into asyncapi.yaml at build time using @asyncapi/bundler.
+# All channels use Kafka with the same broker configuration as the base spec.
+
+channels:
+  srcos.v2.fog.topic.events:
+    description: Events emitted when a FogVault topic is recorded or updated.
+    bindings:
+      kafka:
+        topic: srcos.v2.fog.topic.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishFogTopicEvent
+      summary: Publish a fog topic domain event
+      description: Publishes an event whenever a FogVault Topic is upserted.
+      message:
+        name: FogTopicEvent
+        title: Fog Topic Domain Event
+        summary: A change event for a FogVault Topic.
+        description: |
+          The `eventType` in the payload envelope identifies the specific change:
+          - `FogTopicUpserted`
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the Topic.
+
+  srcos.v2.fog.offer.events:
+    description: Events emitted when a FogCompute offer is recorded or updated.
+    bindings:
+      kafka:
+        topic: srcos.v2.fog.offer.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishFogOfferEvent
+      summary: Publish a fog offer domain event
+      description: Publishes an event whenever a FogCompute Offer is upserted.
+      message:
+        name: FogOfferEvent
+        title: Fog Offer Domain Event
+        summary: A change event for a FogCompute Offer.
+        description: |
+          The `eventType` in the payload envelope identifies the specific change:
+          - `FogOfferUpserted`
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the Offer.
+
+  srcos.v2.fog.workorder.events:
+    description: Events emitted when a FogCompute work order is submitted.
+    bindings:
+      kafka:
+        topic: srcos.v2.fog.workorder.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishFogWorkOrderEvent
+      summary: Publish a fog work order domain event
+      description: Publishes an event whenever a FogCompute WorkOrder is recorded.
+      message:
+        name: FogWorkOrderEvent
+        title: Fog WorkOrder Domain Event
+        summary: A record event for a FogCompute WorkOrder.
+        description: |
+          The `eventType` in the payload envelope is `FogWorkOrderRecorded`.
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the WorkOrder.
+
+  srcos.v2.fog.receipt.events:
+    description: Events emitted when a FogCompute usage receipt is recorded.
+    bindings:
+      kafka:
+        topic: srcos.v2.fog.receipt.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishFogUsageReceiptEvent
+      summary: Publish a fog usage receipt domain event
+      description: Publishes an event whenever a FogCompute UsageReceipt is recorded.
+      message:
+        name: FogUsageReceiptEvent
+        title: Fog Usage Receipt Domain Event
+        summary: A record event for a FogCompute UsageReceipt.
+        description: |
+          The `eventType` in the payload envelope is `FogUsageReceiptRecorded`.
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the UsageReceipt.
+
+  srcos.v2.fog.settlement.events:
+    description: Events emitted when a Fog settlement mapping is recorded.
+    bindings:
+      kafka:
+        topic: srcos.v2.fog.settlement.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishFogSettlementEvent
+      summary: Publish a fog settlement domain event
+      description: Publishes an event whenever a SettlementEvent is recorded.
+      message:
+        name: FogSettlementEvent
+        title: Fog Settlement Domain Event
+        summary: A record event for a Fog settlement mapping.
+        description: |
+          The `eventType` in the payload envelope is `FogSettlementRecorded`.
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the SettlementEvent.

docs/contract-additions/2026-04-fog-contract-index.md

@@ -0,0 +1,58 @@
+# Fog contract additions index
+
+- **Status:** bootstrap index
+- **Date:** 2026-04-16
+
+This document provides a discoverability layer for the initial FogVault / FogCompute contract additions landed in the typed-contract repository.
+
+## New schema types
+
+### FogVault (storage + topics)
+
+- `Topic.json`
+- `TopicEnvelope.json`
+- `ReplicationPolicy.json`
+- `ContentRef.json`
+
+### FogCompute (offers + execution evidence)
+
+- `Offer.json`
+- `WorkOrder.json`
+- `UsageReceipt.json`
+- `SettlementEvent.json`
+
+## Matching examples
+
+- `examples/topic.json`
+- `examples/topic_envelope.json`
+- `examples/replication_policy.json`
+- `examples/content_ref.json`
+- `examples/offer.json`
+- `examples/workorder.json`
+- `examples/usage_receipt.json`
+- `examples/settlement_event.json`
+
+## Why these additions exist
+
+These objects provide the first canonical contract surface for:
+
+- append-only Merkle-log topic channels
+- explicit replication and retention policy
+- content-addressed fog storage references
+- metered compute offers and work orders
+- signed execution receipts and optional settlement mapping
+
+## Relationship to existing schema families
+
+These additions extend the existing SourceOS/SociOS contract system rather than replacing it.
+
+- FogVault extends the execution / provenance story with durable topic and content-addressed storage semantics.
+- FogCompute extends the execution and agent/runtime story with provider offers, workload requests, and receipts.
+- Settlement remains a pluggable evidence layer rather than a mandatory control-plane dependency.
+
+## Intended next updates
+
+1. add dedicated OpenAPI / AsyncAPI fog patch fragments
+2. fold these objects into the schema catalog and repo README family tables
+3. add semantic overlay entries for fog vocabulary
+4. add stricter schema cross-linking once runtime semantics are finalized

openapi.fog.patch.yaml

@@ -0,0 +1,123 @@
+# Additive OpenAPI patch fragment for the Fog Layer (FogVault + FogCompute).
+# Merge this file into openapi.yaml at build time.
+# All operations require bearerAuth (inherited from the base spec security requirement).
+
+tags:
+  - name: Fog Layer
+    description: FogVault topic/storage contracts and FogCompute offers, work orders, and receipts
+
+paths:
+  /v2/fog/topics:
+    post:
+      operationId: upsertFogTopic
+      summary: Upsert a Fog topic definition
+      description: Creates or updates a FogVault Topic contract. Idempotent on `id`.
+      tags: [Fog Layer]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/Topic.json' }
+      responses:
+        '200':
+          description: Topic created or updated successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to upsert fog topics.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/fog/offers:
+    post:
+      operationId: upsertFogOffer
+      summary: Upsert a Fog compute offer
+      description: Creates or updates a FogCompute Offer. Idempotent on `id`.
+      tags: [Fog Layer]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/Offer.json' }
+      responses:
+        '200':
+          description: Offer created or updated successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to upsert fog offers.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/fog/workorders:
+    post:
+      operationId: submitFogWorkOrder
+      summary: Submit a Fog work order
+      description: Records a FogCompute WorkOrder. Idempotent on `id`.
+      tags: [Fog Layer]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/WorkOrder.json' }
+      responses:
+        '200':
+          description: WorkOrder recorded successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to submit fog work orders.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/fog/receipts:
+    post:
+      operationId: recordFogUsageReceipt
+      summary: Record a Fog usage receipt
+      description: Records a FogCompute UsageReceipt. Idempotent on `id`.
+      tags: [Fog Layer]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/UsageReceipt.json' }
+      responses:
+        '200':
+          description: UsageReceipt recorded successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to record fog receipts.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/fog/settlements:
+    post:
+      operationId: recordFogSettlementEvent
+      summary: Record a Fog settlement event
+      description: Records an optional SettlementEvent that maps a usage receipt to a settlement backend.
+      tags: [Fog Layer]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/SettlementEvent.json' }
+      responses:
+        '200':
+          description: SettlementEvent recorded successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to record fog settlements.
+        '422':
+          description: Request body is valid JSON but fails schema validation.

semantic/fog-vocabulary.jsonld

@@ -0,0 +1,21 @@
+{
+  "@context": {
+    "srcos": "https://schemas.srcos.ai/vocab#",
+    "Topic": "srcos:Topic",
+    "TopicEnvelope": "srcos:TopicEnvelope",
+    "ReplicationPolicy": "srcos:ReplicationPolicy",
+    "ContentRef": "srcos:ContentRef",
+    "Offer": "srcos:Offer",
+    "WorkOrder": "srcos:WorkOrder",
+    "UsageReceipt": "srcos:UsageReceipt",
+    "SettlementEvent": "srcos:SettlementEvent",
+    "topicId": "srcos:topicId",
+    "payloadType": "srcos:payloadType",
+    "replicas": "srcos:replicas",
+    "minAcks": "srcos:minAcks",
+    "digest": "srcos:digest",
+    "provider": "srcos:provider",
+    "workOrderId": "srcos:workOrderId",
+    "receiptId": "srcos:receiptId"
+  }
+}