Playbook Designer

flowchart TD
    subgraph "Web App (apps/app)"
        UI["Playbook Designer UI\nReact Flow + Property Panel"]
        API_CLIENT["tRPC / Server Actions"]
    end

    subgraph "API Layer (apps/api)"
        ROUTES["Hono Routes\n/v1/playbooks/*"]
        KERNEL["kernel.invoke()"]
    end

    subgraph "Kernel Capabilities"
        PB_CAPS["playbook.* contracts\n(CRUD, publish, run, export)"]
    end

    subgraph "Storage"
        PG["PostgreSQL\nworkflow schema\n9 tables"]
        NEO["Neo4j\nOntology graph\n(context injection)"]
        CH["ClickHouse\nAudit events\n(hash chain stream)"]
    end

    subgraph "Execution"
        INN["Inngest\nplaybook.run.execute\nplaybook.trigger.match"]
    end

    subgraph "Portability"
        YAML["YAML Files\n.oxagen/playbooks/*.yaml\n(git-tracked seeds)"]
    end

    UI --> API_CLIENT
    API_CLIENT --> ROUTES
    ROUTES --> KERNEL
    KERNEL --> PB_CAPS
    PB_CAPS --> PG
    PB_CAPS --> NEO
    PB_CAPS --> CH
    PB_CAPS --> INN
    PB_CAPS <--> YAML

.oxagen/
  playbooks/
    monthly-kg-audit.yaml        # seed playbook (shipped to customers)
    new-source-onboarding.yaml
    billing-anomaly-check.yaml
  playbooks.lock                 # SHA-256 manifest of deployed versions

# .oxagen/playbooks/monthly-kg-audit.yaml
schemaVersion: "1.0.0"

metadata:
  name: Monthly Knowledge Graph Audit
  slug: monthly-kg-audit
  description: >
    Validates entity freshness, removes stale nodes older than 90 days,
    and generates a reconciliation report.
  version: "1.2.0"
  tags: [knowledge-graph, maintenance]
  visibility: workspace          # private | workspace | organization | marketplace
  author: platform-team
  requiresApproval: true

parameters:
  staleness_days:
    type: integer
    default: 90
    description: Days after which an entity is considered stale
    validation:
      minimum: 7
      maximum: 365
  report_channel:
    type: string
    default: "#kg-alerts"
    description: Slack channel for the reconciliation report

triggers:
  - type: schedule
    config:
      cron: "0 9 1 * *"        # First of month, 09:00 UTC
  - type: event
    config:
      entityType: knowledge_node
      eventType: node.stale_detected
      propertyConditions:
        - property: days_since_update
          operator: gt
          toValue: "{{staleness_days}}"

steps:
  - key: validate_freshness
    name: Validate Entity Freshness
    type: tool
    config:
      capability: ontology.entity.audit
      input:
        staleness_threshold: "{{staleness_days}}"
        workspace_id: "{{context.workspaceId}}"
    position: { x: 100, y: 100 }

  - key: check_stale_count
    name: Check Stale Count
    type: condition
    config:
      propertyConditions:
        - property: stale_count
          operator: gt
          toValue: 0
    position: { x: 300, y: 100 }

  - key: remove_stale_nodes
    name: Remove Stale Nodes
    type: tool
    config:
      capability: ontology.entity.bulk_archive
      input:
        entity_ids: "{{steps.validate_freshness.output.stale_entity_ids}}"
    exitOnError: true
    requiresApproval: true
    position: { x: 500, y: 50 }

  - key: generate_report
    name: Generate Reconciliation Report
    type: agent
    config:
      prompt: >
        Summarize the knowledge graph audit results.
        {{steps.validate_freshness.output.summary}}
        Stale nodes archived: {{steps.remove_stale_nodes.output.archived_count}}
      model: sonnet
    position: { x: 500, y: 200 }

  - key: notify_channel
    name: Notify Slack Channel
    type: webhook
    config:
      url: "{{secrets.SLACK_WEBHOOK_URL}}"
      method: POST
      headers:
        Content-Type: application/json
      body: |
        {
          "channel": "{{report_channel}}",
          "text": "{{steps.generate_report.output}}"
        }
    position: { x: 700, y: 100 }

edges:
  - from: validate_freshness
    to: check_stale_count
    type: default

  - from: check_stale_count
    to: remove_stale_nodes
    type: default
    condition: { passed: true }

  - from: check_stale_count
    to: generate_report
    type: conditional
    condition: { passed: false }

  - from: remove_stale_nodes
    to: generate_report
    type: default

  - from: generate_report
    to: notify_channel
    type: default

