LagomDocument specification

interface LagomDocument {
  $schema: string;              // Schema URL for validation
  lagomVersion: string;         // Spec version (e.g. "1.0")
  kind: "LagomDocument";        // Discriminator
  id: string;                   // Stable unique identifier
  title: string;                // Document title
  description?: string;         // Optional summary
  documentType: DocumentType;   // sop | policy | playbook | ...
  status: DocumentStatus;       // draft | active | deprecated | archived
  owner?: OwnerRef;             // Owner team or person
  aliases?: string[];           // Alternative names for resolution
  sections: LagomSection[];     // Ordered content sections
  variables?: LagomVariable[];  // Document-scoped variables
  entities?: BusinessEntityRef[];  // Referenced business entities
  connectors?: ConnectorRef[];  // External system connectors
  actions?: AgentAction[];      // Declared agent actions
  governance?: GovernanceMetadata;  // Ownership and review rules
  references?: DocumentReference[];  // Typed relationships
  extensions?: Record<string, unknown>;  // Namespaced custom data
}

interface LagomSection {
  id: string;                   // Stable section identifier
  title: string;                // Section heading
  elements: LagomElement[];     // Ordered typed blocks
  visibility?: VisibilityScope; // internal | external | public | private
}

interface LagomElementBase {
  id: string;                   // Stable unique identifier
  elementType: string;           // Discriminator
  label?: string;               // Optional display label
  visible?: boolean;            // Render visibility (default: true)
  condition?: string;           // Variable expression for conditional display
}

interface HeadingElement extends LagomElementBase {
  elementType: "heading";
  level: 1 | 2 | 3 | 4 | 5 | 6;  // Heading depth
  content: string;              // Heading text (may contain inline markdown)
}

interface ParagraphElement extends LagomElementBase {
  elementType: "paragraph";
  content: string;              // Inline markdown content
}

interface MarkdownElement extends LagomElementBase {
  elementType: "markdown";
  content: string;              // Raw markdown block (multi-line)
}

interface BlockquoteElement extends LagomElementBase {
  elementType: "blockquote";
  content: string;              // Quoted text content
}

interface ListElement extends LagomElementBase {
  elementType: "list";
  ordered: boolean;             // Numbered vs bullet list
  items: string[];              // List item content (inline markdown)
}

interface HorizontalRuleElement extends LagomElementBase {
  elementType: "horizontal_rule";
}

interface CodeElement extends LagomElementBase {
  elementType: "code";
  language?: string;             // Syntax highlight language
  content: string;              // Code content
  title?: string;               // Optional caption
}

interface TableElement extends LagomElementBase {
  elementType: "table";
  title?: string;
  columns: string[];             // Column header labels
  rows: string[][];              // Row data (array of arrays)
}

interface ChecklistElement extends LagomElementBase {
  elementType: "checklist";
  title: string;
  items: string[];              // Checklist item labels
  variable?: string;            // Bind checked state to variable
}

interface RadioElement extends LagomElementBase {
  elementType: "radio";
  label: string;                // Input label
  options: string[];            // Selectable options
  variable: string;             // Variable to bind selected value
  default?: string;             // Pre-selected option
}

interface DropdownElement extends LagomElementBase {
  elementType: "dropdown";
  label: string;                // Input label
  options: string[];            // Selectable options
  variable: string;             // Variable to bind selected value
  default?: string;             // Pre-selected option
  placeholder?: string;        // Placeholder text
}

interface NumberElement extends LagomElementBase {
  elementType: "number";
  label: string;                // Input label
  variable: string;             // Variable to bind value
  min?: number;                // Minimum value
  max?: number;                // Maximum value
  step?: number;               // Increment step
  default?: number;            // Default value
}

interface SliderElement extends LagomElementBase {
  elementType: "slider";
  label: string;                // Input label
  variable: string;             // Variable to bind value
  min: number;                 // Minimum value
  max: number;                 // Maximum value
  step?: number;               // Increment step
  default?: number;            // Default position
}

