Unit Schema Types

ELI5

A unit is one of five shapes: a persona (role), a constraint (rule), a job description (task), a recipe of jobs (chain), or a snippet (fragment). Each shape has its own schema; you can’t smuggle a step list into a rule.

Technical Deep Dive

Type Hierarchy

classDiagram
    class BaseSchema {
        +MetaSchema meta
        +string id
        +string slug
        +Domain domain
        +Status status
    }
    class RoleUnitSchema {
        +string persona_block
    }
    class RuleUnitSchema {
        +string polarity
        +string scope
        +bool protected
    }
    class TaskUnitSchema {
        +ContractSchema contract
        +string prompt_body
    }
    class ChainUnitSchema {
        +CompositionStepSchema[] steps
        +string[] imports
    }
    class FragmentUnitSchema {
        +string body
    }
    BaseSchema <|-- RoleUnitSchema
    BaseSchema <|-- RuleUnitSchema
    BaseSchema <|-- TaskUnitSchema
    BaseSchema <|-- ChainUnitSchema
    BaseSchema <|-- FragmentUnitSchema

Field Highlights

Enum Anchors

@stratt/schema/constants.ts exports the closed enums consumed by the Zod validators: UNIT_TYPES, DOMAINS (nine entries), STATUSES (nine, per AC-01), INPUT_TYPES (string | integer | float | boolean | document | array | object), FAILURE_HANDLERS (gate | retry | abort | fallback).

Validation Failure Surface

A validation error is a flat list of Zod issues. The CLI validate command groups by unit type so the writer sees, e.g., “rule unit no-secrets is missing polarity” rather than a deep path string.

Key Terms

• Contract → a task’s typed input/output declaration (lives under contract).
• Composition step → one ordered entry in a chain’s steps[] referencing another unit by URI.
• Protected rule → a rule with protected: true that downstream chains cannot override.

Q&A

Q: Can a fragment import another unit? A: No. Fragments are body-only; only task and chain carry imports[].

Q: Where does a chain reference its steps’ implementations? A: Each CompositionStepSchema carries a strat:// URI; resolution happens at L3 via the dependency DAG.

Examples

A two-step chain strat://dev/chain/triage-bug@0.2.1 references one rule and one task in composition.steps[], both pinned at semver, both listed again in imports[] for the graph builder.