methodology_id: standard_entity_metric_period_table
name: Standard Entity-Metric-Period Table Construction
type: normalization_rule
domain: all

applies_to:
  agent: analytical_table
  triggers:
    - input is a set of pillar_1 resolved records
    - records contain entity, metric, period, value tuples
    - no domain-specific structuring methodology applies

definition:
  structuring_rules:
    - Rows are entities, identified by primary_identifier from Pillar 1 records
    - Columns are metrics, named by the normalized metric key from the JobRequest
    - Period dimension is preserved; if multiple periods are present, the table is faceted by period
    - Each cell contains a single value plus lineage_to_pillar_1 reference

  period_alignment:
    - All annual periods normalized to FY-YYYY format
    - All quarterly periods normalized to QN-YYYY format
    - Fiscal year boundaries respected as reported by source (do not force calendar alignment)
    - If entities report on different fiscal calendars, annotate but do not collapse

  unit_normalization:
    - All currency values normalized to USD where source currency is stated
    - Magnitudes preserved as reported; do not convert to millions or billions
    - Units field on every cell records the source's stated unit
    - If unit is missing from source, cell is marked as unit_unknown and flagged

  missing_cell_handling:
    - If no Pillar 1 record exists for an (entity, metric, period) combination, the cell is null
    - Null cells carry a structured note. reason is no_source_record, escalation_eligible is true
    - Do not interpolate. Do not estimate. Do not fabricate.

  lineage_stamping:
    - Each populated cell references the specific Pillar 1 record_id it came from
    - Each populated cell carries through the source filing accession and date from Pillar 1

inputs:
  - source: pillar_1_output
    field: resolved_records
    required: true
  - source: job_request
    field: entities, target_metrics, periods
    required: true

outputs:
  - analytical_table with rows as entities, columns as metrics, periods as dimensional facets, cells containing value, unit, lineage_ref, and notes

rationale: |
  This is the framework's foundational methodology for converting Pillar 1's record-stream
  output into an analytical table structure. It defines only the mechanical structuring rules
  - how to arrange data, how to align periods, how to handle missing cells, how to preserve
  lineage. It does not interpret the data or apply any domain-specific transformations.

  Domain SMEs should encode more specific structuring methodologies for cases where domain
  conventions matter (e.g., fiscal year normalization rules specific to insurance, period
  treatment specific to banks reporting on calendar quarters). When a more specific
  methodology applies, the agent will select that one over this default.

declared_by: framework_foundation
declared_date: 2026-05-24
last_reviewed: 2026-05-24
status: active

notes: |
  Foundational methodology. Provides mechanical structuring defaults so the Analytical Table
  Agent can operate when no domain-specific methodology has been encoded. SMEs should encode
  domain-specific methodologies as the framework expands; this default applies only when
  nothing more specific matches.