interface TextboxElement extends LagomElementBase {
  elementType: "textbox";
  label: string;                // Input label
  variable: string;             // Variable to bind value
  placeholder?: string;        // Placeholder text
  multiline?: boolean;         // Allow multiline input
  maxLength?: number;          // Character limit
}

interface CardElement extends LagomElementBase {
  elementType: "card";
  title: string;
  content: string;              // Markdown body content
  style?: "default" | "highlight" | "warning" | "info";
  icon?: string;                // Icon identifier
}

interface GridElement extends LagomElementBase {
  elementType: "grid";
  title?: string;
  columns: number;              // Number of grid columns
  items: GridItem[];            // Grid cell items
}

interface GridItem {
  label: string;
  value: string;
  trend?: string;              // Trend indicator (e.g. "+12%")
  icon?: string;
}

interface ChartElement extends LagomElementBase {
  elementType: "chart";
  title: string;
  chartType: "line" | "bar" | "pie" | "area" | "scatter";
  xAxis?: string;               // X-axis label
  yAxis?: string;               // Y-axis label
  dataRef?: string;             // Reference to data source
  data?: Record<string, unknown>[];  // Inline data points
}

interface MermaidElement extends LagomElementBase {
  elementType: "mermaid";
  title?: string;
  diagram: string;              // Mermaid diagram syntax
}

interface ImageElement extends LagomElementBase {
  elementType: "image";
  src: string;                  // Image URL or relative path
  alt?: string;                 // Accessibility alt text
  caption?: string;             // Display caption
  width?: number;               // Display width in pixels
}

interface TabulatorElement extends LagomElementBase {
  elementType: "tabulator";
  title?: string;
  columns: TabulatorColumn[];  // Column definitions
  data?: Record<string, unknown>[];  // Inline row data
  dataRef?: string;             // External data source
  pagination?: boolean;        // Enable pagination
  sortable?: boolean;          // Enable column sorting
}

interface TabulatorColumn {
  field: string;
  title: string;
  type?: "string" | "number" | "date" | "boolean";
}

interface TreebarkElement extends LagomElementBase {
  elementType: "treebark";
  title?: string;
  spec: Record<string, unknown>;  // Treebark visual specification
}

interface ConnectorElement extends LagomElementBase {
  elementType: "connector";
  name: string;                 // Display name
  type: "saas" | "database" | "api" | "file";
  url?: string;                 // Connection endpoint
  connectionString?: string;   // Database connection string
  auth?: "oauth2" | "api-key" | "service-account" | "none";
  scopes?: string[];            // Required permission scopes
}

interface EntityElement extends LagomElementBase {
  elementType: "entity";
  name: string;                 // Business entity name (e.g. "Deal")
  source: string;               // Connector ID this entity belongs to
  fields?: EntityField[];       // Field definitions
}

interface EntityField {
  name: string;
  type: "string" | "number" | "date" | "boolean"
    | "currency" | "enum" | "reference";
  required?: boolean;
  description?: string;
}

interface DataReferenceElement extends LagomElementBase {
  elementType: "data_reference";
  title: string;
  source: string;               // Connector ID
  query?: string;               // Query expression
  refreshInterval?: string;    // Auto-refresh cadence (e.g. "1h")
  format?: "table" | "json" | "csv";
}

interface InstructionElement extends LagomElementBase {
  elementType: "instruction";
  role?: "system" | "user" | "assistant";  // Message role
  content: string;              // Instruction text (supports variable interpolation)
}

interface SkillElement extends LagomElementBase {
  elementType: "skill";
  name: string;                 // Skill name (for agent tool selection)
  description: string;          // What this skill does
  requiredContext?: string[];   // Variables that must be set before use
  outputVariable?: string;     // Variable to store the result
}

interface AssetElement extends LagomElementBase {
  elementType: "asset";
  name: string;                 // Asset display name
  type: "document" | "data" | "template" | "image";
  source?: string;              // Path or URL to the asset
  description?: string;        // What this asset contains
  mimeType?: string;            // Content type
}

