Formal definition: $S = \left( \tau,n,\text{pid},\mathcal{A},\mathcal{O} \right)$ — a tuple of type, title, project identifier, attributes, and child objects.

Syntax: # [TypeRef:] Text [@PID]

Full specification: See the CommonSpec Language Specification for the complete grammar, type inference rules, and examples.

Formal definition: $O = \left( \tau,\text{title},\text{pid},\beta,\mathcal{A},\mathcal{F},\mathcal{R},\mathcal{V},\mathcal{O} \right)$ — a tuple of type, title, project identifier, body content, attributes, floats, relations, views, and child objects.

Syntax: ##...###### [TypeRef:] Title [@PID]

Full specification: See the CommonSpec Language Specification for the complete grammar, type inference, PID auto-generation, and examples.

Formal definition: $F = \left( \tau,\text{label},\mathcal{\text{kv}},\text{content} \right)$ — a tuple of type, label, key-value metadata, and raw content.

Syntax: ```TypeRef:Label[{Key=Value, ...}] Content ```

Full specification: See the CommonSpec Language Specification for float types, aliases, counter groups, and examples.

Formal definition: $A = \left( \tau,\beta,\mathcal{R} \right)$ — a triple of attribute type, blockquote content, and child relations.

Syntax: > TypeRef: value

Datatypes: STRING, INTEGER, REAL, BOOLEAN, DATE, ENUM, XHTML.

Full specification: See the CommonSpec Language Specification for the complete datatype semantics, attribute constraints, and examples.

Formal definition: $R = (s,t,\sigma,\alpha)$ — a 4-tuple of source object, target element, link selector, and source attribute.

Type inference: $\rho = \text{infer}\left( \sigma,\alpha,\tau_{s},\tau_{t} \right)$ — the relation type is inferred by constraint matching with most-specific-wins across selector, attribute, source type, and target type.

Syntax: [Target](selector) where the URL starts with @ or #. Selectors are not hardcoded — they are defined by relation types in the model (e.g., PID_REF defines @, LABEL_REF defines #, XREF_CITATION defines @cite,@citep). Models can register any @... or #... selector.

Full specification: See the CommonSpec Language Specification for the complete inference algorithm and examples.

Formal definition: $V = (\tau,\omega)$ — a pair of view type and parameter string.

Syntax: `TypeRef:[ViewParam]`

Full specification: See the CommonSpec Language Specification for view types, rendering, and examples.

Each phase serves a distinct purpose in document processing:

1. INITIALIZE: Parse document AST and populate database with specifications, spec_objects, floats, relations, views, and attributes
2. RESOLVE: Resolve relations between objects (link target resolution, type inference)
3. TRANSFORM: Pre-compute views, render external content (PlantUML, charts), prepare for output
4. ANALYZE: Run analyze queries to validate data integrity, type constraints, cardinality rules
5. EMIT: Assemble final documents and write to output formats (docx, html5, markdown, json)

Handlers register via register_handler(handler) with required fields:

• name: Unique string identifier for the handler
• prerequisites: Array of handler names that must execute before this handler

Handlers declare participation in phases via hook methods (on_initialize, on_analyze, on_verify, on_transform, on_emit). Duplicate handler names cause registration error.

For each phase, the pipeline:

1. Identifies handlers participating in the phase (those with on_{phase} hooks)
2. Builds dependency graph from prerequisites (only for participating handlers)
3. Executes Kahn’s algorithm to produce execution order
4. Sorts alphabetically at each level for deterministic output
5. Detects and reports circular dependencies with error listing remaining nodes

All handlers implement on_{phase}(data, contexts, diagnostics) hooks that receive the full contexts array. The pipeline orchestrator calls each handler’s hook once per phase via run_phase(), passing all document contexts. Handlers are responsible for iterating over contexts internally.

This enables cross-document optimizations, transaction batching, and parallel processing within any phase.

The execute(docs) method creates context objects for each input document with:

• doc: Pandoc document AST (via DocumentWalker)
• spec_id: Specification identifier derived from filename
• config: Preset configuration (styles, captions, validation)
• build_dir: Output directory path
• output_format: Target format (docx, html5, etc.)
• template: Template name for model loading
• reference_doc: Path to reference.docx for styling
• docx, html5: Format-specific configuration
• outputs: Array of {format, path} for multi-format output
• bibliography, csl: Citation configuration
• project_root: Root directory for resolving relative paths

