lifecycle do
  process_doc "Manages the full lifecycle of vendor invoices from receipt through payment. " \
              "Enforces 3-way match (PO, receipt, invoice) before approval is allowed. " \
              "Requires dual sign-off for invoices above $50,000. " \
              "Integrates with the payment run process — approved invoices queue for the next run."
  # ...
end

lifecycle do
  state :awaiting_approval,
        doc: "Invoice has been submitted and is waiting for an approver to act. " \
             "SLA: 2 business days. Escalation triggers on day 3."

  event :approve do
    doc         "Approver has reviewed and approved the invoice for payment."
    from        :awaiting_approval
    to          :approved
    guards      [:three_way_match_verified?, :within_approval_authority?]
    side_effects [:queue_for_payment, :notify_submitter_of_approval]
  end
end

lifecycle do
  doc :three_way_match_policy,
      "Three-way match requires PO number, goods receipt confirmation, and invoice amount " \
      "to align within 2% tolerance before approval is permitted. This policy was implemented " \
      "in Q2 2025 after an audit found that 12% of invoices were being approved without " \
      "corresponding purchase orders, creating off-PO spend that couldn't be reconciled " \
      "against budget. Exception process: Finance Director can override with written justification."
end

class Nda < ApplicationRecord
  include Fosm::HasLifecycle

  belongs_to :owner,        class_name: "User"
  belongs_to :counterparty, class_name: "User"
  has_one_attached :document

  lifecycle do
    process_doc "Manages the signing lifecycle of Non-Disclosure Agreements between the " \
                "company and external parties (vendors, partners, candidates). " \
                "Enforces signing order flexibility — either party may sign first — " \
                "while ensuring both signatures are captured before execution. " \
                "Integrates with the Contact module: counterparties must be active Contacts " \
                "before an NDA can be sent. Executed NDAs are retained for 7 years per " \
                "legal hold policy."

    states :draft, :sent, :partially_signed, :executed, :expired, :cancelled

    state :draft,
          doc: "NDA has been created but not yet sent. The owner may attach a document, " \
               "edit terms, and designate the counterparty. No signatures collected."

    state :sent,
          doc: "Invitation has been sent to the counterparty. The signing window is open. " \
               "Default expiry: 30 days from send date. Either party may sign first."

    state :partially_signed,
          doc: "One of the two required signatures has been collected. The NDA cannot " \
               "be executed until both the owner and counterparty have signed. " \
               "The system tracks which signature was captured first."

    state :executed,
          doc: "Both parties have signed. The NDA is legally binding. " \
               "Execution date recorded. Document locked — no further changes permitted.",
          terminal: true

    state :expired,
          doc: "The signing window closed without both signatures being captured. " \
               "Distinct from cancellation — expiry is automatic and time-triggered. " \
               "Expired NDAs can be re-sent if the business relationship is still active.",
          terminal: true

    state :cancelled,
          doc: "Explicitly terminated by either party or by an admin. " \
               "Cancellation reason required. Preserved in audit trail indefinitely.",
          terminal: true

    # ─── Events ──────────────────────────────────────────────────────────

    event :send_invitation do
      doc         "Send the NDA to the counterparty. Sets the signing window. " \
                  "Generates a unique signing link valid for expiry_days."
      from        :draft
      to          :sent
      guards      [:document_attached?, :counterparty_is_active_contact?]
      side_effects [:set_expiry_date, :send_invitation_email, :create_audit_entry]
    end

    event :sign_by_owner do
      doc         "Owner's signature captured. Can occur before or after counterparty signs. " \
                  "Records signature timestamp and IP address."
      from        :draft, :sent, :partially_signed
      to          :partially_signed
      guards      [:not_already_signed_by_owner?]
      side_effects [:record_owner_signature]
    end

    event :sign_by_counter do
      doc         "Counterparty signature captured via signing link. " \
                  "Records signature timestamp and IP address."
      from        :sent, :partially_signed
      to          :partially_signed
      guards      [:not_already_signed_by_counter?]
      side_effects [:record_counter_signature]
    end

    event :execute do
      doc         "Both signatures confirmed — mark NDA as legally binding. " \
                  "Execution timestamp recorded. Document hash stored for tamper detection."
      from        :partially_signed
      to          :executed
      guards      [:both_parties_signed?]
      side_effects [:set_execution_date, :lock_document, :notify_both_parties, :create_audit_entry]
    end

    event :expire do
      doc         "Triggered automatically by ExpireNdasJob when current time exceeds expiry_date. " \
                  "Not a human action — do not expose this event in the UI."
      from        :sent, :partially_signed
      to          :expired
      side_effects [:send_expiry_notification]
    end

    event :cancel do
      doc         "Explicitly cancel the NDA. Cancellation reason is stored in the metadata field. " \
                  "Available to the NDA owner and to admins. Not reversible."
      from        :draft, :sent, :partially_signed
      to          :cancelled
      side_effects [:send_cancellation_notification, :create_audit_entry]
    end

    # ─── Guards ──────────────────────────────────────────────────────────

    guard :document_attached? do
      doc "NDA document must be attached before invitation can be sent. " \
          "Accepted formats: PDF only. Maximum size: 10MB."
    end

    guard :counterparty_is_active_contact? do
      doc "Counterparty must exist as an active Contact in the system. " \
          "This ensures the signing invitation reaches a verified email address."
    end

    guard :both_parties_signed? do
      doc "Both owner_signed_at and counter_signed_at must be non-null. " \
          "This is the critical execution guard — partial signatures cannot execute."
    end

    # ─── Side Effects ─────────────────────────────────────────────────────

    side_effect :set_expiry_date do
      doc "Sets expiry_date to (Time.current + expiry_days.days). " \
          "Default expiry_days: 30. Configurable per NDA."
    end

    side_effect :lock_document do
      doc "Sets document_locked: true. Prevents attachment replacement post-execution. " \
          "Also stores document_sha256 hash for tamper detection."
    end

    # ─── Long-form documentation ──────────────────────────────────────────

    doc :signing_order_policy,
        "Either party may sign first. This is intentional — requiring counterparty to sign " \
        "before the owner creates unnecessary back-and-forth. The partially_signed state " \
        "tracks which signature has been collected via owner_signed_at and counter_signed_at. " \
        "The execute event guard (both_parties_signed?) enforces that both are present."

    doc :re_send_policy,
        "Expired NDAs can be re-sent by creating a new NDA record. We do not reuse expired " \
        "NDAs because the expiry creates a clean audit break. The original expired record " \
        "is preserved. A new NDA starts from draft with a fresh signing window."
  end