-- Formal parameter declarations (runtime inputs to the playbook)
CREATE TABLE workflow.playbook_parameters (
  id              UUID PRIMARY KEY DEFAULT uuidv7(),
  playbook_version_id UUID NOT NULL REFERENCES workflow.playbook_versions(id),
  param_key       CITEXT NOT NULL,
  param_type      TEXT NOT NULL CHECK (param_type IN (
    'string','integer','number','boolean','array','object','secret'
  )),
  description     TEXT,
  default_value   JSONB,
  validation      JSONB,         -- { minimum, maximum, pattern, enum, ... }
  is_required     BOOLEAN NOT NULL DEFAULT true,
  display_order   INTEGER NOT NULL DEFAULT 0,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  UNIQUE (playbook_version_id, param_key)
);

-- Ephemeral designer state (viewport, selection, draft edits)
-- This is NOT versioned — it's per-user working state
CREATE TABLE workflow.playbook_canvas_state (
  id              UUID PRIMARY KEY DEFAULT uuidv7(),
  org_id          UUID NOT NULL,
  workspace_id    UUID NOT NULL,
  playbook_id     UUID NOT NULL REFERENCES workflow.playbooks(id),
  user_id         UUID NOT NULL,
  viewport        JSONB NOT NULL DEFAULT '{"x":0,"y":0,"zoom":1}',
  selected_nodes  JSONB NOT NULL DEFAULT '[]',
  panel_state     JSONB NOT NULL DEFAULT '{}',
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  UNIQUE (playbook_id, user_id)
);

-- Published playbooks available for cross-org installation
CREATE TABLE workflow.playbook_marketplace_listings (
  id              UUID PRIMARY KEY DEFAULT uuidv7(),
  org_id          UUID NOT NULL,
  playbook_id     UUID NOT NULL REFERENCES workflow.playbooks(id),
  version_id      UUID NOT NULL REFERENCES workflow.playbook_versions(id),
  title           TEXT NOT NULL,
  description     TEXT,
  category        TEXT NOT NULL,
  tags            JSONB NOT NULL DEFAULT '[]',
  install_count   INTEGER NOT NULL DEFAULT 0,
  is_verified     BOOLEAN NOT NULL DEFAULT false,
  is_featured     BOOLEAN NOT NULL DEFAULT false,
  published_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  unpublished_at  TIMESTAMPTZ,

  UNIQUE (playbook_id, version_id)
);
CREATE INDEX idx_marketplace_category ON workflow.playbook_marketplace_listings(category)
  WHERE unpublished_at IS NULL;

-- Add to playbook_steps for enhanced designer support
ALTER TABLE workflow.playbook_steps
  ADD COLUMN display_config JSONB DEFAULT '{}',  -- { color, icon, width, collapsed }
  ADD COLUMN notes TEXT;                         -- Designer-only annotation

-- Add to playbooks for YAML sync tracking
ALTER TABLE workflow.playbooks
  ADD COLUMN yaml_source_path TEXT,              -- e.g. ".oxagen/playbooks/monthly-kg-audit.yaml"
  ADD COLUMN last_synced_at TIMESTAMPTZ,
  ADD COLUMN sync_direction TEXT CHECK (sync_direction IN ('push', 'pull', 'bidirectional'));

graph TD
    PAGE["PlaybookDesignerPage"]
    TOOLBAR["DesignerToolbar\n(save, publish, run, export, undo/redo)"]
    CANVAS["DesignerCanvas\n(React Flow)"]
    PALETTE["StepPalette\n(draggable step types)"]
    PROPS["PropertyPanel\n(selected node config)"]
    MINIMAP["Minimap"]
    RUNS["RunHistoryPanel"]
    VERSIONS["VersionTimeline"]
    TRIGGERS["TriggerConfigPanel"]

    PAGE --> TOOLBAR
    PAGE --> CANVAS
    PAGE --> PALETTE
    PAGE --> PROPS
    CANVAS --> MINIMAP
    PAGE --> RUNS
    PAGE --> VERSIONS
    PAGE --> TRIGGERS

┌──────────────────────────────────┐
│ Step: Remove Stale Nodes         │
│ Type: Tool                       │
├──────────────────────────────────┤
│ Capability: ontology.entity.*    │ ← Autocomplete from registry
│ Input Mapping:                   │
│   entity_ids: {{steps.validate   │ ← Expression editor with
│     _freshness.output.stale_...}}│   autocomplete for step refs
├──────────────────────────────────┤
│ ☑ Exit on Error                  │
│ ☑ Requires Approval              │
│ Timeout: 30s                     │
│ Retry: { maxAttempts: 3 }        │
├──────────────────────────────────┤
│ Notes: This step archives nodes  │ ← Designer annotation
│ that haven't been updated...     │
└──────────────────────────────────┘

