if.bus — full stack whitepaper (single-file, offline-friendly)

Generated (UTC): 2026-01-22
Product ID: if.bus
Artifact kind: whitepaper_singlefile
Intended use: copy/paste into sandboxed reviewers that cannot fetch URLs

Online identifier (txt-first): https://infrafabric.io/llm/products/if-bus/full-stack-whitepaper/2026-01-22/index.md.txt

0. Black/white (verified vs not claimed)
1. What this document contains
2. Public review surfaces (URLs)
3. Current implementation in this repo (reference runtime)
4. Runtime posture (what external integrators can and cannot do)
5. Protocol summary (what an adapter must produce)
6. Control plane summary (pause/quarantine/replay)
7. DLQ summary (dead-letter envelope)
8. Pointer-only pattern (large payloads, redaction posture)
9. Full JSON Schemas (embedded)

0. Black/white (verified vs not claimed)

Verified (from this repo + public /llm mirrors):

if.bus status is preview with “internal-only sandbox runtime documented; no public bus endpoints claimed.”
A runtime spec pack and a sandbox runtime pack are published under /llm/products/if-bus/ (dated).
JSON Schemas for the bus envelope + control plane + DLQ are published under the runtime spec pack.
This repo contains a reference bus runtime implementation (if_bus_runtime/) with transports:
- in_memory
- nats_js (NATS JetStream via nats-py)

Not claimed by this document:

Any public, internet-reachable bus endpoint you can connect to without coordination.
Any “exactly once” delivery guarantee.
Any adapter registration service being publicly exposed.
Any real-time claims about runtime liveness beyond what is documented in the published packs.

1. What this document contains

This is a single-file consolidation of:

The public /llm review surfaces for if.bus (links only; one URL per line).
A “what to implement” adapter summary (envelope, routing, hashing, DLQ, control plane).
The current reference runtime implementation shape in this repo.
The JSON Schemas (embedded) used as the contract baseline.

2. Public review surfaces (URLs)

3. Current implementation in this repo (reference runtime)

Code location

if_bus_runtime/ is the reference runtime package in this repository.

Entry points

python3 -m if_bus_runtime --help (CLI)
if_bus_runtime/runtime.py (core runtime loop)
if_bus_runtime/transports/in_memory.py (local testing)
if_bus_runtime/transports/nats_js.py (NATS JetStream backend)

Supported transport kinds (as implemented)