end

class AddDocumentationToFosmDefinitions < ActiveRecord::Migration[8.0]
  def change
    add_column :fosm_definitions, :process_description, :text
    add_column :fosm_definitions, :documentation,       :jsonb, default: {}
  end
end

module Fosm
  class LifecycleDsl
    # ... existing DSL parser ...

    def process_doc(text)
      @process_description = text
    end

    def doc(name, text)
      (@named_docs ||= {})[name.to_s] = text
    end

    def build_fosm_definition(model_class)
      definition = FosmDefinition.find_or_initialize_by(
        object_type: model_class.name
      )

      definition.assign_attributes(
        states:              @states.map(&:name),
        events:              serialize_events,
        process_description: @process_description,
        documentation:       build_documentation_hash
      )

      definition.save!
      definition
    end

    private

    def build_documentation_hash
      {
        states:       doc_hash_for(@states),
        events:       doc_hash_for(@events),
        guards:       doc_hash_for(collect_guards),
        side_effects: doc_hash_for(collect_side_effects),
        named_docs:   @named_docs || {}
      }
    end

    def doc_hash_for(elements)
      elements.each_with_object({}) do |el, hash|
        hash[el.name.to_s] = el.doc if el.respond_to?(:doc) && el.doc.present?
      end
    end
  end
end

$ rails db:migrate

$ rails fosm:reload_definitions

