state

Intent

Create a structured representation of the current state of a domain, system, or entity. This is the foundation for world modeling, enabling tracking of entities, relationships, and properties over time.

Success criteria:

• State captured in structured, queryable format
• Entities and relationships clearly identified
• Uncertainty and confidence explicitly represented
• Evidence anchors for all state assertions

Compatible schemas:

• schemas/output_schema.yaml
• reference/world_state_schema.yaml

Inputs

Parameter	Required	Type	Description
scope	Yes	string	What domain/system to model (e.g., "user authentication", "payment processing")
schema	No	object	State schema defining expected structure
timestamp	No	string	Point in time for state (default: now)
depth	No	string	Modeling depth: surface, detailed, comprehensive

Procedure

1. Define scope boundaries: Clarify what is included in the state model

   • Identify system or domain boundaries
   • Determine entity types to include
   • Establish relationship types to capture

2. Identify entities: Enumerate entities within scope

   • Extract entity references from sources
   • Assign unique identifiers
   • Capture entity properties/attributes

3. Map relationships: Document connections between entities

   • Identify relationship types (contains, depends_on, references)
   • Note relationship directionality
   • Capture relationship properties

4. Capture current values: Record current state of each entity

   • Document property values with evidence
   • Note uncertainty where values are unclear
   • Record observation timestamp

5. Apply schema: Structure state according to schema if provided

   • Validate against schema constraints
   • Note schema violations or extensions needed
   • Ensure required fields are populated

6. Ground state claims: Attach evidence to all assertions

   • Reference source files, commands, or observations
   • Note confidence level for each assertion

Output Contract

Return a structured object:

state:
  world_id: string  # Unique identifier for this state snapshot
  scope: string  # Domain being modeled
  timestamp: string  # When state was captured
  entities:
    - id: string  # Unique entity identifier
      type: string  # Entity classification
      properties: object  # Entity attributes
      confidence: number  # Confidence in entity state
  relationships:
    - from: string  # Source entity ID
      to: string  # Target entity ID
      type: string  # Relationship type
      properties: object  # Relationship attributes
  meta:
    version: string  # State schema version
    completeness: number  # 0-1 estimate of coverage
confidence: 0..1  # Overall state model confidence
evidence_anchors: ["file:line", "observation:id"]
assumptions: []

Field Definitions

Field	Type	Description
state.world_id	string	Unique identifier for state snapshot
state.scope	string	Domain or system being modeled
state.entities	array	Identified entities with properties
state.relationships	array	Connections between entities
state.meta.completeness	number	Estimated model completeness
confidence	number	Overall confidence in state accuracy

Examples

Example 1: Model Authentication System State

Input:

scope: "user authentication system"
depth: "detailed"

Output:

state:
  world_id: "auth-state-20240115-001"
  scope: "user authentication system"
  timestamp: "2024-01-15T10:30:00Z"
  entities:
    - id: "auth-service"
      type: "service"
      properties:
        status: "running"
        version: "2.3.1"
        port: 8080
      confidence: 0.95
    - id: "user-db"
      type: "database"
      properties:
        type: "PostgreSQL"
        connection_pool: 20
        active_connections: 12
      confidence: 0.90
    - id: "session-cache"
      type: "cache"
      properties:
        type: "Redis"
        memory_used: "256MB"
        keys: 15420
      confidence: 0.90
  relationships:
    - from: "auth-service"
      to: "user-db"
      type: "depends_on"
      properties:
        connection_type: "direct"
        required: true
    - from: "auth-service"
      to: "session-cache"
      type: "depends_on"
      properties:
        connection_type: "direct"
        required: true
  meta:
    version: "1.0"
    completeness: 0.85
confidence: 0.88
evidence_anchors:
  - "config/services.yml:15-45"
  - "command:docker ps"
  - "command:redis-cli info"
assumptions:
  - "Service discovery reflects actual running state"
  - "Configuration matches deployed state"

Example 2: Model Code Module State

Input:

scope: "payment processing module"
schema:
  required_entities: ["class", "method", "dependency"]

Output:

state:
  world_id: "payments-code-20240115"
  scope: "payment processing module"
  timestamp: "2024-01-15T11:00:00Z"
  entities:
    - id: "PaymentProcessor"
      type: "class"
      properties:
        file: "src/services/payment_processor.rb"
        lines: 145
        methods: 8
        complexity: 24
      confidence: 0.95
    - id: "process_payment"
      type: "method"
      properties:
        class: "PaymentProcessor"
        visibility: "public"
        params: ["order", "payment_method"]
        complexity: 12
      confidence: 0.95
    - id: "stripe-gem"
      type: "dependency"
      properties:
        name: "stripe"
        version: "8.0.0"
        usage: ["PaymentProcessor"]
      confidence: 0.90
  relationships:
    - from: "PaymentProcessor"
      to: "stripe-gem"
      type: "depends_on"
      properties:
        import_type: "require"
    - from: "process_payment"
      to: "PaymentProcessor"
      type: "member_of"
      properties:
        visibility: "public"
  meta:
    version: "1.0"
    completeness: 0.75
confidence: 0.85
evidence_anchors:
  - "src/services/payment_processor.rb:1-145"
  - "Gemfile:42"
assumptions:
  - "Static analysis reflects runtime behavior"
  - "No dynamic method definitions"

Verification

• State includes world_id and timestamp
• All entities have unique IDs and types
• Relationships reference valid entity IDs
• Confidence scores present for entities
• Evidence anchors support state assertions

Verification tools: Read (to verify file references)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Do not modify state while modeling it
• Note when state may be stale or dynamic
• Flag entities with low confidence
• Do not invent entities without evidence

Composition Patterns

Commonly follows:

• observe - Observations feed into state modeling
• retrieve - Retrieved data informs state
• integrate - Merged data forms state

Commonly precedes:

• transition - State enables transition modeling
• compare - States can be compared (diff)
• simulate - State is starting point for simulation

Anti-patterns:

• Never use state for predictions (use predict)
• Avoid state for single-value measurement (use measure)

Workflow references:

• See reference/workflow_catalog.yaml#world_model_build for state in world modeling
• See reference/workflow_catalog.yaml#digital_twin_sync_loop for state in digital twins