decision-schema

Source: GitHub repo (ARCHITECTURE.md + README). Single Source of Truth (SSOT) for contracts in the multi-core decision ecosystem.

Purpose

Decision Schema is the Single Source of Truth (SSOT) for contracts in the multi-core decision ecosystem. It provides shared types and contracts that all decision cores depend on.

Core Components

Types (decision_schema/types.py)

• Action: Generic action enum (HOLD, ACT, EXIT, CANCEL, STOP)
• Proposal: MDM output (action, confidence, reasons, params dict)
• FinalDecision: Post-modulation action (action, allowed, reasons, mismatch)
• MismatchInfo: Guard failure flags and reason codes

Packet (decision_schema/packet_v2.py)

• PacketV2: End-to-end tracing packet — packet_version, schema_version; fields: run_id, step, input, external, mdm, final_action, latency_ms, mismatch

Compatibility (decision_schema/compat.py)

• is_compatible(): Check schema version compatibility (minor version ranges for 0.x)
• parse_version(): Parse SemVer to (major, minor, patch)
• get_current_version(): Current schema version

Inputs/Outputs

Inputs: None (foundation package)

Outputs: Type definitions used by all cores: Proposal → DMC; FinalDecision → executor; PacketV2 → evaluation-core; Action enum → all cores.

Non-Goals

• Domain-specific logic (schema is domain-agnostic)
• Runtime behavior (does not execute decisions)
• Policy enforcement or metrics computation

Design Principles

1. SSOT: Single source of truth for all contracts
2. SemVer: Compatibility guarantees
3. Domain-agnostic: Generic types across domains
4. Backward compatibility: Deprecation plan for smooth transitions
5. Fail-closed: Invalid versions raise errors

Quick Start (from README)

from decision_schema.types import Proposal, FinalDecision, Action
from decision_schema.packet_v2 import PacketV2
from decision_schema.compat import is_compatible

proposal = Proposal(
    action=Action.ACT,
    confidence=0.8,
    reasons=["anomaly_signal", "constraint_violation"],
    params={"value": 100},
)

Pin in pyproject.toml: decision-schema>=0.2,<0.3