-- File: models/<your-model>/types/<category>/<type-name>.lua
-- The module returns one descriptor table.
return {
    -- kind: object | float | view | relation | specification | analyze.
    -- It must match the category directory the file lives in.
    kind = "object",

    -- schema contains data. schema.id is authoritative.
    -- These fields become columns in the SpecIR database.
    schema = {
        id = "...",            -- required, uppercase convention, globally unique
        -- extends = "...",    -- inherit attributes + hooks from a base type
        -- attributes = { ... },
    },

    -- hooks contains optional custom behavior.
    -- The host classifies each hook by NAME, infers the role from the hooks
    -- present, and rejects a function placed on any other top-level key. A
    -- pure-data type (most objects/floats) omits this key entirely and
    -- inherits the host default.
    -- hooks = {
    --     render = function(ctx) ... end,   -- one hook whose name fits the intent
    -- },
}

return {
    kind = "object",
    schema = {
        id = "DECISION",
        long_name = "Architecture Decision",
        extends = "SECTION",
        pid_prefix = "ADR",
        pid_format = "%s-%03d",
        attributes = {
            { name = "status", type = "ENUM",
              values = { "Proposed", "Accepted", "Superseded" } },
            { name = "consequences", type = "XHTML" },
        },
    },
}

# Architecture Decisions @SPEC-ADR-001

## DECISION: Use SQLite for the IR @ADR-001

> status: Accepted

> consequences: The build produces one file. SQL queries provide traceability data.

We store the intermediate representation in a SQLite database rather than
in-memory tables, so analyze queries can use SQL.

## DECISION: Run on stock pandoc

> status: Proposed

Use the system Pandoc with Lua and C extensions.

name: mymodel
description: My domain model
requires: [base_model]   # Load this model first.

local render_utils = require("pipeline.shared.render_utils")

return {
    kind = "object",
    schema = {
        id = "HLR",
        long_name = "High-Level Requirement",
        description = "A top-level system requirement",
        extends = "TRACEABLE",       -- inherit the standard traceable card
        pid_prefix = "HLR",
        pid_format = "%s-%03d",
        attributes = {
            { name = "priority", type = "ENUM",
              values = { "High", "Medium", "Low" },
              min_occurs = 1, max_occurs = 1 },
            { name = "rationale", type = "XHTML" },
        },
    },
    hooks = {
        -- EMIT: ctx.subject carries { object, attributes, element, ... } already
        -- resolved by the pipeline, so no DB query is needed for our own item.
        render = function(ctx)
            local obj   = ctx.subject.object
            local attrs = ctx.subject.attributes or {}
            local priority = (attrs.priority or {}).value or "?"

            local blocks = {}
            local level = math.max((ctx.subject.header_level or 2) - 1, 1)
            local hdr = ctx.pandoc.Header(level,
                { ctx.pandoc.Str(obj.pid .. ": " .. (obj.title_text or "")) })
            render_utils.add_header_blocks(blocks, hdr)
            table.insert(blocks, ctx.pandoc.Para({
                ctx.pandoc.Strong({ ctx.pandoc.Str("Priority: ") }),
                ctx.pandoc.Str(priority),
            }))
            return blocks
        end,
    },
}

## HLR: User Authentication @HLR-001

> priority: High
> rationale: Required by security policy section 4.2

The system shall authenticate users via username and password.

return {
    kind = "relation",
    schema = {
        id = "TRACES_TO",
        extends = "PID_REF",
        long_name = "Traces To",
        description = "Traceability link from one object to another",
        source_type_ref = "LLR",
        target_type_ref = "HLR",
    },
}

hooks = {
    -- Render section refs as "<hierarchical-number> <title>", e.g. "3.4 Introduction".
    render_link = function(ctx)
        local target = ctx.subject.target
        local title  = target.title or ""
        local number = target.pid and target.pid:match("sec([%d%.]+)$")
        if number and title ~= "" then return number .. " " .. title end
        if title ~= "" then return title end
        return target.pid
    end,
}

return {
    kind = "view",
    schema = {
        id = "SYMBOL",
        long_name = "Symbol",
        description = "Engineering symbol with inline formatting",
        aliases = { "sym" },
        inline_prefix = "symbol",
    },
    hooks = {
        -- EMIT: ctx.subject.element is the Pandoc Code element.
        render = function(ctx)
            local text = ctx.subject.element.text or ""
            local content = text:match("^symbol:%s*(.+)$") or text:match("^sym:%s*(.+)$")
            if not content then return nil end
            return { ctx.pandoc.Emph({ ctx.pandoc.Str(content) }) }
        end,
    },
}

