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

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

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