sequenceDiagram
    participant Runner as Inngest Runner
    participant PG as PostgreSQL
    participant Neo as Neo4j
    participant Step as Step Executor

    Runner->>PG: Load step config
    Runner->>Runner: Detect {{ontology.*}} templates
    Runner->>Neo: MATCH (n:EntityType) WHERE n.property = value RETURN n
    Neo-->>Runner: Entity properties
    Runner->>Runner: Interpolate templates
    Runner->>Step: Execute with resolved config

# Query a specific entity by natural key
input:
  customer_name: "{{ontology.customer[natural_key='acme-corp'].name}}"
  contract_value: "{{ontology.contract[customer='acme-corp'].annual_value}}"

# Query entities matching conditions (returns array)
input:
  stale_entities: "{{ontology.knowledge_node[days_since_update > staleness_days]}}"

# Traverse relationships
input:
  owner_email: "{{ontology.service[name='auth-api'].owned_by.email}}"

- key: find_related_services
  name: Find Related Services
  type: knowledge_search
  config:
    query: |
      MATCH (s:Service)-[:DEPENDS_ON]->(d:Service)
      WHERE s.name = $service_name
      RETURN d.name, d.health_status
    parameters:
      service_name: "{{trigger.payload.service_name}}"
    limit: 50
    outputMapping:
      dependencies: result.rows
      unhealthy_count: "result.rows | filter(.health_status != 'healthy') | length"

graphHash = SHA-256(
  canonical_json_sort(steps[].{stepKey, stepType, config}) +
  canonical_json_sort(edges[].{sourceStepKey, targetStepKey, edgeType, condition})
)

stateDiagram-v2
    [*] --> Running: playbook.run.start
    Running --> WaitingApproval: step.requiresApproval = true
    WaitingApproval --> Running: approval.resolve(approved)
    WaitingApproval --> Cancelled: approval.resolve(denied)
    WaitingApproval --> Expired: approval.expiresAt reached
    Running --> Completed: all steps done
    Running --> Failed: step error + exitOnError
    Expired --> Cancelled: auto-cancel

.oxagen/playbooks/
  monthly-kg-audit.yaml
  new-source-onboarding.yaml
  stale-entity-cleanup.yaml
  billing-reconciliation.yaml
  competitor-monitoring.yaml
  security-posture-check.yaml
  data-quality-report.yaml
  connector-health-check.yaml

// packages/oxagen/src/contracts/playbook/yaml-schema.ts

import { z } from "zod";

export const PlaybookParameterSchema = z.object({
  type: z.enum(["string", "integer", "number", "boolean", "array", "object", "secret"]),
  default: z.unknown().optional(),
  description: z.string().optional(),
  validation: z.object({
    minimum: z.number().optional(),
    maximum: z.number().optional(),
    minLength: z.number().optional(),
    maxLength: z.number().optional(),
    pattern: z.string().optional(),
    enum: z.array(z.union([z.string(), z.number()])).optional(),
  }).optional(),
});

export const TriggerConfigSchema = z.discriminatedUnion("type", [
  z.object({
    type: z.literal("schedule"),
    config: z.object({ cron: z.string() }),
  }),
  z.object({
    type: z.literal("event"),
    config: z.object({
      entityType: z.string(),
      eventType: z.string().optional(),
      propertyConditions: z.array(z.object({
        property: z.string(),
        operator: z.enum(["eq", "gt", "lt", "changed"]),
        toValue: z.union([z.string(), z.number()]).optional(),
      })).optional(),
    }),
  }),
  z.object({
    type: z.literal("api"),
    config: z.object({
      rateLimit: z.object({ maxPerHour: z.number() }).optional(),
    }).optional(),
  }),
]);

export const StepSchema = z.object({
  key: z.string().regex(/^[a-z][a-z0-9_]*$/),
  name: z.string().min(1).max(100),
  type: z.enum([
    "tool", "agent", "prompt", "condition", "webhook", "approval",
    "human_input", "transform", "loop", "parallel", "delay",
    "sub_playbook", "knowledge_search", "code_execution",
  ]),
  config: z.record(z.unknown()),
  position: z.object({ x: z.number(), y: z.number() }).optional(),
  isAsync: z.boolean().optional().default(false),
  exitOnError: z.boolean().optional().default(true),
  timeoutSeconds: z.number().optional(),
  retryPolicy: z.object({
    maxAttempts: z.number().min(1).max(10),
    backoffMs: z.number().optional(),
  }).optional(),
  requiresApproval: z.boolean().optional().default(false),
  notes: z.string().optional(),
});

export const EdgeSchema = z.object({
  from: z.string(),
  to: z.string(),
  type: z.enum(["default", "conditional", "on_error", "loop_back", "parallel"]),
  condition: z.record(z.unknown()).optional(),
  priority: z.number().optional().default(0),
});

