$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://cfse.ai/schemas/artifacts/flow.schema.yaml"
title: "CFSE Flow Artifact Schema"
description: |
  Schema for Flow artifacts - multi-step legitimate sequences.
  Flows represent goal-oriented sequences of Interactions that achieve a user
  or system outcome, with clear preconditions, step sequencing, invariant
  guards/effects, variants, and success criteria.

type: object

required:
  - id
  - name
  - actor
  - goal
  - trigger
  - preconditions
  - steps
  - postconditions

properties:
  id:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/FlowID"
    description: |
      Unique identifier for the flow following the pattern F-<SYSTEM>-<NAME>.
      Example: F-SHOP-CHECKOUT, F-AWS-CROSS-ACCOUNT, F-K8S-POD-DEPLOY

  name:
    type: string
    minLength: 1
    maxLength: 100
    description: |
      Human-readable name for the flow. Should describe the user goal or
      outcome being achieved.
    examples:
      - "User Checkout and Payment"
      - "Cross-Account Resource Access"
      - "Pod Deployment with Security Context"

  description:
    type: string
    minLength: 10
    maxLength: 1000
    description: |
      Detailed description of what this flow accomplishes, its business purpose,
      and any important context.

  actor:
    type: string
    minLength: 1
    description: |
      The primary actor executing this flow. May be a specific concept ID
      (C-SHOP-USER) or a role description (authenticated user, admin).
    examples:
      - "C-SHOP-USER"
      - "Authenticated User"
      - "System Administrator"
      - "Scheduled Job"

  goal:
    type: string
    minLength: 10
    maxLength: 500
    description: |
      The user or system goal this flow achieves. Should be expressed as an
      outcome, not a list of actions.
    examples:
      - "Convert a shopping basket into a paid order"
      - "Assume a cross-account IAM role to access resources"
      - "Deploy a new pod with appropriate security constraints"

  trigger:
    $ref: "#/$defs/FlowTrigger"
    description: |
      What initiates this flow. Can be user-initiated, system-initiated,
      event-driven, or scheduled.

  scope:
    type: string
    description: |
      Boundary of this flow. Clarifies what is included and excluded.
    examples:
      - "From basket creation to payment confirmation"
      - "Authentication through resource access, excluding audit logging"

  preconditions:
    type: array
    minItems: 1
    items:
      $ref: "#/$defs/FlowCondition"
    description: |
      Conditions that must hold before the flow can begin. Include invariant
      references and any required starting states.

  steps:
    type: array
    minItems: 1
    items:
      $ref: "#/$defs/FlowStep"
    description: |
      Ordered sequence of interactions that comprise this flow. Each step
      references an Interaction ID and includes purpose and context.

  postconditions:
    type: array
    minItems: 1
    items:
      $ref: "#/$defs/FlowCondition"
    description: |
      Conditions that must hold after successful completion. Include invariant
      references and final state guarantees.

  variants:
    type: array
    items:
      $ref: "#/$defs/FlowVariant"
    description: |
      Alternative paths through the flow based on conditions (payment method,
      feature flags, user type, etc.).

  state_map:
    $ref: "#/$defs/StateMap"
    description: |
      Optional visual representation of concept state transitions driven
      by this flow.

  related:
    $ref: "#/$defs/RelatedArtifacts"
    description: |
      References to related concepts, interactions, scenarios, and explorations.

  security_insights:
    $ref: "#/$defs/FlowSecurityInsights"
    description: |
      Security considerations including identity continuity, cross-tenant
      boundaries, idempotency, and race conditions.

  observability:
    $ref: "#/$defs/FlowObservability"
    description: |
      Add only after live validation. Documents concrete commands and sample
      outputs that prove the flow executed correctly.

  status:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ArtifactStatus"
    default: "DRAFT"
    description: |
      Lifecycle status of this flow artifact.

  version:
    type: string
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    description: |
      Semantic version of this flow definition.
    examples:
      - "1.0.0"
      - "2.1.3"

  extensions:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/Extensions"
    description: |
      Optional extension-specific fields. Extensions MUST be declared by the
      corpus to be validated. See foundations/extensions.md.

additionalProperties: false