class Invoice < ApplicationRecord
  include Fosm::HasLifecycle

  belongs_to :vendor
  belongs_to :submitter, class_name: "User"
  belongs_to :approver,  class_name: "User", optional: true
  has_many   :line_items, dependent: :destroy

  lifecycle do
    process_doc "Manages the full lifecycle of vendor invoices from receipt through payment. " \
                "Enforces three-way match (PO, goods receipt, invoice) before approval. " \
                "Dual sign-off required for invoices above $50,000 (configurable via " \
                "InvoicePolicy.high_value_threshold). Approved invoices are queued " \
                "automatically for the next payment run."

    state :draft,
          doc: "Invoice has been entered but not submitted. Editable. " \
               "Not yet validated against PO or goods receipt."

    state :submitted,
          doc: "Invoice submitted for approval. 3-way match validated at submission. " \
               "SLA: 2 business days for first approver action."

    state :awaiting_second_approval,
          doc: "High-value invoice (above threshold) has received first approval " \
               "and is awaiting CFO or delegate sign-off."

    state :approved,
          doc: "All required approvals received. Invoice is queued for the next payment run. " \
               "Vendor will be paid within terms (net-30 default)."

    state :rejected,
          doc: "Approval denied. Rejection reason is required and stored. " \
               "Vendor is notified. Invoice may be resubmitted after correction.",
          terminal: false

    state :paid,
          doc: "Payment processed. Transaction reference stored. " \
               "Closing entry created in GL.",
          terminal: true

    state :voided,
          doc: "Invoice cancelled — not paid, no GL entry. " \
               "Void reason required. Preserves full history.",
          terminal: true

    event :submit do
      doc         "Submit invoice for approval. Triggers 3-way match validation."
      from        :draft, :rejected
      to          :submitted
      guards      [:three_way_match_verified?, :all_line_items_present?]
      side_effects [:notify_approvers, :set_submission_date]
    end

    event :approve do
      doc         "First approver confirms invoice is correct and approved for payment. " \
                  "High-value invoices route to awaiting_second_approval instead of approved."
      from        :submitted
      to          ->(inv) { inv.requires_second_approval? ? :awaiting_second_approval : :approved }
      guards      [:within_approval_authority?]
      side_effects [:record_first_approval, :notify_on_routing]
    end

    event :second_approve do
      doc         "CFO or delegate provides second sign-off on high-value invoice."
      from        :awaiting_second_approval
      to          :approved
      guards      [:is_senior_approver?]
      side_effects [:record_second_approval, :queue_for_payment_run]
    end

    event :reject do
      doc         "Approver rejects invoice. Rejection reason stored in metadata. " \
                  "Vendor notified. Invoice returns to rejected state for correction."
      from        :submitted, :awaiting_second_approval
      to          :rejected
      side_effects [:notify_submitter_of_rejection, :notify_vendor]
    end

    event :mark_paid do
      doc         "Payment run has processed this invoice. Transaction reference stored."
      from        :approved
      to          :paid
      side_effects [:create_gl_closing_entry, :notify_vendor_of_payment]
    end

    event :void do
      doc         "Cancel invoice without payment. Void reason required in metadata."
      from        :draft, :submitted, :awaiting_second_approval, :approved, :rejected
      to          :voided
      side_effects [:reverse_any_gl_entries, :notify_affected_parties]
    end

    guard :three_way_match_verified? do
      doc "PO number must be present and match an approved PO. " \
          "Goods receipt must be confirmed. Invoice amount must be within 2% of PO amount. " \
          "Override available to Finance Director with written justification stored in metadata."
    end

    guard :within_approval_authority? do
      doc "Approver's authority limit must cover the invoice total. " \
          "Authority limits are set on User.invoice_approval_limit. " \
          "Default: $10,000. Configurable per user by HR Admin."
    end

    doc :high_value_policy,
        "Invoices above InvoicePolicy.high_value_threshold (default: $50,000) require " \
        "two approvals: first from any user with invoice approval authority, second from " \
        "a user with the :senior_approver role. The threshold is configurable without code " \
        "changes via the Admin → Invoice Policy settings page."
  end
end

class Admin::Fosm::DocsController < Admin::BaseController
  def index
    @definitions = FosmDefinition.all.order(:object_type)
  end

  def show
    @definition  = FosmDefinition.find_by!(object_type: params[:object_type])
    @doc         = @definition.documentation.with_indifferent_access
    @states      = @definition.states
    @events      = @definition.events
    @diagram_src = generate_mermaid(@definition)
  end

  # GET /admin/fosm/docs.txt
  def export_llms_txt
    @definitions = FosmDefinition.all.order(:object_type)
    render plain: LlmsTxtExporter.export(@definitions),
           content_type: "text/plain"
  end

  private

  def generate_mermaid(definition)
    lines = ["stateDiagram-v2"]
    lines << "    [*] --> #{definition.initial_state}"

    definition.events.each do |event|
      froms = Array(event["from"])
      to    = event["to"]
      next unless to.is_a?(String)

      froms.each do |from|
        lines << "    #{from} --> #{to} : #{event['name']}"
      end
    end

    # Terminal states
    (definition.terminal_states || []).each do |state|
      lines << "    #{state} --> [*]"
    end

    lines.join("\n")
  end
