# Workflow Schema — Layer 3 Domain Type
# This file defines the schema for workflow documents.
# A workflow describes a sequence of steps that transform inputs to outputs.
#
# Version: 0.2.0
# Status: Draft
# Last Updated: 2026-02-21
#
# KEY RELATIONSHIP: Workflows PRODUCE activities.
# When a workflow executes, each step generates activity records.
# This is the foundational semantic link in the observability ontology.

# =============================================================================
# @kno:manifest
# =============================================================================
$schema: kno@0.0.9
id: 01KGK3V73EGN38EF0KEX2NWGYF
slug: workflow-schema
type: spec
version: 0.2.0

title: "Workflow Schema"
purpose: |
  Define the schema for workflow documents — operational specifications
  that describe HOW things happen in a system.

  **Workflow vs Activity:**
  - Workflow: The template/specification (defined once)
  - Activity: A record of occurrence (created many times)

  When a workflow executes:
  1. Each step produces one or more activity records
  2. Activities reference their workflow via `workflow.id`
  3. Activities within same execution share `workflow.instanceId`

# =============================================================================
# @kno:taxonomy
# =============================================================================
taxonomy:
  topics:
    - workflows
    - processes
    - orchestration
    - operations
  keywords:
    - workflow
    - process
    - steps
    - automation
    - orchestration
    - pipeline

# =============================================================================
# @kno:relationships
# =============================================================================

# =============================================================================
# RICH TIER (provenance)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73EGN38EF0KEX2NWGYF
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type for all documents"
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"
  composes:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, canonical_id, local_ids"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation"
  produces:
    - xri: "kno://specs/activity-schema"
      reason: "Workflow execution produces activity records"
  enables:
    - xri: "kno://workflows/activity-logging"
      reason: "Activity logging workflow instance"
    - xri: "kno://workflows/corpus-import"
      reason: "Corpus import workflow instance"
  related_to:
    - xri: "kno://specs/spec-schema"
      reason: "Sibling Layer 3 type"
    - xri: "kno://external/github-actions"
      reason: "External workflow system"

  implements:
    - xri: "kno://principles/P9"
      reason: "Temporal/Historical — workflows in Hive are versioned"
    - xri: "kno://principles/VCS-Mandatory-Rule"
      reason: "Generated workflows promoted to Hive MUST be recorded in VCS"

# =============================================================================
# @kno:quality
# =============================================================================
quality:
  completeness: 0.80
  last_reviewed: "2026-01-27"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# @kno:history
# =============================================================================
_history:
  version: 2
  created: "2026-01-27T12:00:00Z"
  created_by: "claude"
  modified: "2026-02-21T00:00:00Z"
  modified_by: "claude"

# =============================================================================
# @kno:index
# Navigation index for agent-optimized retrieval
# =============================================================================
_index:
  - path: "overview"
    line: 130
    keywords: [workflow, activity, produces, ontology]
  - path: "schema"
    line: 200
    keywords: [fields, required, properties]
  - path: "schema/workflow-fields"
    line: 280
    keywords: [type, trigger, steps, outputs]
  - path: "schema/step-structure"
    line: 350
    keywords: [step, id, depends_on, implementation]
  - path: "examples"
    line: 450
    keywords: [minimal, event-triggered, example]

# =============================================================================
# @kno:contains
# What this container holds (discovery manifest)
# =============================================================================
contains:
  - xri: "#overview"
    role: section
    title: "Overview"
    keywords: [workflow, activity, produces]
  - xri: "#schema"
    role: section
    title: "Schema Definition"
    keywords: [fields, validation, required]
  - xri: "#examples"
    role: section
    title: "Examples"
    keywords: [minimal, usage]