Context flows through all phases, enriched by handlers (e.g., verification results in ANALYZE phase).

The INITIALIZE phase <Handler>s parse the Pandoc <Abstract Syntax Tree> and populate the six IR content tables according to these rules:

1. H1 headers register as <Specification> records with optional TYPE: prefix and @PID suffix
2. H2-H6 headers register as <Spec Object> records with type inference (explicit TYPE: prefix, implicit alias lookup, or default type fallback)
3. Blockquote lines (> key: value) register as <Attribute> records attached to the enclosing spec object
4. Fenced code blocks with TypeRef:Label class register as <Spec Float> records
5. Markdown links with (@) or (#) targets register as <Spec Relation> records
6. Inline code with TypeRef: content syntax registers as <Spec View> records

Each handler populates its content table with content-addressable identifiers (SHA1) and preserves document ordering via file_seq.

Include expansion runs before the five-phase pipeline on each source document:

1. Fenced code blocks with class .include are identified
2. Each line in the block is treated as a relative file path
3. Paths are resolved relative to the including file’s directory
4. Referenced files are read, parsed, and recursively expanded
5. The include block is replaced with the parsed content blocks

Cycle detection prevents infinite recursion. Maximum include depth is bounded. Source position tracking attributes are injected for diagnostic reporting.

The PID generator runs in the RESOLVE phase before relation resolution:

1. Non-<Composite Object Type> objects: PIDs are generated using the type’s pid_prefix and pid_format (e.g., HLR-%03d produces “HLR-001”), starting from the next available sequence number
2. <Composite Object Type> objects: Hierarchical PIDs are qualified by the specification PID (e.g., “SRS-sec1.2.3”)

Auto-generated PIDs never overwrite explicit @PID annotations. Collision detection ensures global uniqueness across all specifications.

For each unresolved relation, the relation analyzer:

1. Filter: Identifies candidate relation types whose constraints are compatible with the relation’s <Relation Selector>, source attribute, source type, and target type
2. Resolve: Calls the resolver (determined by the type’s extends chain root) to find the target object
3. Score: Counts matching non-NULL constraints across all four dimensions; NULL constraints act as wildcards (match anything but do not increase specificity)
4. Pick: The highest specificity match wins; ties mark the relation as ambiguous

Same-specification targets are preferred over cross-specification targets. The relation’s target_ref and type_ref are updated in the database.

During INITIALIZE, the first ---- thematic break ends the active section scope. The marker does not appear in rendered output. Later content keeps its document position and belongs to the parent section.

An empty heading (a header whose title is blank) is rejected: it would otherwise render as an empty numbered heading and corrupt downstream numbering. The object_broken_hierarchy analyze query reports it as an error and directs the author to use ---- instead.

The specifications table stores metadata for each specification document parsed during <INITIALIZE Phase> phase:

• identifier: Unique specification ID derived from filename (e.g., “srs-main”)
• root_path: Source file path for the specification
• long_name: Human-readable title extracted from L1 header
• type_ref: Specification type (validated against spec_specification_types)
• pid: Optional PID from @PID syntax in L1 header

L1 headers register as specifications. Type validation checks spec_specification_types table. Invalid types fall back to default or emit warning.

The spec_objects table stores structured specification items extracted from L2+ headers:

• identifier: SHA1 hash of source path + line + title (content-addressable)
• specification_ref: Foreign key to parent specification
• type_ref: Object type (validated against spec_object_types)
• from_file: Source file path
• file_seq: Document order sequence number
• pid: Project ID from @PID syntax (e.g., “REQ-001”)
• title_text: Header text without type prefix or PID
• label: Unified label for cross-referencing (format: {type_lower}:{title_slug})
• level: Header level (2-6)
• start_line, end_line: Source line range
• ast: Serialized Pandoc AST (JSON) for section content

Type resolution order: explicit TYPE: prefix, implicit alias lookup, default type fallback.

The spec_floats table stores content blocks that receive sequential numbering:

• identifier: Short format “float-{8-char-sha1}” for DOCX compatibility
• specification_ref: Foreign key to parent specification
• type_ref: Float type resolved from aliases (e.g., “csv” -> “TABLE”, “puml” -> “FIGURE”)
• from_file: Source file path
• file_seq: Document order for numbering
• label: User-provided label for cross-referencing
• number: Sequential number within counter_group (assigned in <TRANSFORM Phase>)
• caption: Caption text from attributes
• raw_content: Original code block text
• raw_ast: Serialized Pandoc CodeBlock (JSON)
• parent_object_ref: Foreign key to containing spec_object
• attributes: JSON-serialized attributes (caption, source, language)
• syntax_key: Original class syntax for backend matching

<Counter Group> share numbering (e.g., FIGURE, CHART, PLANTUML all increment “FIGURE” counter).

The spec_views table stores view definitions from inline view syntax (views are inline-only; a view alone in its own paragraph is transparently promoted to block output at EMIT):

• identifier: SHA1 hash of specification + sequence + content
• specification_ref: Foreign key to parent specification
• view_type_ref: Uppercase view type (e.g., “TOC”, “SYMBOL”, “MATH”, “ABBREV”)
• from_file: Source file path
• file_seq: Document order sequence number
• raw_ast: View definition content (symbol path, expression, parameters)

View types with needs_external_render = 1 in spec_view_types are delegated to specialized renderers. Inline views use prefix: content syntax (e.g., symbol: Class.method). The content may carry key=value parameters (e.g., [TOC], allocation_matrix: status=complete); the EMIT dispatcher parses the prefix, content, and parameters once and passes them to the view’s render hooks (ctx.subject.prefix/content/params).

The spec_relations table stores inter-element references:

• identifier: SHA1 hash of specification + target + type + parent
• specification_ref: Foreign key to parent specification
• source_ref: Foreign key to source spec_object
• target_text: Raw link target from syntax (e.g., “REQ-001”, “fig:diagram”)
• target_ref: Resolved target identifier (populated in <RESOLVE Phase> phase)
• type_ref: Relation type from spec_relation_types (e.g., “TRACES”, “XREF_FIGURE”)
• from_file: Source file path

Link syntax: [PID](@) for PID references, [type:label](#) for float references, [@citation] for bibliographic citations. Default relation types are determined by is_default and link_selector columns in spec_relation_types.

The spec_attributes table stores typed attribute values extracted from blockquote syntax:

• identifier: SHA1 hash of specification + owner + name + value
• specification_ref: Foreign key to parent specification
• owner_ref: Foreign key to owning spec_object
• name: Attribute name (field name without colon)
• raw_value: Original string value
• string_value, int_value, real_value, bool_value, date_value: Type-specific columns
• enum_ref: Foreign key to enum_values for ENUM types
• ast: JSON-serialized Pandoc AST for rich content (XHTML type)
• datatype: Resolved datatype from spec_attribute_types

Attribute syntax: > name: value in blockquotes following headers. Datatypes include STRING, INTEGER, REAL, BOOLEAN, DATE, ENUM, XHTML. Multi-line attributes use continuation blocks.

Verification views are SQL queries registered in the <ANALYZE Phase> phase that check for constraint violations:

• Specification-level (missing required attributes, invalid types)
• Object-level (missing required, cardinality, cast failures, invalid enum/date, bounds)
• Float-level (orphans, duplicate labels, render failures, invalid types)
• Relation-level (unresolved, dangling, ambiguous)

The validation policy (configurable in project.yaml) determines severity: error, warn, or ignore.

The host scans these directories under models/{model}/types/:

• objects/ for kind = "object"
• specifications/ for kind = "specification"
• floats/ for kind = "float"
• views/ for kind = "view"
• relations/ for kind = "relation"

Each Lua module returns one descriptor table. The host uses schema.id as the type identifier. The file name does not define the identifier.

A model can contain the following paths:

models/{model}/
  model.yaml
  types/
    objects/
    specifications/
    floats/
    views/
    relations/
  analyze_queries/
  filters/
  postprocessors/
  styles/
  tools/

Only the directories required by the model must exist. A type directory can contain a Lua file or a subdirectory with init.lua.

During the <EMIT Phase> phase, the assembler queries spec_objects ordered by file_seq, decodes stored JSON <Abstract Syntax Tree> fragments back to Pandoc blocks, adjusts header levels for cross-file includes, and embeds:

1. Specification title: From specifications.header_ast, wrapped in a title Div
2. Spec objects: All objects belonging to the specification, in file_seq order, with their rendered body AST
3. Spec floats: Placeholder CodeBlocks for floats at their document positions (resolved later by the float emitter)
4. Spec views: Placeholder CodeBlocks for views at their document positions (expanded later by the view emitter)

The assembled document includes Pandoc metadata built from specification attributes (title, author, date). The result is a valid pandoc.Pandoc document suitable for format-specific output.

Header-level adjustment rescales the shallowest header level to the top output level uniformly; it therefore assumes the source header levels form a well-formed tree (contiguous nesting, a single root depth). That precondition is enforced declaratively by the object_broken_hierarchy analyze query, which rejects skipped levels and orphaned roots before emission rather than letting a malformed hierarchy mis-render silently.

After document assembly, the float emitter walks all blocks and replaces CodeBlock placeholders (identified by float labels) with rendered Div elements containing:

1. Rendered content: The resolved_ast from spec_floats (SVG images for PlantUML, parsed tables for CSV, chart images for ECharts)
2. Caption: A formatted caption with type prefix and sequential number (e.g., “Figure 1 – Diagram Title”)
3. Semantic classes: CSS classes (speccompiler-float, speccompiler-caption, type-specific class) for format-specific styling
4. Bookmark anchor: An identifier anchor for cross-reference navigation

Floats whose resolved_ast is NULL (failed external renders) are preserved as error placeholders.

During the <TRANSFORM Phase> phase, the float numberer:

1. Queries all floats across all specifications, ordered by file_seq
2. Groups floats by their counter_group (e.g., FIGURE, TABLE, LISTING, EQUATION)
3. Assigns monotonically increasing numbers within each group (starting at 1)
4. Float types sharing a counter_group share the same sequence (e.g., FIGURE, CHART, and PLANTUML all increment the “FIGURE” counter)

The assigned numbers are stored in spec_floats.number and used for caption formatting and cross-reference display text.

The emitter orchestrator iterates over config.outputs (an array of {format, path} pairs) and for each specification:

1. Serializes the assembled Pandoc document to an intermediate JSON file
2. Checks the output cache (is_output_current()) and skips generation when the P-IR hash matches
3. Applies format-specific Pandoc Lua filters (e.g., docx.lua, html.lua from the model’s filters/ directory)
4. Invokes Pandoc for format conversion
5. Runs format-specific postprocessors after Pandoc generation completes
6. Cleans up intermediate JSON files

Supported output formats: DOCX, HTML5, Markdown, JSON. Multiple formats can be generated from a single pipeline execution.

DOCX output generation follows this sequence:

1. Preset loading: Loads style preset definitions from models/{model}/styles/presets/ with extends-chain merging and circular dependency detection
2. Reference document generation: Generates a reference.docx from the resolved preset containing custom Word styles (headings, captions, code blocks, table styles)
3. Pandoc conversion: Invokes Pandoc with --reference-doc pointing to the generated reference and format-specific Lua filters
4. OOXML post-processing: Modifies the DOCX archive to apply style fixups, numbering definitions, and structural corrections that Pandoc cannot produce natively

The reference document is cached and regenerated only when the preset hash changes.

HTML5 output generation follows this sequence:

1. Pandoc conversion: Invokes Pandoc with HTML5-specific options from project configuration (number_sections, table_of_contents, toc_depth, standalone, embed_resources)
2. Resource embedding: When embed_resources is enabled, all CSS, JavaScript, and image assets are embedded inline for single-file distribution
3. Search index: When <Full-Text Search> tables are populated, the HTML5 postprocessor bundles the search index for client-side full-text search
4. Internal links: Cross-reference (@) links resolve to #anchor URLs for in-page navigation

Configuration is specified in the html5: section of project.yaml.

The FTS indexer creates and populates three FTS5 virtual tables with Porter stemming:

1. fts_objects: Indexes spec object titles and body text, keyed by identifier and spec_id
2. fts_attributes: Indexes attribute names and string values, keyed by owner_ref and spec_id
3. fts_floats: Indexes float captions and raw source content, keyed by identifier and spec_id

<Abstract Syntax Tree> content is converted to plain text before indexing.

The build engine computes SHA1 hashes for each document. Hashes are compared against the cached values recorded as build_graph nodes (the root document is its own node, alongside its includes):

1. Every node of the document’s build graph is compared against its current file hash
2. If all hashes match, the document is skipped (cached <Intermediate Representation> state is reused)
3. If any hash differs, a node file is missing, or no root node is recorded, the document is rebuilt from source
4. After successful rebuild (no <ANALYZE Phase> errors), the build_graph nodes are rewritten with current hashes

This provides O(1) change detection without parsing unchanged documents.

Before <Pipeline> execution, the include handler expands .include code blocks by:

1. Resolving include paths relative to the source file directory
2. Detecting circular includes via a processed-file set (raises error on cycle)
3. Recursively expanding nested includes up to a bounded maximum depth
4. Recording all include paths and their SHA1 hashes in the build_graph table (root_path, node_path, node_sha1)

Subsequent builds use this graph to check if any included file has changed, triggering a rebuild of the root document when needed.

The diagnostics collector provides structured error/warning reporting:

1. Collection: <Handler>s report issues via diagnostics:error(file, line, code, msg) and diagnostics:warn(file, line, code, msg)
2. Structured data: Each diagnostic record contains file path, line number, diagnostic key, and human-readable message
3. Severity control: The has_errors() method enables the <Pipeline> to determine abort conditions after the <ANALYZE Phase> phase
4. Output integration: Diagnostics are emitted through the structured logger with file and line context

Diagnostic keys are stable identifiers (e.g., invalid_enum, missing_required, dangling_relation) suitable for filtering and CI policy.

The logging subsystem supports two output modes selected automatically or via configuration:

1. NDJSON mode (non-TTY): Outputs one JSON object per line with fields: level, message, timestamp, and optional context. Suitable for CI/CD log aggregation and jq filtering
2. Console mode (TTY): Outputs human-readable formatted messages with ANSI color coding (respects NO_COLOR environment variable). Includes timestamp and level indicator

Log levels: DEBUG, INFO, WARN, ERROR. Configured via config.logging.level with environment override SPECCOMPILER_LOG_LEVEL.

Build reproducibility is ensured through:

1. Deterministic parsing: Content-addressable SHA1 identifiers ensure consistent object identity
2. Deterministic ordering: <Topological Sort> with alphabetic tie-breaking produces the same <Handler> execution order
3. Deterministic numbering: Float numbers assigned by file_seq ordering, which is stable across builds
4. Deterministic output: Pandoc invoked with the same arguments and reference documents produces identical output

Cache invalidation is based solely on content hashes, not filesystem timestamps or system state.

Purpose: Defines the input language for SpecCompiler. Extends standard Markdown (CommonMark) with six constructs: specifications, spec objects, spec floats, attributes, spec relations, and spec views.

Architecture: CommonSpec (language) compiles into SpecIR (intermediate representation) via SpecCompiler (compiler).

Specification: See the CommonSpec Language Specification (docs/commonspec/) for the formal definition.

Purpose: Provides a portable, queryable storage format for specification data. Compilation target for CommonSpec and interchange format for other tools (ReqIF, DOORS CSV, SQL).

Schema: Two core layers: Type System tables (metamodel) and Content tables (data). Build infrastructure and FTS tables are not part of the SpecIR standard.

Specification: See the SpecIR Schema Specification (docs/specir/) for the formal definition.

Purpose: Resolves cross-references between spec objects and infers missing type information.

Position: Second phase after INITIALIZE, before TRANSFORM.

Purpose: Stores content hashes to detect which documents have changed since last build.

Implementation: Compares current file hash against cached hash to skip unchanged files.

Purpose: Groups related float types to share sequential numbering.

Example: FIG and DIAGRAM types may share a counter, producing Figure 1, Figure 2, etc.

Purpose: Groups software units into higher-level structural components for design allocation.

Examples: src/core, src/db, src/infra.

Purpose: Captures file-level implementation units allocated to functional descriptions.

Examples: src/core/pipeline.lua, src/db/manager.lua.

Purpose: Produces structured data that can be injected into chart floats.

Implementation: A dataset DATA hook receives a frozen data context (reading subject.params) and returns a { source / data / links } dataset. The descriptor is resolved from models/{requested}/types/views/{view} with fallback to models/default/types/views/{view}.

Purpose: Flexible schema for storing typed attributes on spec objects.

Structure: Entity (spec object), Attribute (key name), Value (typed content).

Purpose: Assembles transformed content and writes final output documents.

Position: Final phase after ANALYZE.

Purpose: Delegates rendering to external tools via subprocess execution.

Examples: PlantUML JAR for diagrams, chart libraries for data visualization.

Purpose: Encapsulates processing logic for a content type. Behaviour lives only under a descriptor’s hooks table; the host classifies each hook by name and indexes it into the (kind, id) -> hook map.

Structure: Two kinds of contributions, both keyed by hook name:

• Phase participation — on_<phase> functions (on_initialize, on_analyze, on_transform, on_verify, on_emit) declared in hooks beside the behavior hooks; the host synthesizes them into pipeline:register_handler under the derived name <lower(id)>_handler, ordered via schema.phase_prerequisites. Each runs once per phase with full pipeline context.
• Per-item hooks — RENDER hooks (render, render_block, render_link, message) and DATA hooks (dataset, build_block, transform, resolve, prepare_task, handle_result). The hook NAME selects one of two context tiers (a frozen render ctx or a frozen data ctx) and the return type the hook owes. Consumers resolve them via get_hook_inherited, which walks the extends chain.

Purpose: Parses markdown AST and populates intermediate representation containers.

Position: First phase, entry point for document processing.

Purpose: Bundles related type descriptors (each carrying its own hooks) and styling for specific documentation domains. The host overlays default then each model later-wins-by-id, so a model overrides only the type ids it redefines.

Examples: SRS model for software requirements, HRS model for hardware requirements.

Purpose: Tracks when outputs were last generated to enable incremental builds.

Implementation: Compares source modification time against cached output timestamp.

Purpose: Separates document processing into well-defined sequential stages.

Phases: INITIALIZE, RESOLVE, TRANSFORM, ANALYZE, EMIT.

Purpose: Orchestrates document processing through sequential phases.

Flow: Each phase completes for all handlers before the next phase begins.

Purpose: Declares which handlers must complete before a given handler can execute.

Usage: Handlers declare prerequisites to ensure data dependencies are satisfied.

Purpose: Determines valid execution order for handlers based on dependencies.

Algorithm: Uses Kahn’s algorithm to produce a topologically sorted handler sequence.

Purpose: Materializes database views into content and applies content transformations.

Position: Third phase after RESOLVE, before ANALYZE.

Purpose: Provides shorthand or alternative names for types.

Example: csv is an alias for the TABLE type in float definitions.

Purpose: Discovers each model’s type descriptors and registers them with the SpecIR type tables, the data manager, and the pipeline.

Implementation: Overlays the default model then each requested model (later-wins-by-id; resolved repo-bundled under SPECCOMPILER_HOME/models/{model} then cwd, no out-of-tree path). For each models/{model}/types/{category}/ file it loads the single returned descriptor { kind, schema, [hooks] }, validates it (known kind, present schema.id, each hook valid for the kind, no behaviour on top-level keys), emits the type row, and eager-indexes each hook into a (kind, id) -> hook map read via get_hook / get_hook_inherited (which walks the extends chain). host:finalize() then propagates inherited attributes, creates the verification SQL views, and asserts required hooks.

Purpose: Stores type definitions including attributes, aliases, and validation rules.

Tables: spec_object_types, spec_float_types, spec_attribute_types, etc.

Purpose: Validates document content using analyze queries and constraint checking.

Position: Fourth phase after TRANSFORM, before EMIT.

Purpose: Represents document structure as a hierarchical tree of elements.

Source: Pandoc parses Markdown and produces JSON AST.

Usage: Handlers walk the AST to extract spec objects, floats, and relations.

Purpose: Indexes specification text for fast full-text search queries.

Implementation: SQLite FTS5 virtual tables populated during EMIT phase.

Usage: Web application uses FTS for search functionality.

Purpose: Defines system-level requirements that guide design and implementation.

Traceability: HLRs trace to verification cases (VC) and are realized by functional descriptions (FD).

Purpose: Stores parsed specification content in queryable form.

Storage: SQLite database with spec_objects, spec_floats, spec_relations tables.

Lifecycle: Populated during INITIALIZE, queried and modified through remaining phases.

Purpose: Provides unique, human-readable identifiers for traceability and cross-referencing.

Syntax: Written as @PID in header text (e.g., ## HLR: Requirement Title @REQ-001).

Auto-generation: PIDs can be auto-generated from type prefix and sequence number.

Purpose: Defines validation rules as SQL queries that detect specification errors.

Execution: Run during the ANALYZE phase; violations are reported as diagnostics.

Examples: Missing required attributes, unresolved relations, cardinality violations.

Purpose: Provides persistent, portable storage for the intermediate representation.

Benefits: Single-file storage, ACID transactions, SQL query capability.

Usage: All pipeline phases read/write to SQLite via the database manager.

Purpose: Base type for objects that can be linked via traceability relations.

Types: Any spec object type registered in the model (e.g., HLR, LLR, SECTION).

Relations: Model-defined relation types (e.g., XREF_FIGURE, XREF_CITATION) inferred by specificity matching.

Purpose: Defines the schema, validation rules, and hooks behaviour for a category of elements.

Categories: Object types (HLR, SECTION), float types (FIGURE, TABLE), relation types (TRACES_TO), view types (TOC, LOF).

Registration: Each type is one descriptor ({ kind, schema, hooks }) loaded from a model’s category directory, validated by the host engine, and emitted into the type registry.

Purpose: Defines how requirements are verified through test procedures and expected results.

Traceability: VCs trace to HLRs via traceability attribute links.

Naming: VC PIDs follow the pattern VC-{category}-{seq} (e.g., VC-PIPE-001).

Purpose: Distinguishes object types that represent document structure (e.g., SECTION) from traceable types that receive standalone PIDs (e.g., HLR, VC).

PID behavior: Composite objects get hierarchical PIDs derived from the specification PID (e.g., SRS-sec1.2.3). Non-composite objects get independent PIDs from their pid_prefix and pid_format (e.g., HLR-001).

Configuration: Set via is_composite = true in the descriptor’s schema.

Purpose: Identifies what kind of relation a Markdown link represents, enabling type-driven inference.

Selectors: @ (PID reference, e.g., [HLR-001](@)), # (label reference, e.g., [fig:diagram](#)), @cite (bibliographic citation).

Configuration: Each relation type declares a link_selector value in spec_relation_types. Selectors are model-defined, not hardcoded.

Purpose: Resolves ambiguity when multiple relation types match a given link by selecting the most specific type.

Algorithm: Each non-NULL constraint match across four dimensions (selector, source_attribute, source_type, target_type) adds one point. The highest total score wins. Ties mark the relation as ambiguous.

Example: A relation type with constraints on selector + source_type + target_type (score 3) wins over one with only selector (score 1).

Purpose: Provides a single hash that represents the fully processed state of a specification, including all resolved relations, materialized views, and transformed content.

Usage: The output cache stores the P-IR hash alongside each generated output file. When rebuilding, the system compares the current P-IR hash to the cached hash to determine if output regeneration is needed.

Distinction: Unlike the build cache (which tracks source file hashes), the P-IR hash captures the post-processing state, detecting changes from cross-document operations.

Purpose: Provides machine-parseable structured logging suitable for CI/CD log aggregation and filtering with tools like jq.

Format: One JSON object per line with fields: level, message, timestamp, and optional context fields.

Usage: The logger emits NDJSON when output is not connected to a TTY (e.g., piped to a file or running in CI).

Purpose: Allows projects to control validation strictness by mapping each analyze query to a severity level.

Severity levels: error (blocks output generation), warn (reported but build continues), ignore (suppressed).

Configuration: Set in the validation: section of project.yaml (e.g., traceability_hlr_to_vc: warn).

Default: When a policy_key is not configured, the system applies its built-in default severity.

Purpose: Provides machine-parseable and human-readable feedback on specification errors and warnings throughout all pipeline phases.

Fields: Each record contains file (source path), line (source line number), code (stable diagnostic key, usually the analyze query policy_key, e.g., dangling_relation), and msg (human-readable description).

Severity: Errors trigger abort after ANALYZE Phase phase; warnings are reported but do not block output generation.

Purpose: Records the full file set of each document build — the root document itself and every included file — enabling change detection across include hierarchies with a single node walk.

Storage: Stored in the build_graph table with columns root_path (the document being built), node_path (a file that build read: the root itself or an include), and node_sha1 (content hash at build time).

Usage: Queried by Build Cache is_document_dirty() to determine if the root or any included file has changed since the last successful build.

Purpose: Marks positions in the assembled Pandoc document where floats and views will be substituted during the EMIT Phase phase.

Mechanism: During assembly, sdd: Document Assembler inserts CodeBlock elements at the correct file_seq positions. Downstream handlers (sdd: Float Emitter for floats, sdd: View Emitter for views) match these placeholders by label and replace them with rendered content.

Lifecycle: Created during assembly, consumed during float/view emission, never present in final output.