end

class LlmsTxtExporter
  def self.export(definitions)
    new(definitions).export
  end

  def initialize(definitions)
    @definitions = definitions
    @lines       = []
  end

  def export
    write_header
    @definitions.each { |d| write_definition(d) }
    @lines.join("\n")
  end

  private

  def write_header
    @lines << "# FOSM Process Documentation"
    @lines << "# Generated: #{Time.current.iso8601}"
    @lines << "# Source: #{Rails.application.class.module_parent_name}"
    @lines << "#"
    @lines << "# This file describes every state-machine-managed business process."
    @lines << "# It is generated from the model lifecycle definitions and is always current."
    @lines << "# Use this file to give an LLM agent context about business process rules."
    @lines << ""
    @lines << "---"
    @lines << ""
  end

  def write_definition(defn)
    doc = defn.documentation.with_indifferent_access

    @lines << "## #{defn.object_type}"
    @lines << ""

    if defn.process_description.present?
      @lines << defn.process_description
      @lines << ""
    end

    write_states(defn, doc)
    write_events(defn, doc)
    write_guards(doc)
    write_side_effects(doc)
    write_named_docs(doc)
    write_mermaid_diagram(defn)

    @lines << "---"
    @lines << ""
  end

  def write_states(defn, doc)
    return if defn.states.empty?

    @lines << "### States"
    @lines << ""
    defn.states.each do |state|
      terminal = defn.terminal_states&.include?(state) ? " [terminal]" : ""
      @lines << "**#{state}**#{terminal}"
      state_doc = doc.dig(:states, state)
      @lines << (state_doc || "(not documented)")
      @lines << ""
    end
  end

  def write_events(defn, doc)
    return if defn.events.empty?

    @lines << "### Events"
    @lines << ""
    defn.events.each do |event|
      froms = Array(event["from"]).join(", ")
      to    = event["to"]
      @lines << "**#{event['name']}** (#{froms} → #{to})"
      event_doc = doc.dig(:events, event["name"])
      @lines << (event_doc || "(not documented)")

      guards = Array(event["guards"])
      if guards.any?
        @lines << "Guards: #{guards.join(', ')}"
      end

      side_effects = Array(event["side_effects"])
      if side_effects.any?
        @lines << "Side effects: #{side_effects.join(', ')}"
      end
      @lines << ""
    end
  end

  def write_guards(doc)
    guards = doc[:guards] || {}
    return if guards.empty?

    @lines << "### Guard Conditions"
    @lines << ""
    guards.each do |guard, text|
      @lines << "**#{guard}**"
      @lines << text
      @lines << ""
    end
  end

  def write_side_effects(doc)
    effects = doc[:side_effects] || {}
    return if effects.empty?

    @lines << "### Side Effects"
    @lines << ""
    effects.each do |effect, text|
      @lines << "**#{effect}**"
      @lines << text
      @lines << ""
    end
  end

  def write_named_docs(doc)
    named = doc[:named_docs] || {}
    return if named.empty?

    @lines << "### Policy Notes"
    @lines << ""
    named.each do |name, text|
      @lines << "**#{name.to_s.humanize}**"
      @lines << text
      @lines << ""
    end
  end

  def write_mermaid_diagram(defn)
    @lines << "### State Diagram"
    @lines << ""
    @lines << "```mermaid"
    @lines << "stateDiagram-v2"
    @lines << "    [*] --> #{defn.initial_state}"

    defn.events.each do |event|
      froms = Array(event["from"])
      to    = event["to"]
      next unless to.is_a?(String)

      froms.each { |from| @lines << "    #{from} --> #{to} : #{event['name']}" }
    end

    (defn.terminal_states || []).each do |state|
      @lines << "    #{state} --> [*]"
    end

    @lines << "```"
    @lines << ""
  end
end

$ curl https://yourapp.com/admin/fosm/docs.txt > llms.txt

$ rails fosm:export_llms_txt > llms.txt