# =============================================================================
# NESTED CONTENT
# =============================================================================
_contains:
  # ===========================================================================
  # @kno:overview
  # ===========================================================================
  overview:
    $schema: kno-section@0.0.1
    id: overview
    title: "Overview"

    content:
      definition: |
        A **workflow** is a document that describes a sequence of steps that
        transform inputs to outputs. Workflows are operational specifications —
        they describe HOW things happen in a system.

      comparison: |
        | Aspect | Workflow | Activity |
        |--------|----------|----------|
        | Nature | Template/specification | Record of occurrence |
        | Timing | Defined once | Created many times |
        | Example | "User onboarding workflow" | "Alice signed up at 3pm" |
        | Schema | `type: workflow` | `type: activity` |

      produces_relationship: |
        This is the key semantic relationship in the ontology:

        ┌──────────────────────┐         ┌──────────────────────┐
        │  workflow-schema.kno │─────────│  activity-schema.kno │
        │  (Layer 3)           │ produces│  (Layer 3)           │
        └──────────────────────┘         └──────────────────────┘
                │                                   │
                │ instances                         │ instances
                ▼                                   ▼
        ┌──────────────────────┐         ┌──────────────────────┐
        │  activity-logging    │ ─────── │  "User created       │
        │  workflow instance   │ produces│   invite at 3pm"     │
        └──────────────────────┘         └──────────────────────┘

      layer_position: |
        Workflow extends document (Layer 2), which composes Layer 1 primitives:

        workflow-schema.kno
        └── extends: document-schema.kno
            └── composes: identity-schema.kno, history-schema.kno, quality-schema.kno

  # ===========================================================================
  # @kno:schema
  # ===========================================================================
  schema:
    $schema: kno-section@0.0.1
    id: schema
    title: "Schema Definition"

    content:
      overview: |
        The workflow schema defines required and optional fields for
        workflow documents. All workflows inherit from document-schema.kno.

      required_fields:
        - id
        - type
        - version
        - title
        - workflow

    _contains:
      # @kno:schema/workflow-fields
      workflow-fields:
        $schema: kno-section@0.0.1
        id: workflow-fields
        title: "Workflow-Specific Fields"

        content:
          workflow:
            type: object
            required:
              - type
              - steps
            description: "Workflow definition content"
            properties:
              type:
                type: string
                enum:
                  - linear
                  - branching
                  - parallel
                  - event-driven
                description: |
                  Workflow execution model:
                  - linear: Steps execute in sequence
                  - branching: Steps may branch based on conditions
                  - parallel: Steps may execute concurrently
                  - event-driven: Steps triggered by events

              trigger:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - event
                      - schedule
                      - manual
                      - api
                  description:
                    type: string
                  event_type:
                    type: string
                  schedule:
                    type: string

              inputs:
                type: object
                description: "Workflow-level input parameters"

              outputs:
                type: object
                description: "Workflow-level output values"

              steps:
                type: array
                description: "Ordered list of workflow steps"

      # @kno:schema/step-structure
      step-structure:
        $schema: kno-section@0.0.1
        id: step-structure
        title: "Step Structure"

        content:
          description: |
            Each step in a workflow has the following structure.

          step_schema:
            required:
              - id
              - name
              - type
            properties:
              id:
                type: string
                pattern: "^[a-z][a-z0-9-]*$"
                description: "Unique step identifier within workflow"

              name:
                type: string
                description: "Human-readable step name"

              type:
                type: string
                enum:
                  - activity
                  - decision
                  - parallel
                  - wait
                  - subprocess
                description: |
                  Step types:
                  - activity: Performs action, produces activity record
                  - decision: Branches based on condition
                  - parallel: Executes multiple steps concurrently
                  - wait: Waits for external event
                  - subprocess: Invokes another workflow

              description:
                type: string

              depends_on:
                type: array
                items:
                  type: string
                description: "Step IDs that must complete first"

              inputs:
                type: object

              outputs:
                type: object

              implementation:
                type: object
                properties:
                  file:
                    type: string
                  function:
                    type: string
                  service:
                    type: string
                  endpoint:
                    type: string

              error_handling:
                type: array
                items:
                  type: object
                  properties:
                    scenario:
                      type: string
                    action:
                      type: string

  # ===========================================================================
  # @kno:examples
  # ===========================================================================
  examples:
    $schema: kno-section@0.0.1
    id: examples
    title: "Examples"

    content:
      minimal_workflow: |
        $schema: kno@0.0.9
        conforms_to: workflow-schema@0.1

        id: hello-world
        type: workflow
        version: 0.1.0
        title: "Hello World Workflow"

        workflow:
          type: linear
          steps:
            - id: greet
              name: "Say Hello"
              type: activity
              description: "Produces a greeting activity"

      event_triggered_workflow: |
        $schema: kno@0.0.9
        conforms_to: workflow-schema@0.1

        id: user-onboarding
        type: workflow
        version: 0.1.0
        title: "User Onboarding Workflow"

        workflow:
          type: linear
          trigger:
            type: event
            event_type: "user.created"
            description: "Triggered when a new user is created"
          steps:
            - id: send-welcome
              name: "Send Welcome Email"
              type: activity
              implementation:
                service: pspace-email
                endpoint: /send
            - id: create-workspace
              name: "Create User Workspace"
              type: activity
              depends_on:
                - send-welcome
              implementation:
                service: pspace-api
                endpoint: /users/{id}/workspace

# =============================================================================
# DESIGN NOTES
# =============================================================================
_design_notes:
  decisions:
    - "Workflows are specifications, not executions — state lives in activities"
    - "The PRODUCES relationship is central to the ontology"
    - "Step types are extensible — five core types cover most patterns"
    - "Implementation is optional — workflows can be documentary or executable"
    - "Error handling is per-step, not global"

  future:
    - "Compensation patterns for saga-style rollback"
    - "Versioning strategy for workflow migrations"
    - "Runtime state schema for execution instances"