export const PlaybookYamlSchema = z.object({
  schemaVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
  metadata: z.object({
    name: z.string().min(1).max(100),
    slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
    description: z.string().optional(),
    version: z.string().regex(/^\d+\.\d+\.\d+$/),
    tags: z.array(z.string()).optional().default([]),
    visibility: z.enum(["private", "workspace", "organization", "marketplace"]).default("workspace"),
    author: z.string().optional(),
    requiresApproval: z.boolean().optional().default(false),
  }),
  parameters: z.record(PlaybookParameterSchema).optional().default({}),
  triggers: z.array(TriggerConfigSchema).optional().default([]),
  steps: z.array(StepSchema).min(1),
  edges: z.array(EdgeSchema).optional().default([]),
});

export type PlaybookYaml = z.infer<typeof PlaybookYamlSchema>;
export type PlaybookStep = z.infer<typeof StepSchema>;
export type PlaybookEdge = z.infer<typeof EdgeSchema>;
export type PlaybookParameter = z.infer<typeof PlaybookParameterSchema>;

// packages/oxagen/src/contracts/playbook/designer-types.ts

import type { Node, Edge } from "reactflow";

/** Step node data rendered on the canvas */
export interface StepNodeData {
  stepKey: string;
  name: string;
  stepType: PlaybookStepType;
  config: Record<string, unknown>;
  isAsync: boolean;
  exitOnError: boolean;
  requiresApproval: boolean;
  timeoutSeconds?: number;
  retryPolicy?: { maxAttempts: number; backoffMs?: number };
  notes?: string;
  displayConfig?: {
    color?: string;
    icon?: string;
    width?: number;
    collapsed?: boolean;
  };
  // Runtime state (during live run visualization)
  runStatus?: "pending" | "running" | "completed" | "failed" | "skipped" | "waiting_approval";
}

export type StepNode = Node<StepNodeData>;

export interface PlaybookEdgeData {
  edgeType: "default" | "conditional" | "on_error" | "loop_back" | "parallel";
  condition?: Record<string, unknown>;
  priority: number;
  label?: string;
}

export type PlaybookEdge = Edge<PlaybookEdgeData>;

/** Designer store state (Zustand) */
export interface DesignerState {
  // Playbook metadata
  playbookId: string | null;
  versionId: string | null;
  isDraft: boolean;
  isDirty: boolean;

  // Canvas state
  nodes: StepNode[];
  edges: PlaybookEdge[];
  selectedNodeId: string | null;
  viewport: { x: number; y: number; zoom: number };

  // Parameters
  parameters: Record<string, PlaybookParameter>;

  // Triggers
  triggers: TriggerConfig[];

  // History (undo/redo)
  history: DesignerCommand[];
  historyIndex: number;

  // Actions
  addStep: (type: PlaybookStepType, position: { x: number; y: number }) => void;
  updateStep: (nodeId: string, data: Partial<StepNodeData>) => void;
  removeStep: (nodeId: string) => void;
  connectSteps: (from: string, to: string, edgeType?: string) => void;
  disconnectSteps: (edgeId: string) => void;
  undo: () => void;
  redo: () => void;
  save: () => Promise<void>;
  publish: () => Promise<void>;
  exportYaml: () => string;
  importYaml: (yaml: string) => void;
}

flowchart LR
    RAW["Raw step config\n(JSONB from DB)"] --> P1["Phase 1: Parameters\n{{paramName}} → value"]
    P1 --> P2["Phase 2: Context\n{{context.*}} → runtime ctx"]
    P2 --> P3["Phase 3: Step Refs\n{{steps.*.output}} → prior output"]
    P3 --> P4["Phase 4: Secrets\n{{secrets.*}} → vault lookup"]
    P4 --> P5["Phase 5: Ontology\n{{ontology.*}} → Neo4j query"]
    P5 --> RESOLVED["Fully resolved config\n→ Step executor"]

interface KnowledgeSearchConfig {
  // Raw Cypher query with $param placeholders
  query: string;
  // Parameters to bind (supports template interpolation)
  parameters?: Record<string, unknown>;
  // Max rows returned
  limit?: number;
  // Map result columns to output fields
  outputMapping?: Record<string, string>;
}

interface CodeExecutionConfig {
  runtime: "javascript" | "python" | "bash";
  code: string;
  timeout?: number;     // max seconds (default 30)
  memoryMb?: number;    // max memory (default 128)
  // Input variables available as `context` in the script
  inputMapping?: Record<string, string>;
}

// GET /v1/playbooks/:id/runs/:runId/live
interface LiveRunUpdate {
  runId: string;
  status: "running" | "paused" | "completed" | "failed";
  currentStepId: string | null;
  stepStatuses: Record<string, {
    status: "pending" | "running" | "completed" | "failed" | "waiting_approval";
    startedAt?: string;
    completedAt?: string;
    output?: unknown;
    error?: string;
  }>;
  eventCount: number;
  lastEventHash: string;
}