namespace :fosm do
  desc "Export all process documentation as llms.txt"
  task export_llms_txt: :environment do
    definitions = FosmDefinition.all.order(:object_type)
    output_path = Rails.root.join("public", "llms.txt")

    File.write(output_path, LlmsTxtExporter.export(definitions))
    puts "Exported #{definitions.count} process definitions to #{output_path}"
  end

  desc "Reload all FOSM lifecycle definitions from model files"
  task reload_definitions: :environment do
    count = 0
    Dir[Rails.root.join("app/models/**/*.rb")].each do |file|
      model_name = File.basename(file, ".rb").camelize
      begin
        klass = model_name.constantize
        if klass.respond_to?(:fosm_lifecycle)
          klass.fosm_lifecycle.sync_to_database!
          count += 1
          puts "  ✓ #{model_name}"
        end
      rescue NameError, LoadError
        # Not a FOSM model
      end
    end
    puts "Reloaded #{count} FOSM definitions"
  end
end

namespace :admin do
  namespace :fosm do
    resources :docs, param: :object_type, only: [:index, :show] do
      collection do
        get :export_llms_txt, path: "docs.txt"
      end
    end
  end
end

module Fosm
  module DocsHelper
    def documented_count(definition, section)
      doc = definition.documentation.with_indifferent_access
      items = doc[section] || {}
      items.count { |_, text| text.present? }
    end

    def documentation_coverage(definition)
      total   = definition.states.count + definition.events.count
      return 0 if total.zero?

      doc     = definition.documentation.with_indifferent_access
      documented = documented_count(definition, :states) +
                   documented_count(definition, :events)

      (documented.to_f / total * 100).round
    end

    def coverage_badge_class(pct)
      case pct
      when 80..100 then "badge-success"
      when 50..79  then "badge-warning"
      else              "badge-danger"
      end
    end
  end
end

require "rails_helper"

RSpec.describe "FOSM documentation coverage" do
  MINIMUM_COVERAGE_PERCENT = 80

  FosmDefinition.all.each do |definition|
    describe "#{definition.object_type} lifecycle" do
      it "has a process_doc description" do
        expect(definition.process_description).to be_present,
          "#{definition.object_type} is missing a process_doc in its lifecycle block"
      end

      it "has states documented above #{MINIMUM_COVERAGE_PERCENT}%" do
        doc        = definition.documentation.with_indifferent_access
        total      = definition.states.count
        documented = (doc[:states] || {}).count { |_, t| t.present? }
        coverage   = total.zero? ? 100 : (documented.to_f / total * 100).round

        expect(coverage).to be >= MINIMUM_COVERAGE_PERCENT,
          "#{definition.object_type} has #{coverage}% state documentation " \
          "(#{documented}/#{total}). Add doc: to undocumented states."
      end

      it "has events documented above #{MINIMUM_COVERAGE_PERCENT}%" do
        doc        = definition.documentation.with_indifferent_access
        total      = definition.events.count
        documented = (doc[:events] || {}).count { |_, t| t.present? }
        coverage   = total.zero? ? 100 : (documented.to_f / total * 100).round

        expect(coverage).to be >= MINIMUM_COVERAGE_PERCENT,
          "#{definition.object_type} has #{coverage}% event documentation " \
          "(#{documented}/#{total}). Add doc: to undocumented events."
      end
    end
  end
end

$ bundle exec rspec spec/fosm/documentation_coverage_spec.rb

lifecycle do
  process_doc "Manages the full lifecycle of external contacts: candidates, vendors, " \
              "partners, and customers. Contacts are the external party in NDA, hiring, " \
              "and vendor management workflows. The vetting process ensures due diligence " \
              "before a contact can be used in a business-critical context."

  state :prospect,
        doc: "Contact has been added to the system but not yet vetted. " \
             "Cannot be named as NDA counterparty or invoice vendor until approved. " \
             "Source tracked: referral, inbound, import, manual."

  state :active,
        doc: "Contact is fully vetted and usable across all modules. " \
             "Can be designated as NDA counterparty, invoice vendor, hire candidate."

  state :inactive,
        doc: "Contact has been deactivated — typically a departed employee, " \
             "terminated vendor relationship, or candidate no longer in pipeline. " \
             "Historical records preserved. Cannot be used in new workflows."

  event :vet do
    doc     "Transition from prospect to active after due diligence. " \
            "Records who vetted and when. Required for regulated vendor onboarding."
    from    :prospect
    to      :active
    guards  [:identity_verified?, :no_sanctions_match?]
  end

  guard :no_sanctions_match? do
    doc "Checks contact name and entity against OFAC/SDN list via SanctionsChecker service. " \
        "Required for vendor and partner contacts. Skipped for internal candidates " \
        "unless international flag is set."
  end
end

$ git log --follow -p app/models/invoice.rb | grep -A5 "process_doc\|doc:"