return {
    kind = "view",
    schema = {
        id = "TRACEABILITY_MATRIX",
        extends = "TABLE_VIEW",          -- inherits the shared render_block
        long_name = "Traceability Matrix",
        description = "HLR to VC traceability with test results",
        inline_prefix = "traceability_matrix",
    },
    hooks = {
        -- DATA: build the generated table. dctx.data is the SpecIR database.
        -- dctx.subject.params holds any view parameters.
        build_block = function(dctx)
            local rows = dctx.data:query_all([[
                SELECT hlr.pid AS hlr_pid, vc.pid AS vc_pid
                FROM spec_relations r
                JOIN spec_objects vc  ON r.source_object_id = vc.id
                JOIN spec_objects hlr ON r.target_object_id = hlr.id
                WHERE vc.type_ref = 'VC' AND hlr.type_ref = 'HLR'
                  AND vc.specification_ref = :spec_id
                ORDER BY hlr.pid, vc.pid
            ]], { spec_id = dctx.spec_id })
            if not rows or #rows == 0 then
                return pandoc.Para({ pandoc.Str("No HLR-VC traceability found.") })
            end
            local header = {
                { pandoc.Plain({ pandoc.Strong({ pandoc.Str("HLR") }) }) },
                { pandoc.Plain({ pandoc.Strong({ pandoc.Str("VC")  }) }) },
            }
            local body = {}
            for _, row in ipairs(rows) do
                table.insert(body, {
                    { pandoc.Plain({ pandoc.Str(row.hlr_pid or "") }) },
                    { pandoc.Plain({ pandoc.Str(row.vc_pid  or "") }) },
                })
            end
            local tbl = pandoc.SimpleTable({}, { pandoc.AlignLeft, pandoc.AlignLeft },
                { 0, 0 }, header, body)
            return pandoc.utils.from_simple_table(tbl)
        end,
    },
}

return {
    kind = "float",
    schema = {
        id = "SEQUENCE",
        long_name = "Sequence Diagram",
        caption_format = "Figure",
        counter_group = "FIGURE",      -- shares numbering with FIGURE, PLANTUML, CHART
        aliases = { "seq", "sequence" },
    },
}

```seq:auth-flow{caption="User authentication flow"}
sequence diagram content here
```

return {
    kind = "specification",
    schema = {
        id = "SRS",
        long_name = "Software Requirements Specification",
        description = "MIL-STD-498 SRS document",
        is_default = false,
        implicit_aliases = { "Software Requirements Specification", "SRS" },
        attributes = {
            { name = "version", type = "STRING" },
            { name = "date",    type = "STRING" },
        },
    },
}

return {
    kind = "analyze",
    schema = {
        id = "vc_missing_hlr",
        view = "view_traceability_vc_missing_hlr",
        policy_key = "traceability_vc_to_hlr",
        sql = [[
CREATE VIEW IF NOT EXISTS view_traceability_vc_missing_hlr AS
SELECT vc.identifier AS object_id, vc.pid AS object_pid,
       vc.title_text AS object_title, vc.from_file, vc.start_line
FROM spec_objects vc
WHERE vc.type_ref = 'VC'
  AND NOT EXISTS (
      SELECT 1 FROM spec_relations r
      JOIN spec_objects target ON target.identifier = r.target_ref
      WHERE r.source_ref = vc.identifier AND target.type_ref = 'HLR'
  );
]],
    },
    hooks = {
        -- ANALYZE: one call per row. ctx.subject.row contains the query result.
        message = function(ctx)
            local row = ctx.subject.row
            local label = row.object_pid or row.object_title or row.object_id
            return string.format(
                "Verification case '%s' has no traceability link to an HLR", label)
        end,
    },
}

validation:
  traceability_vc_to_hlr: ignore

local float_base  = require("pipeline.shared.float_base")
local task_runner = require("infra.process.task_runner")

return {
    kind = "float",
    schema = {
        id = "PLANTUML",
        long_name = "PlantUML Diagram",
        caption_format = "Figure",
        counter_group = "FIGURE",
        aliases = { "puml", "plantuml" },
        needs_external_render = true,
    },
    hooks = {
        -- DATA: build the spawn task. dctx.subject contains { float, build_dir }.
        -- dctx.log is the logger. Return the task descriptor, or nil to skip.
        prepare_task = function(dctx)
            local float     = dctx.subject.float
            local build_dir = dctx.subject.build_dir
            local content   = float.raw_content or ""
            local hash      = pandoc.sha1(content)
            local diagrams  = build_dir .. "/diagrams"
            local puml_file = diagrams .. "/" .. hash .. ".puml"
            local png_file  = diagrams .. "/" .. hash .. ".png"

            task_runner.ensure_dir(diagrams)
            task_runner.write_file(puml_file, content)

            return {
                cmd = "plantuml",
                args = { "-tpng", puml_file },
                opts = { timeout = 30000 },
                output_path = png_file,   -- cache key: skipped when the file exists
                context = { float = float, relative_path = "diagrams/" .. hash .. ".png" },
            }
        end,

        -- DATA: write the resolved AST. dctx.subject carries
        -- { task, success, stdout, stderr }. dctx.data is the SpecIR database.
        handle_result = function(dctx)
            local task = dctx.subject.task
            local ctx  = task.context
            if not dctx.subject.success then
                dctx.log.warn("PlantUML failed: %s", dctx.subject.stderr)
                return
            end
            local json = string.format('{"png_paths":["%s"]}', ctx.relative_path)
            float_base.update_resolved_ast(dctx.data, ctx.float.id, json)
        end,
    },
}

project:
  code: MYPROJ
  name: My Project

template: mymodel   # Loads models/default/ then models/mymodel/

doc_files:
  - srs.md