in_memory (no broker; deterministic smoke tests)
nats_js (JetStream stream default: IFBUS, servers default: nats://127.0.0.1:4222)

Implemented behaviors (as of this repo state)

Validates incoming envelopes against schemas/if-bus/envelope.schema.json (optionally via --envelope-schema).
Produces a DLQ envelope on:
- schema violations
- quarantine
- pause/drain
- hold exceeding max_hold_attempts
- quota exceeded
Supports control commands with acks:
- pause / resume
- quarantine / unquarantine (alias: release)
- replay
Optional control-plane auth gate:
- enabled when runtime is configured with control_auth
- reference scheme is HMAC over canonical JSON bytes (details in schema + if_bus_runtime/control_auth.py)

4. Runtime posture (what external integrators can and cannot do)

What external integrators can do from public artifacts alone

Implement an envelope generator that emits valid if.bus.envelope JSON.
Implement validators using the embedded JSON Schemas (below).
Build adapters that assume NATS JetStream as one transport option, without claiming connectivity.
Build a “pointer-only” producer that emits payload_ref + payload_sha256 instead of large inline payloads.

What is not provided as a public contract (requires coordination)

Public broker connection details (host/port/creds).
Any public token issuance or adapter registration flow.
Any guarantee that topics are routable across networks from third-party environments.

Black/white: the public contract is the schemas + the published review packs; any connectivity details are environment-specific and may be intentionally private.

5. Protocol summary (what an adapter must produce)

5.1 Data-plane envelope (`if.bus.envelope`)

Required top-level fields (see schema for types):

schema_id (must be if.bus.envelope)
schema_version (semver string; baseline v1 is 1.0.0)
event_id (stable unique id)
emitted_utc (UTC timestamp)
producer (kind, id, optional version, optional instance)
event (name, optional op)
routing (topic, partition_key, optional priority, optional ttl_seconds)
payload_sha256 (sha256 of the canonical payload bytes, even if payload is omitted/redacted)

Recommended for robust workflows:

correlation (correlation_id, optional causation_id) to model request/response as correlated events.
payload_media_type (e.g., application/json).
payload_ref when payload is too large or must not be inlined.
extensions for additive growth without breaking v1 consumers (bounded by runtime limits).

5.2 Topic taxonomy

Reference topic shape:

if.bus.{tenant_id}.{environment}.{domain}.{event_type}

Notes:

tenant_id is required for isolation (multi-tenant posture).
environment is runtime-defined (examples: dev, staging, prod, preview, roadmap).
domain and event_type should be stable tokens (avoid churn).

5.3 Canonical bytes + hashing

Reference implementation canonical bytes (used in this repo runtime and CLI):

json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")

Black/white:

The spec recommends a single canonicalization rule so hashes are stable across runtimes.
This repo’s reference runtime uses the deterministic json.dumps(...) rule above as its baseline.

5.4 Minimal examples (publish-safe)

Data-plane envelope (inline payload example):

{
  "schema_id": "if.bus.envelope",
  "schema_version": "1.0.0",
  "event_id": "00000000-0000-0000-0000-000000000001",
  "emitted_utc": "2026-01-01T00:00:00Z",
  "producer": {
    "kind": "mcp.server",
    "id": "example-adapter",
    "version": "0.1.0"
  },
  "event": {
    "name": "example.event"
  },
  "routing": {
    "topic": "if.bus.demo.dev.example.event",
    "partition_key": "example",
    "priority": 5,
    "ttl_seconds": 60
  },
  "payload_media_type": "application/json",
  "payload": {
    "hello": "world",
    "seq": 1
  },
  "payload_sha256": "197edc9bbf42b71472da1d5af47c9df1e1d7dd92a45eed75c3a3132314c0c4ed",
  "extensions": {}
}

Data-plane envelope (pointer-only payload reference example):

{
  "schema_id": "if.bus.envelope",
  "schema_version": "1.0.0",
  "event_id": "00000000-0000-0000-0000-000000000002",
  "emitted_utc": "2026-01-01T00:00:00Z",
  "producer": {
    "kind": "mcp.server",
    "id": "example-adapter",
    "version": "0.1.0"
  },
  "event": {
    "name": "example.large_payload_event"
  },
  "routing": {
    "topic": "if.bus.demo.dev.example.large_payload_event",
    "partition_key": "example",
    "priority": 5,
    "ttl_seconds": 60
  },
  "payload_media_type": "application/json",
  "payload": null,
  "payload_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
  "payload_ref": {
    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
    "bytes": 12345,
    "content_encoding": "identity"
  },
  "extensions": {}
}

Control command (unsigned example; valid only when control auth is not enforced by runtime config):

{
  "schema_id": "if.bus.control_command",
  "schema_version": "1.0.0",
  "command_id": "00000000-0000-0000-0000-0000000000c0",
  "issued_utc": "2026-01-01T00:00:00Z",
  "actor": {
    "kind": "system",
    "id": "example-operator"
  },
  "target": {
    "kind": "topic",
    "id": "if.bus.demo.dev.example.event"
  },
  "command": {
    "name": "pause",
    "parameters": {
      "mode": "hold",
      "ttl_seconds": 60,
      "hold_delay_seconds": 1,
      "max_hold_attempts": 3
    }
  },
  "reason": "example pause",
  "idempotency_key": "example:pause:if.bus.demo.dev.example.event",
  "extensions": {}
}

Control acknowledgement (example):

{
  "schema_id": "if.bus.control_ack",
  "schema_version": "1.0.0",
  "ack_id": "00000000-0000-0000-0000-0000000000a0",
  "command_id": "00000000-0000-0000-0000-0000000000c0",
  "processed_utc": "2026-01-01T00:00:00Z",
  "status": "completed",
  "runtime_instance": "ifbus-example"
}

6. Control plane summary (pause/quarantine/replay)

6.1 Control topics (reference defaults)

if.bus.control.command
if.bus.control.ack

6.2 Control command (`if.bus.control_command`)

Adapters/operators send a control command object (not an envelope) to the control topic. The runtime validates it and emits an ack object to the ack topic.

6.3 Control auth gate (optional)

Black/white:

Control auth is only enforced when the runtime is configured with control_auth.
The reference scheme is HMAC-SHA256 over canonical JSON bytes of the command with the auth extension removed.
This document does not publish any secrets or credential material.

7. DLQ summary (dead-letter envelope)

Black/white:

DLQ is represented as a normal bus envelope whose event.name is if.bus.dead_letter_event.
The DLQ payload includes the original envelope plus error context and transport metadata.
DLQ exists to make failures queryable without “log archaeology.”

8. Pointer-only pattern (large payloads, redaction posture)

If a payload is large or must be redacted:

Keep payload_sha256 (hash of canonical payload bytes) as the audit anchor.
Omit payload or include a redacted/summary payload.
Include payload_ref with:
- sha256 that matches payload_sha256
- optional source_url only if it is safe to disclose publicly (otherwise omit it)

This keeps envelopes small and review-friendly while preserving integrity checks.

9. Full JSON Schemas (embedded)

Source of truth (repo-relative):

schemas/if-bus/*.schema.json

9.1 `if.bus.envelope`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/envelope.schema.json",
  "title": "IF.BUS Event Envelope",
  "description": "A stable, versioned envelope for events moving through the integration bus.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": ["if.bus.envelope"],
      "description": "Stable schema identifier."
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Schema version (semver)."
    },
    "event_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "description": "Stable event identifier (recommended: ULID/UUID)."
    },
    "emitted_utc": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp when the event was emitted."
    },
    "producer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "description": "Producer kind (e.g., if.api.adapter, if.bus.runtime)."
        },
        "id": {
          "type": "string",
          "description": "Producer identifier (e.g., adapter_id)."
        },
        "version": {
          "type": "string",
          "description": "Producer version or build identifier."
        },
        "instance": {
          "type": "string",
          "description": "Optional runtime instance identifier."
        }
      },
      "required": ["kind", "id"]
    },
    "event": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Event name (recommended: dot-separated token)."
        },
        "op": {
          "type": "string",
          "description": "High-level operation type (optional)."
        }
      },
      "required": ["name"]
    },
    "subject": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "description": "Subject kind (e.g., repo, ticket, document)."
        },
        "id": {
          "type": "string",
          "description": "Subject identifier in the source system."
        }
      },
      "required": ["kind", "id"]
    },
    "routing": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "topic": {
          "type": "string",
          "description": "Routing topic name."
        },
        "partition_key": {
          "type": "string",
          "description": "Partition key used for best-effort ordering."
        },
        "priority": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "description": "Optional priority hint (0=lowest, 10=highest)."
        },
        "ttl_seconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Optional time-to-live for the event."
        }
      },
      "required": ["topic", "partition_key"]
    },
    "correlation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "correlation_id": {
          "type": "string",
          "description": "Correlation identifier for grouping related events."
        },
        "causation_id": {
          "type": "string",
          "description": "Causation identifier (e.g., parent event_id)."
        }
      }
    },
    "payload_media_type": {
      "type": "string",
      "description": "Media type of the payload (optional)."
    },
    "payload": {
      "type": "object",
      "additionalProperties": true,
      "description": "Event payload (may be redacted or partial; hash is authoritative)."
    },
    "payload_sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "SHA-256 of the authoritative payload bytes."
    },
    "payload_ref": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional pointer to the authoritative payload bytes when the payload is too large to inline or must be redacted. This is static metadata (no runtime fetch requirement).",
      "properties": {
        "sha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$",
          "description": "SHA-256 of the decoded/authoritative payload bytes (should match payload_sha256)."
        },
        "content_sha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$",
          "description": "Optional SHA-256 of the stored bytes at source_url (may be compressed/encoded)."
        },
        "content_encoding": {
          "type": "string",
          "enum": [
            "identity",
            "gzip",
            "zstd"
          ],
          "description": "Optional encoding of the stored bytes referenced by source_url."
        },
        "bytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Optional stored size in bytes."
        },
        "media_type": {
          "type": "string",
          "description": "Optional media type of the decoded payload bytes."
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Optional public/capability URL for fetching the stored bytes (static). If present, it MUST NOT require interactive auth (no cookies, no bearer tokens)."
        }
      },
      "required": [
        "sha256"
      ]
    },
    "receipts": {
      "type": "array",
      "description": "Optional receipt references (integrity receipts, not truth claims).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "description": "Receipt kind (e.g., if.trace)."
          },
          "share_id": {
            "type": "string",
            "description": "Public receipt shareId."
          }
        },
        "required": ["kind", "share_id"]
      }
    },
    "budget": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional pre-emptive budget guardrails for downstream actions.",
      "properties": {
        "budget_id": {
          "type": "string",
          "description": "Stable budget identifier."
        },
        "currency": {
          "type": "string",
          "description": "Currency code (e.g., USD)."
        },
        "soft_limit": {
          "type": "number",
          "minimum": 0,
          "description": "Soft limit (warn)."
        },
        "hard_limit": {
          "type": "number",
          "minimum": 0,
          "description": "Hard limit (stop)."
        }
      },
      "required": ["budget_id", "currency"]
    },
    "security": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional security classification pointers (detailed findings are separate signals).",
      "properties": {
        "classification": {
          "type": "string",
          "enum": ["public", "internal", "restricted"],
          "description": "Data classification label."
        },
        "pii_present": {
          "type": "boolean",
          "description": "Whether payload likely contains personal data."
        }
      }
    },
    "extensions": {
      "type": "object",
      "maxProperties": 64,
      "additionalProperties": true,
      "description": "Namespaced extension fields for future compatibility. Runtime enforces a maximum extension size budget (bytes); schema enforces only basic key shape.",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9_-]*\\.[a-z0-9][a-z0-9_.-]*$",
        "description": "Extension keys must be dot-namespaced (recommended: vendor.product.*)."
      }
    }
  },
  "required": ["schema_id", "schema_version", "event_id", "emitted_utc", "producer", "event", "routing", "payload_sha256"],
  "examples": [
    {
      "schema_id": "if.bus.envelope",
      "schema_version": "1.0.0",
      "event_id": "01JH8Y3KJ7P2B34M1R9T2Y8X0A",
      "emitted_utc": "2026-01-08T20:00:00Z",
      "producer": {
        "kind": "if.api.adapter",
        "id": "github_webhook",
        "version": "2026-01-05"
      },
      "event": {
        "name": "github.push",
        "op": "update"
      },
      "subject": {
        "kind": "repo",
        "id": "octo-org/octo-repo"
      },
            "routing": {
                "topic": "if.bus.demo.roadmap.ingress.github.push",
                "partition_key": "octo-org/octo-repo",
                "priority": 5,
                "ttl_seconds": 86400
            },
      "payload_media_type": "application/json",
      "payload": {
        "demo": true,
        "note": "Payload content may be partial or redacted; payload_sha256 is authoritative."
      },
      "payload_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "payload_ref": {
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "content_encoding": "gzip",
        "content_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "source_url": "https://infrafabric.io/static/source/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.tgz"
      },
      "budget": {
        "budget_id": "tenant-demo-usd-daily",
        "currency": "USD",
        "soft_limit": 25.0,
        "hard_limit": 50.0
      },
      "security": {
        "classification": "internal",
        "pii_present": false
      },
      "extensions": {
        "if.bus.demo.note": "Extension keys must be namespaced to avoid collisions."
      }
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.envelope",
    "used_in": ["if.bus.runtime", "if.api.adapters"]
  }
}

9.2 `if.bus.runtime_config`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/runtime_config.schema.json",
  "title": "IF.BUS Runtime Config",
  "description": "Build-time and deploy-time configuration for a bus runtime instance (transport, retention, DLQ, limits, and optional control-plane auth).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": [
        "if.bus.runtime_config"
      ]
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "generated_utc": {
      "type": "string",
      "format": "date-time"
    },
    "instance": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Runtime instance identifier."
        },
        "environment": {
          "type": "string",
          "description": "Environment label (e.g., dev, staging, prod)."
        }
      },
      "required": [
        "id",
        "environment"
      ]
    },
    "transport": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "in_memory",
            "nats_js",
            "kafka",
            "redis_streams",
            "rabbitmq"
          ]
        },
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stream": {
          "type": "string",
          "description": "Stream name (if applicable)."
        }
      },
      "required": [
        "kind"
      ]
    },
    "retention_policy": {
      "type": "object",
      "additionalProperties": false,
      "description": "Mandatory retention policy for the hot event store used by the runtime.",
      "properties": {
        "limits": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "bytes": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum bytes of retained messages (hot store)."
            },
            "messages": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum number of retained messages (hot store)."
            },
            "age": {
              "type": "string",
              "pattern": "^[0-9]+(s|m|h|d)$",
              "description": "Maximum age for retained messages (e.g., 72h)."
            }
          },
          "required": [
            "age"
          ]
        },
        "when_exceeded": {
          "type": "string",
          "enum": [
            "discard_oldest",
            "reject_new"
          ],
          "description": "Black/white behavior when limits are reached."
        }
      },
      "required": [
        "limits",
        "when_exceeded"
      ]
    },
    "limits": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional runtime size limits (envelope and inline payload). These are enforced by the runtime at ingest/validation time.",
      "properties": {
        "max_envelope_bytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum size in bytes of the envelope JSON bytes after canonicalization (best-effort)."
        },
        "max_inline_payload_bytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum size in bytes for inline payload bytes; larger payloads should use payload_ref."
        },
        "max_extensions_bytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum size in bytes for the JSON-encoded extensions object."
        }
      }
    },
    "dlq": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "topic": {
          "type": "string",
          "description": "Dead-letter topic/subject."
        },
        "max_attempts": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum retry attempts before dead-lettering."
        }
      },
      "required": [
        "topic"
      ]
    },
    "control_auth": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional control-plane auth gate for control commands (reference runtime skeleton). Secrets should be provided via environment variables, not committed config.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "hmac_sha256"
          ],
          "description": "Reference implementation: HMAC-SHA256 over UTF-8 JSON bytes of the control command with `extensions.auth` removed (json.dumps(sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False))."
        },
        "key_id": {
          "type": "string",
          "description": "Key identifier (supports rotation; runtime matches `extensions.auth.key_id`)."
        },
        "secret_env": {
          "type": "string",
          "description": "Environment variable name containing the shared secret."
        }
      },
      "required": [
        "kind",
        "key_id",
        "secret_env"
      ]
    },
    "quotas": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional ingress quotas for fail-closed backpressure (reference runtime skeleton).",
      "properties": {
        "default": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "messages_per_sec": {
              "type": "number",
              "minimum": 0,
              "description": "Maximum ingested messages per second (applies per {tenant,topic} key)."
            },
            "bytes_per_sec": {
              "type": "number",
              "minimum": 0,
              "description": "Maximum ingested bytes per second (applies per {tenant,topic} key)."
            },
            "when_exceeded": {
              "type": "string",
              "enum": [
                "dead_letter"
              ],
              "description": "Black/white behavior when quota is exceeded (reference runtime skeleton emits a DLQ event and acks the original message)."
            }
          },
          "required": [
            "messages_per_sec",
            "bytes_per_sec",
            "when_exceeded"
          ]
        },
        "overrides": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "tenant_id": {
                "type": "string"
              },
              "topic": {
                "type": "string"
              },
              "rule": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "messages_per_sec": {
                    "type": "number",
                    "minimum": 0
                  },
                  "bytes_per_sec": {
                    "type": "number",
                    "minimum": 0
                  },
                  "when_exceeded": {
                    "type": "string",
                    "enum": [
                      "dead_letter"
                    ]
                  }
                },
                "required": [
                  "messages_per_sec",
                  "bytes_per_sec",
                  "when_exceeded"
                ]
              }
            },
            "required": [
              "tenant_id",
              "topic",
              "rule"
            ]
          }
        }
      }
    }
  },
  "required": [
    "schema_id",
    "schema_version",
    "generated_utc",
    "instance",
    "transport",
    "retention_policy",
    "dlq"
  ],
  "examples": [
    {
      "schema_id": "if.bus.runtime_config",
      "schema_version": "1.0.0",
      "generated_utc": "2026-01-10T00:00:00Z",
      "instance": {
        "id": "if-bus-runtime-dev",
        "environment": "dev"
      },
      "transport": {
        "kind": "nats_js",
        "servers": [
          "nats://127.0.0.1:4222"
        ],
        "stream": "IFBUS"
      },
      "retention_policy": {
        "limits": {
          "age": "72h",
          "bytes": 2147483648,
          "messages": 1000000
        },
        "when_exceeded": "discard_oldest"
      },
      "dlq": {
        "topic": "if.bus.dlq",
        "max_attempts": 10
      },
      "control_auth": {
        "kind": "hmac_sha256",
        "key_id": "default",
        "secret_env": "IFBUS_CONTROL_AUTH_SECRET"
      },
      "quotas": {
        "default": {
          "messages_per_sec": 1000,
          "bytes_per_sec": 1048576,
          "when_exceeded": "dead_letter"
        },
        "overrides": [
          {
            "tenant_id": "acme",
            "topic": "if.bus.acme.dev.ingress.github",
            "rule": {
              "messages_per_sec": 25,
              "bytes_per_sec": 262144,
              "when_exceeded": "dead_letter"
            }
          }
        ]
      }
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.runtime_config",
    "used_in": [
      "if.bus.runtime"
    ]
  }
}

9.3 `if.bus.control_command`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/control_command.schema.json",
  "title": "IF.BUS Control Command",
  "description": "An asynchronous control-plane command for bus operations (pause, replay, quarantine, budgets).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": ["if.bus.control_command"]
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "command_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "description": "Stable command identifier."
    },
    "issued_utc": {
      "type": "string",
      "format": "date-time"
    },
    "actor": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["operator", "automation", "system"],
          "description": "Who issued the command."
        },
        "id": {
          "type": "string",
          "description": "Actor identifier."
        }
      },
      "required": ["kind", "id"]
    },
    "target": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["runtime", "topic", "stream", "event", "adapter", "carrier", "tenant", "budget", "policy"],
          "description": "Target type."
        },
        "id": {
          "type": "string",
          "description": "Target identifier."
        }
      },
      "required": ["kind", "id"]
    },
    "command": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Command name (examples: pause, resume, replay, quarantine, set_budget)."
        },
        "parameters": {
          "type": "object",
          "additionalProperties": true,
          "description": "Command parameters (schema depends on command.name)."
        }
      },
      "required": ["name"]
    },
    "reason": {
      "type": "string",
      "description": "Human explanation for audit trails."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key for safe retries."
    },
    "extensions": {
      "type": "object",
      "maxProperties": 64,
      "additionalProperties": true,
      "description": "Namespaced extension fields (recommended: vendor.product.*). Runtime enforces a maximum extension size budget (bytes).",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9_-]*\\.[a-z0-9][a-z0-9_.-]*$"
      }
    }
  },
  "required": ["schema_id", "schema_version", "command_id", "issued_utc", "actor", "target", "command"],
  "examples": [
    {
      "schema_id": "if.bus.control_command",
      "schema_version": "1.0.0",
      "command_id": "cmd-01JH8Y50Y1G3C8X2W4R9V8TQ3Z",
      "issued_utc": "2026-01-08T20:05:00Z",
      "actor": {
        "kind": "operator",
        "id": "oncall"
      },
      "target": {
        "kind": "topic",
        "id": "if.bus.ingress.github"
      },
      "command": {
        "name": "pause",
        "parameters": {
          "ttl_seconds": 900,
          "mode": "drain"
        }
      },
      "reason": "Backpressure event: downstream consumer is failing; pause ingress to prevent queue growth.",
      "idempotency_key": "pause-if.bus.ingress.github-2026-01-08T20:05Z"
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.control_command",
    "used_in": ["if.bus.runtime"]
  }
}

9.4 `if.bus.control_ack`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/control_ack.schema.json",
  "title": "IF.BUS Control Acknowledgement",
  "description": "An acknowledgement describing the observed lifecycle of a control command.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": ["if.bus.control_ack"]
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "ack_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "command_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "processed_utc": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": ["accepted", "rejected", "in_progress", "completed", "failed", "timed_out"]
    },
    "runtime_instance": {
      "type": "string",
      "description": "Runtime instance that processed the command."
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "code": {"type": "string"},
        "message": {"type": "string"},
        "retryable": {"type": "boolean"}
      },
      "required": ["code", "message"]
    },
    "metrics": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "duration_ms": {"type": "integer", "minimum": 0}
      }
    },
    "extensions": {
      "type": "object",
      "maxProperties": 64,
      "additionalProperties": true,
      "description": "Namespaced extension fields (recommended: vendor.product.*). Runtime enforces a maximum extension size budget (bytes).",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9_-]*\\.[a-z0-9][a-z0-9_.-]*$"
      }
    }
  },
  "required": ["schema_id", "schema_version", "ack_id", "command_id", "processed_utc", "status"],
  "examples": [
    {
      "schema_id": "if.bus.control_ack",
      "schema_version": "1.0.0",
      "ack_id": "ack-01JH8Y5C7Z5XQ8J4V1A6S2T9P0",
      "command_id": "cmd-01JH8Y50Y1G3C8X2W4R9V8TQ3Z",
      "processed_utc": "2026-01-08T20:05:02Z",
      "status": "accepted",
      "runtime_instance": "ifbus-rt-01"
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.control_ack",
    "depends_on": ["if.bus.control_command"],
    "used_in": ["if.bus.runtime"]
  }
}

9.5 `if.bus.dead_letter_event`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/dead_letter_event.schema.json",
  "title": "IF.BUS Dead Letter Envelope",
  "description": "A structured dead-letter envelope that wraps a failed original envelope with error context and retry history.",
  "allOf": [
    {
      "$ref": "envelope.schema.json"
    },
    {
      "type": "object",
      "properties": {
        "event": {
          "type": "object",
          "properties": {
            "name": {
              "const": "if.bus.dead_letter_event"
            }
          },
          "required": [
            "name"
          ]
        },
        "payload": {
          "$ref": "#/$defs/dead_letter_payload"
        }
      },
      "required": [
        "event",
        "payload"
      ]
    }
  ],
  "$defs": {
    "error_context": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "schema_violation",
            "quota_exceeded",
            "consumer_timeout",
            "consumer_exception",
            "transport_error",
            "poison_message"
          ],
          "description": "Black/white classifier for why the message was dead-lettered."
        },
        "error": {
          "type": "string",
          "description": "Human-readable error summary (no secrets; safe to log)."
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Optional structured details (backend-specific)."
        }
      },
      "required": [
        "kind",
        "error"
      ]
    },
    "retry_attempt": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "attempt_utc": {
          "type": "string",
          "format": "date-time"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "nack_retry",
            "ack_success",
            "dead_lettered"
          ]
        },
        "retry_delay_seconds": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "attempt_utc",
        "outcome"
      ]
    },
    "source_transport": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "description": "Transport kind (e.g., nats_js, kafka, in_memory)."
        },
        "node_id": {
          "type": "string",
          "description": "Optional runtime node identifier."
        },
        "consumer_group": {
          "type": "string",
          "description": "Consumer group / durable subscription name."
        },
        "stream": {
          "type": "string",
          "description": "Transport stream name (if applicable)."
        },
        "subject": {
          "type": "string",
          "description": "Transport subject/topic name (if applicable)."
        },
        "message_id": {
          "type": "string",
          "description": "Transport message identifier (backend-specific)."
        },
        "partition": {
          "type": "integer",
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "kind",
        "message_id"
      ]
    },
    "dead_letter_payload": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "original_envelope": {
          "type": "object",
          "additionalProperties": true,
          "description": "The original envelope that failed processing."
        },
        "error_context": {
          "$ref": "#/$defs/error_context"
        },
        "retry_history": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/retry_attempt"
          }
        },
        "source_transport": {
          "$ref": "#/$defs/source_transport"
        }
      },
      "required": [
        "original_envelope",
        "error_context",
        "retry_history",
        "source_transport"
      ]
    }
  },
  "examples": [
    {
      "schema_id": "if.bus.envelope",
      "schema_version": "1.0.0",
      "event_id": "if.bus.example.dead_letter_event.v1",
      "emitted_utc": "2026-01-10T00:00:00Z",
      "producer": {
        "kind": "if.bus.runtime",
        "id": "example",
        "version": "0.0.0"
      },
      "event": {
        "name": "if.bus.dead_letter_event"
      },
      "routing": {
        "topic": "if.bus.dlq",
        "partition_key": "dlq",
        "priority": 5,
        "ttl_seconds": 86400
      },
      "payload_media_type": "application/json",
      "payload": {
        "original_envelope": {
          "schema_id": "if.bus.envelope",
          "schema_version": "1.0.0",
          "event_id": "01JH8Y3KJ7P2B34M1R9T2Y8X0A",
          "emitted_utc": "2026-01-10T00:00:00Z",
          "producer": {
            "kind": "if.api.adapter",
            "id": "github_webhook",
            "version": "2026-01-05"
          },
          "event": {
            "name": "github.push"
          },
          "routing": {
            "topic": "if.bus.demo.roadmap.ingress.github.push",
            "partition_key": "octo-org/octo-repo",
            "priority": 5,
            "ttl_seconds": 86400
          },
          "payload_media_type": "application/json",
          "payload_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "extensions": {}
        },
        "error_context": {
          "kind": "schema_violation",
          "error": "payload_sha256 missing"
        },
        "retry_history": [
          {
            "attempt_utc": "2026-01-10T00:00:00Z",
            "outcome": "dead_lettered"
          }
        ],
        "source_transport": {
          "kind": "nats_js",
          "consumer_group": "if-bus-runtime",
          "stream": "IFBUS",
          "subject": "if.bus.>",
          "message_id": "nats:seq:1"
        }
      },
      "payload_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "extensions": {}
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.dead_letter_event",
    "used_in": [
      "if.bus.runtime"
    ]
  }
}

9.6 `if.bus.dead_letter_payload`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/dead_letter_payload.schema.json",
  "title": "IF.BUS Dead Letter Payload",
  "description": "Payload object for `if.bus.dead_letter_event` envelopes (used by the runtime DLQ emitter and payload registry validation).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "original_envelope": {
      "type": "object",
      "additionalProperties": true,
      "description": "The original envelope that failed processing."
    },
    "error_context": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "schema_violation",
            "quota_exceeded",
            "consumer_timeout",
            "consumer_exception",
            "transport_error",
            "poison_message"
          ],
          "description": "Black/white classifier for why the message was dead-lettered."
        },
        "error": {
          "type": "string",
          "description": "Human-readable error summary (no secrets; safe to log)."
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Optional structured details (backend-specific)."
        }
      },
      "required": [
        "kind",
        "error"
      ]
    },
    "retry_history": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "attempt_utc": {
            "type": "string",
            "format": "date-time"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "nack_retry",
              "ack_success",
              "dead_lettered"
            ]
          },
          "retry_delay_seconds": {
            "type": "number",
            "minimum": 0
          }
        },
        "required": [
          "attempt_utc",
          "outcome"
        ]
      }
    },
    "source_transport": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "description": "Transport kind (e.g., nats_js, kafka, in_memory)."
        },
        "node_id": {
          "type": "string",
          "description": "Optional runtime node identifier."
        },
        "consumer_group": {
          "type": "string",
          "description": "Consumer group / durable subscription name."
        },
        "stream": {
          "type": "string",
          "description": "Transport stream name (if applicable)."
        },
        "subject": {
          "type": "string",
          "description": "Transport subject/topic name (if applicable)."
        },
        "message_id": {
          "type": "string",
          "description": "Transport message identifier (backend-specific)."
        }
      },
      "required": [
        "kind",
        "message_id"
      ]
    }
  },
  "required": [
    "original_envelope",
    "error_context",
    "retry_history",
    "source_transport"
  ],
  "examples": [
    {
      "original_envelope": {
        "schema_id": "if.bus.envelope",
        "schema_version": "1.0.0",
        "event_id": "01JH8Y3KJ7P2B34M1R9T2Y8X0A",
        "emitted_utc": "2026-01-10T00:00:00Z",
        "producer": {
          "kind": "if.api.adapter",
          "id": "github_webhook",
          "version": "2026-01-05"
        },
        "event": {
          "name": "github.push"
        },
        "routing": {
          "topic": "if.bus.demo.roadmap.ingress.github.push",
          "partition_key": "octo-org/octo-repo",
          "priority": 5,
          "ttl_seconds": 86400
        },
        "payload_media_type": "application/json",
        "payload_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "extensions": {}
      },
      "error_context": {
        "kind": "schema_violation",
        "error": "payload_sha256 missing"
      },
      "retry_history": [
        {
          "attempt_utc": "2026-01-10T00:00:00Z",
          "outcome": "dead_lettered"
        }
      ],
      "source_transport": {
        "kind": "nats_js",
        "message_id": "nats:IFBUS:12345"
      }
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.dead_letter_payload",
    "used_in": [
      "if.bus.dead_letter_event"
    ]
  }
}

9.7 `if.bus.budget_event`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/budget_event.schema.json",
  "title": "IF.BUS Budget Event",
  "description": "Budget telemetry for pre-emptive cost monitoring (preflight estimates and postflight actuals).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": ["if.bus.budget_event"]
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "budget_event_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "emitted_utc": {
      "type": "string",
      "format": "date-time"
    },
    "trigger": {
      "type": "string",
      "enum": ["preflight", "postflight", "periodic", "anomaly"]
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["tenant", "workflow", "adapter", "carrier"]
        },
        "id": {
          "type": "string"
        }
      },
      "required": ["kind", "id"]
    },
    "budget": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "budget_id": {"type": "string"},
        "currency": {"type": "string"},
        "soft_limit": {"type": "number", "minimum": 0},
        "hard_limit": {"type": "number", "minimum": 0},
        "period": {"type": "string", "description": "Budget period (e.g., daily, monthly)."},
        "resource_limits": {
          "type": "object",
          "additionalProperties": false,
          "description": "Optional per-resource caps (non-monetary) to prevent runaway spend even when prices change.",
          "properties": {
            "api_calls": {"$ref": "#/$defs/resource_limit"},
            "bytes_in": {"$ref": "#/$defs/resource_limit"},
            "bytes_out": {"$ref": "#/$defs/resource_limit"},
            "tokens_in": {"$ref": "#/$defs/resource_limit"},
            "tokens_out": {"$ref": "#/$defs/resource_limit"},
            "compute_ms": {"$ref": "#/$defs/resource_limit"}
          }
        },
        "replenishment": {
          "type": "object",
          "additionalProperties": false,
          "description": "Optional replenishment schedule metadata for how budget windows reset.",
          "properties": {
            "kind": {
              "type": "string",
              "enum": ["fixed_window", "rolling_window"]
            },
            "period": {
              "type": "string",
              "description": "Window size label (e.g., hourly, daily, monthly)."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone name (informational)."
            },
            "next_reset_utc": {
              "type": "string",
              "format": "date-time",
              "description": "Best-effort next reset time (informational; not authoritative)."
            }
          },
          "required": ["kind", "period"]
        }
      },
      "required": ["budget_id", "currency"]
    },
    "usage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "cost_estimate": {"type": "number", "minimum": 0},
        "cost_actual": {"type": "number", "minimum": 0},
        "units": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "api_calls": {"type": "integer", "minimum": 0},
            "bytes_in": {"type": "integer", "minimum": 0},
            "bytes_out": {"type": "integer", "minimum": 0},
            "tokens_in": {"type": "integer", "minimum": 0},
            "tokens_out": {"type": "integer", "minimum": 0},
            "compute_ms": {"type": "integer", "minimum": 0},
            "wall_ms": {"type": "integer", "minimum": 0}
          }
        }
      }
    },
    "advice": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Recommended operational actions (non-binding)."
    },
    "related_event_id": {
      "type": "string",
      "description": "Optional related data-plane event_id."
    },
    "reconciliation": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional reconciliation metadata linking preflight estimates to postflight actuals.",
      "properties": {
        "preflight_budget_event_id": {"type": "string"},
        "postflight_budget_event_id": {"type": "string"},
        "cost_delta": {"type": "number"},
        "units_delta": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "api_calls": {"type": "integer"},
            "bytes_in": {"type": "integer"},
            "bytes_out": {"type": "integer"},
            "tokens_in": {"type": "integer"},
            "tokens_out": {"type": "integer"},
            "compute_ms": {"type": "integer"},
            "wall_ms": {"type": "integer"}
          }
        }
      },
      "required": ["preflight_budget_event_id"]
    },
    "extensions": {
      "type": "object",
      "maxProperties": 64,
      "additionalProperties": true,
      "description": "Namespaced extension fields (recommended: vendor.product.*). Runtime enforces a maximum extension size budget (bytes).",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9_-]*\\.[a-z0-9][a-z0-9_.-]*$"
      }
    }
  },
  "$defs": {
    "resource_limit": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "soft_limit": {"type": "number", "minimum": 0},
        "hard_limit": {"type": "number", "minimum": 0}
      }
    }
  },
  "required": ["schema_id", "schema_version", "budget_event_id", "emitted_utc", "trigger", "scope", "budget"],
  "examples": [
    {
      "schema_id": "if.bus.budget_event",
      "schema_version": "1.0.0",
      "budget_event_id": "bud-01JH8Y5S3F2WJ6X9Q1R8T7Y6Z5",
      "emitted_utc": "2026-01-08T20:06:00Z",
      "trigger": "preflight",
      "scope": {
        "kind": "workflow",
        "id": "demo-github-to-slack"
      },
      "budget": {
        "budget_id": "tenant-demo-usd-daily",
        "currency": "USD",
        "soft_limit": 25.0,
        "hard_limit": 50.0,
        "period": "daily",
        "resource_limits": {
          "api_calls": {"soft_limit": 1000, "hard_limit": 2000},
          "bytes_out": {"soft_limit": 104857600, "hard_limit": 209715200}
        },
        "replenishment": {
          "kind": "fixed_window",
          "period": "daily",
          "timezone": "UTC",
          "next_reset_utc": "2026-01-09T00:00:00Z"
        }
      },
      "usage": {
        "cost_estimate": 0.02,
        "units": {
          "api_calls": 1,
          "bytes_in": 2048,
          "bytes_out": 1024
        }
      },
      "advice": ["allow"]
    },
    {
      "schema_id": "if.bus.budget_event",
      "schema_version": "1.0.0",
      "budget_event_id": "bud-01JH8Y5S3F2WJ6X9Q1R8T7Y6Z6",
      "emitted_utc": "2026-01-08T20:06:03Z",
      "trigger": "postflight",
      "scope": {
        "kind": "workflow",
        "id": "demo-github-to-slack"
      },
      "budget": {
        "budget_id": "tenant-demo-usd-daily",
        "currency": "USD",
        "soft_limit": 25.0,
        "hard_limit": 50.0,
        "period": "daily"
      },
      "usage": {
        "cost_actual": 0.03,
        "units": {
          "api_calls": 1,
          "bytes_in": 2048,
          "bytes_out": 2048,
          "compute_ms": 25,
          "wall_ms": 120
        }
      },
      "reconciliation": {
        "preflight_budget_event_id": "bud-01JH8Y5S3F2WJ6X9Q1R8T7Y6Z5",
        "cost_delta": 0.01,
        "units_delta": {
          "bytes_out": 1024
        }
      },
      "advice": ["allow"]
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.budget_event",
    "used_in": ["if.bus.runtime", "if.bus.ops"]
  }
}

9.8 `if.bus.security_signal` (sanitized example)

Black/white:

This embedded schema is identical to schemas/if-bus/security_signal.schema.json except for one example string that contained an authorization header scheme word; it is replaced with a generic redacted form to keep this single-file brief publish-safe under strict scanners.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/security_signal.schema.json",
  "title": "IF.BUS Security Signal",
  "description": "A security monitoring signal emitted by detectors observing bus traffic (redacted; no secrets).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_id": {
      "type": "string",
      "enum": ["if.bus.security_signal"]
    },
    "schema_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "signal_id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "emitted_utc": {
      "type": "string",
      "format": "date-time"
    },
    "detector": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "detector_id": {"type": "string"},
        "version": {"type": "string"},
        "kind": {"type": "string"}
      },
      "required": ["detector_id", "version"]
    },
    "severity": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "finding_type": {
      "type": "string",
      "description": "Short token describing the finding class."
    },
    "summary": {
      "type": "string",
      "description": "Human-readable summary (public-safe)."
    },
    "recommended_action": {
      "type": "string",
      "description": "Recommended action (e.g., quarantine, redact, notify)."
    },
    "redactions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "redacted_excerpt": {
          "type": "string",
          "description": "A redacted excerpt showing what matched (never include secrets)."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "related_event_id": {
      "type": "string",
      "description": "Optional related data-plane event_id."
    },
    "extensions": {
      "type": "object",
      "maxProperties": 64,
      "additionalProperties": true,
      "description": "Namespaced extension fields (recommended: vendor.product.*). Runtime enforces a maximum extension size budget (bytes).",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9_-]*\\.[a-z0-9][a-z0-9_.-]*$"
      }
    }
  },
  "required": ["schema_id", "schema_version", "signal_id", "emitted_utc", "detector", "severity", "finding_type", "summary"],
  "examples": [
    {
      "schema_id": "if.bus.security_signal",
      "schema_version": "1.0.0",
      "signal_id": "sec-01JH8Y6A8N3Q2P1R0S9T8U7V6W",
      "emitted_utc": "2026-01-08T20:07:00Z",
      "detector": {
        "detector_id": "secrets.detect",
        "version": "1.0.0",
        "kind": "regex"
      },
      "severity": "high",
      "finding_type": "secret_like_token",
      "summary": "Detector matched a token-like pattern in an inbound payload; excerpt is redacted.",
      "recommended_action": "quarantine",
      "redactions": {
        "redacted_excerpt": "Authorization: [REDACTED]",
        "note": "Signals must never include the full secret; only redacted context."
      },
      "related_event_id": "01JH8Y3KJ7P2B34M1R9T2Y8X0A"
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.security_signal",
    "used_in": ["if.bus.runtime", "if.security.secrets.detect"]
  }
}

9.9 `if.bus.payload_registry`

{
  "schema_id": "if.bus.payload_registry",
  "schema_version": "1.0.0",
  "generated_utc": "2026-01-21T04:27:48Z",
  "evolution": {
    "v1_rule": "additive_only",
    "notes": [
      "Adding new optional fields is non-breaking.",
      "Removing fields or changing meanings is breaking.",
      "Breaking changes require a new schema_version and explicit migration guidance."
    ]
  },
  "entries": {
    "if.bus.budget_event": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/budget_event.schema.json"
    },
    "if.bus.carrier": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/carrier.schema.json"
    },
    "if.bus.carrier_manifest": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/carrier_manifest.schema.json"
    },
    "if.bus.dead_letter_event": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/dead_letter_payload.schema.json"
    },
    "if.bus.security_signal": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/security_signal.schema.json"
    },
    "if.bus.blog.medium_import_request": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/blog_medium_import_request.schema.json"
    },
    "if.bus.blog.medium_import_result": {
      "product_id": "if.bus",
      "payload_schema": "schemas/if-bus/blog_medium_import_result.schema.json"
    },
    "if.bus.llm.search_index_update": {
      "product_id": "if.discover",
      "payload_schema": "schemas/if-bus/llm_search_index_update.schema.json"
    },
    "if.api.adapter": {
      "product_id": "if.api",
      "payload_schema": "schemas/if-api/adapter.schema.json"
    },
    "if.api.adapter_spec": {
      "product_id": "if.api",
      "payload_schema": "schemas/if-api/adapter_spec.schema.json"
    }
  },
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.payload_registry",
    "used_in": [
      "if.bus.runtime"
    ]
  }
}

9.10 `if.bus.carrier` + `if.bus.carrier_manifest`

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/carrier.schema.json",
  "title": "IF.BUS Carrier",
  "description": "Lightweight carrier metadata for the integration bus.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "carrier_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_.-]{2,63}$",
      "description": "Stable carrier identifier."
    },
    "label": {
      "type": "string",
      "description": "Human-readable carrier label."
    },
    "provider": {
      "type": "string",
      "description": "Source vendor or platform providing the carrier."
    },
    "summary": {
      "type": "string",
      "description": "One-sentence description of what the carrier enables."
    },
    "status": {
      "type": "string",
      "enum": ["shipped", "preview", "roadmap"],
      "description": "Carrier readiness status."
    },
    "category": {
      "type": "string",
      "enum": ["connector", "resolver", "delivery", "registry"],
      "description": "Carrier family."
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Key capabilities exposed by the carrier."
    },
    "docs_url": {
      "type": "string",
      "format": "uri",
      "description": "Public documentation link for the carrier."
    },
    "demo_share_id": {
      "type": "string",
      "description": "Optional public demo shareId (if available)."
    }
  },
  "required": ["carrier_id", "label", "summary"],
  "examples": [
    {
      "carrier_id": "docusign",
      "label": "DocuSign",
      "provider": "DocuSign",
      "summary": "Send and track signature envelopes with receipt-backed outputs.",
      "status": "preview",
      "category": "connector",
      "capabilities": ["send", "status", "audit_log"],
      "docs_url": "https://developers.docusign.com/",
      "demo_share_id": "HmlXcqae8heBq1siMrIRyw"
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.carrier",
    "used_in": ["if.bus.carrier_manifest", "if.api.adapter_spec"]
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "if-bus/carrier_manifest.schema.json",
  "title": "IF.BUS Carrier Manifest",
  "description": "A versioned manifest describing available carriers for the integration bus.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string",
      "description": "Schema version for the manifest payload."
    },
    "generated_utc": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp when the manifest was generated."
    },
    "carriers": {
      "type": "array",
      "items": {
        "$ref": "carrier.schema.json"
      },
      "description": "Carrier entries included in the manifest."
    },
    "source": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "inventory_path": {
          "type": "string",
          "description": "Path to the inventory source document."
        },
        "notes": {
          "type": "string",
          "description": "Human notes about the manifest source."
        }
      },
      "required": ["inventory_path"]
    }
  },
  "required": ["schema_version", "generated_utc", "carriers"],
  "examples": [
    {
      "schema_version": "1.0.0",
      "generated_utc": "2026-01-07T16:30:00Z",
      "carriers": [
        {
          "carrier_id": "docusign",
          "label": "DocuSign",
          "provider": "DocuSign",
          "summary": "Send and track signature envelopes with receipt-backed outputs.",
          "status": "preview",
          "category": "connector",
          "capabilities": ["send", "status", "audit_log"],
          "docs_url": "https://developers.docusign.com/",
          "demo_share_id": "HmlXcqae8heBq1siMrIRyw"
        }
      ],
      "source": {
        "inventory_path": "docs/32-if-api-integrations-inventory.md",
        "notes": "Inventory-driven carrier list."
      }
    }
  ],
  "x_if": {
    "product_id": "if.bus",
    "concept_id": "if.bus.carrier_manifest",
    "depends_on": ["if.bus.carrier"],
    "used_in": ["if.api.adapter_spec"]
  }
}

if.bus full stack

if.bus — full stack whitepaper (single-file, offline-friendly)

Table of contents

0. Black/white (verified vs not claimed)

1. What this document contains

2. Public review surfaces (URLs)

Product index (entrypoint)

Runtime spec pack (dated)

Sandbox runtime pack (dated; internal-only posture documented)

Whitepaper source pack (dated)

Registry mirror (status source of truth)

Schema URLs (2026-01-19 runtime spec pack)

Legacy whitepaper extract (hosted-static; HTML-first)

Developer KB snapshot (hosted-static; HTML-first)

3. Current implementation in this repo (reference runtime)

Code location

Entry points

Supported transport kinds (as implemented)

Implemented behaviors (as of this repo state)

4. Runtime posture (what external integrators can and cannot do)

What external integrators can do from public artifacts alone

What is not provided as a public contract (requires coordination)

5. Protocol summary (what an adapter must produce)

5.1 Data-plane envelope (if.bus.envelope)

5.2 Topic taxonomy

5.3 Canonical bytes + hashing

5.4 Minimal examples (publish-safe)

6. Control plane summary (pause/quarantine/replay)

6.1 Control topics (reference defaults)

6.2 Control command (if.bus.control_command)

6.3 Control auth gate (optional)

7. DLQ summary (dead-letter envelope)

8. Pointer-only pattern (large payloads, redaction posture)

9. Full JSON Schemas (embedded)

9.1 if.bus.envelope

9.2 if.bus.runtime_config

9.3 if.bus.control_command

9.4 if.bus.control_ack

9.5 if.bus.dead_letter_event

9.6 if.bus.dead_letter_payload

9.7 if.bus.budget_event

9.8 if.bus.security_signal (sanitized example)

9.9 if.bus.payload_registry

9.10 if.bus.carrier + if.bus.carrier_manifest

5.1 Data-plane envelope (`if.bus.envelope`)

6.2 Control command (`if.bus.control_command`)

9.1 `if.bus.envelope`

9.2 `if.bus.runtime_config`

9.3 `if.bus.control_command`

9.4 `if.bus.control_ack`

9.5 `if.bus.dead_letter_event`

9.6 `if.bus.dead_letter_payload`

9.7 `if.bus.budget_event`

9.8 `if.bus.security_signal` (sanitized example)

9.9 `if.bus.payload_registry`

9.10 `if.bus.carrier` + `if.bus.carrier_manifest`