$defs:
  FlowTrigger:
    title: "Flow Trigger"
    description: "What initiates this flow"
    type: object
    required:
      - type
      - description
    properties:
      type:
        type: string
        enum:
          - user_action
          - system_event
          - scheduled
          - api_call
          - webhook
          - message
        description: "Type of trigger"
      description:
        type: string
        description: "What specifically triggers the flow"
      initial_interaction:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InteractionID"
        description: "Initial interaction that starts the flow (I-*), not an EP-* Entry Point artifact"
      event:
        type: string
        description: "Event name or pattern if event-driven"
      schedule:
        type: string
        description: "Cron expression or schedule description"
    additionalProperties: false

  FlowCondition:
    title: "Flow Condition"
    description: "A precondition or postcondition for the flow"
    type: object
    required:
      - type
    properties:
      type:
        type: string
        enum:
          - invariant
          - state
          - attribute
          - exists
          - custom
        description: "Type of condition"
      invariant:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
        description: "Invariant reference (when type=invariant)"
      concept:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ConceptID"
        description: "Concept reference (when type=state or attribute)"
      state:
        type: string
        description: "Required state value (when type=state)"
      attribute:
        type: string
        description: "Attribute name (when type=attribute)"
      value:
        description: "Required attribute value"
      expression:
        type: string
        description: "Custom condition expression (when type=custom)"
      description:
        type: string
        description: "Human-readable description of the condition"
    additionalProperties: false

  FlowStep:
    title: "Flow Step"
    description: "A single step in the flow sequence"
    type: object
    required:
      - order
      - actor
      - interaction
      - purpose
    properties:
      order:
        type: integer
        minimum: 1
        description: "Step sequence number (1-based)"
      actor:
        type: string
        description: "Who performs this step"
      interaction:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InteractionID"
        description: "Reference to the interaction being executed"
      purpose:
        type: string
        description: "Why this step is performed in the flow context"
      pre:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
        description: "Step-specific pre-invariants (may narrow flow preconditions)"
      post:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
        description: "Step-specific post-invariants (may extend flow postconditions)"
      conditional:
        type: string
        description: "Condition expression for optional steps"
      on_success:
        type: integer
        description: "Next step on success (defaults to order+1)"
      on_failure:
        type: string
        enum:
          - abort
          - retry
          - skip
          - compensate
          - continue
        default: "abort"
        description: "Failure handling strategy"
      compensation:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InteractionID"
        description: "Compensation interaction if step needs rollback"
      notes:
        type: string
        description: "Additional context for this step"
    additionalProperties: false

  FlowVariant:
    title: "Flow Variant"
    description: "An alternative path through the flow"
    type: object
    required:
      - name
      - condition
    properties:
      name:
        type: string
        description: "Variant name (e.g., 'credit_card', 'wallet')"
      condition:
        type: string
        description: "When this variant applies"
      steps:
        type: array
        items:
          $ref: "#/$defs/FlowStep"
        description: "Replacement or additional steps for this variant"
      replaces:
        type: array
        items:
          type: integer
        description: "Which step numbers this variant replaces"
      inserts_after:
        type: integer
        description: "Insert variant steps after this step number"
      postconditions:
        type: array
        items:
          $ref: "#/$defs/FlowCondition"
        description: "Variant-specific postconditions"
    additionalProperties: false

  StateMap:
    title: "State Map"
    description: "Visual representation of state transitions in this flow"
    type: object
    required:
      - concept
      - states
      - transitions
    properties:
      concept:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ConceptID"
        description: "Primary concept whose state is tracked"
      states:
        type: array
        items:
          type: string
        description: "States visited during the flow"
      transitions:
        type: array
        items:
          $ref: "#/$defs/StateMapTransition"
        description: "State transitions triggered by flow steps"
    additionalProperties: false

  StateMapTransition:
    title: "State Map Transition"
    description: "A state transition in the flow's state map"
    type: object
    required:
      - from
      - to
      - step
    properties:
      from:
        type: string
        description: "Starting state"
      to:
        type: string
        description: "Ending state"
      step:
        type: integer
        description: "Which flow step triggers this transition"
      interaction:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InteractionID"
        description: "Interaction that causes the transition"
      guard:
        $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
        description: "Guard invariant for this transition"
    additionalProperties: false

  RelatedArtifacts:
    title: "Related Artifacts"
    description: "References to related CFSE artifacts"
    type: object
    properties:
      concepts:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ConceptID"
        description: "Concepts involved in this flow"
      interactions:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InteractionID"
        description: "All interactions referenced by flow steps"
      scenarios:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ScenarioID"
        description: "Scenarios that target this flow"
      explorations:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ExplorationID"
        description: "Explorations that execute this flow"
    additionalProperties: false

  FlowSecurityInsights:
    title: "Flow Security Insights"
    description: "Security considerations for the flow"
    type: object
    properties:
      identity_continuity:
        type: string
        description: "How identity is maintained across steps"
      cross_tenant:
        type: string
        description: "Cross-tenant boundary considerations"
      idempotency:
        type: string
        description: "Idempotency guarantees and requirements"
      compensation:
        type: string
        description: "Rollback and compensation strategies"
      timeouts:
        type: string
        description: "Timeout considerations between steps"
      race_conditions:
        type: array
        items:
          type: string
        description: "Potential race conditions"
      trust_boundaries:
        type: array
        items:
          type: string
        description: "Trust boundaries crossed during flow"
    additionalProperties: false

  FlowObservability:
    title: "Flow Observability"
    description: "Live validation evidence - add only after testing"
    type: object
    properties:
      commands:
        type: array
        items:
          $ref: "#/$defs/ObservabilityCommand"
        description: "Commands used to validate each step"
      sample_outputs:
        type: array
        items:
          type: string
        description: "Minimal sample outputs proving execution"
      validated_at:
        type: string
        format: date-time
        description: "When live validation was performed"
      environment:
        type: string
        description: "Environment where validation occurred"
    additionalProperties: false

  ObservabilityCommand:
    title: "Observability Command"
    description: "A command used for live validation"
    type: object
    required:
      - step
      - type
      - command
    properties:
      step:
        type: integer
        description: "Which flow step this validates"
      type:
        type: string
        enum:
          - curl
          - httpie
          - cli
          - db_query
          - other
        description: "Type of command"
      command:
        type: string
        description: "The actual command"
      description:
        type: string
        description: "What this command validates"
    additionalProperties: false