interface ScriptElement extends LagomElementBase {
  elementType: "script";
  name: string;                 // Script display name
  language?: string;            // Language identifier (e.g. "pseudo", "python")
  code: string;                 // Script body
  description?: string;        // What the script does
}

interface StepElement extends LagomElementBase {
  elementType: "step";
  title: string;
  description?: string;
  owner?: string;              // Role or person responsible
  system?: string;             // System of record
  tool?: string;               // Tool identifier (e.g. google_drive.create_folder)
  requiresApproval?: boolean;  // Gate before execution
  inputMap?: Record<string, string>;  // Variable bindings
  requiredEntity?: string;     // Business entity dependency
  expectedDuration?: string;   // Human-readable estimate
  retry?: RetryPolicy;         // Retry configuration
  approval?: ApprovalConfig;   // Approval gate configuration
  onFailure?: "escalate" | "skip" | "abort";
  escalateTo?: string;         // Escalation target on failure
}

interface ConditionElement extends LagomElementBase {
  elementType: "condition";
  expression: string;           // Boolean expression using variables
  thenBranch?: string;          // Element ID to execute if true
  elseBranch?: string;          // Element ID to execute if false
}

interface DecisionElement extends LagomElementBase {
  elementType: "decision";
  title: string;
  rationale?: string;           // Why this decision exists
  options?: string[];           // Available choices
  status?: "pending" | "accepted" | "rejected";
  date?: string;                // ISO 8601 decision date
  owner?: string;               // Decision maker
}

interface EvidenceElement extends LagomElementBase {
  elementType: "evidence";
  sourceType: "document" | "url" | "data" | "observation";
  title?: string;               // Evidence description
  author?: string;              // Who provided this evidence
  confidence?: "low" | "medium" | "high";
  url?: string;                 // Link to source
}

interface FlowElement extends LagomElementBase {
  elementType: "flow";
  title: string;
  parallel?: string[];           // Element IDs to run concurrently
  joinType?: "all" | "any";    // Wait for all or first to complete
}

interface ApprovalGateElement extends LagomElementBase {
  elementType: "approval_gate";
  approver: string;             // Role or person who approves
  appliesTo?: string[];         // Element IDs this gate applies to
  timeout?: string;             // Max wait time (e.g. "48h")
  escalation?: string;          // Who to escalate to on timeout
  onReject?: "abort" | "revise" | "escalate";
}

interface PolicyRuleElement extends LagomElementBase {
  elementType: "policy_rule";
  rule: string;                 // The policy statement
  scope?: string;               // Who or what this applies to
  severity?: "standard" | "critical";
  enforcement?: "manual" | "automated" | "manual-with-automation";
  system?: string;              // Enforcement system
  exceptions?: string[];       // Listed exceptions
}

interface RetryPolicy {
  maxAttempts: number;          // Maximum retry attempts
  firstRetryInterval: string;  // Initial delay (e.g. "5s")
  backoffCoefficient?: number; // Multiplier for each retry
  maxRetryInterval?: string;   // Maximum delay cap
}

interface ApprovalConfig {
  timeout: string;              // Max wait time
  escalateTo?: string;         // Escalation target
  onReject?: "abort" | "revise" | "escalate";
  maxRevisions?: number;       // Max revision cycles
}

interface GovernanceMetadata {
  owner?: string;              // Responsible team or person
  reviewer?: string;           // Designated reviewer
  department?: string;         // Organizational unit
  reviewCadence?: string;      // monthly | quarterly | annually
  lastVerifiedAt?: string;     // ISO 8601 date
  staleAfterDays?: number;     // Days before flagged stale
  confidence?: "low" | "medium" | "high";
  riskLevel?: "low" | "medium" | "high";
  agentReady?: boolean;        // Safe for agent consumption
  externalSharingAllowed?: boolean;
  sourceOfTruth?: boolean;     // Canonical source document
}