Skip to content

Metrics M-1: rs-metric catalog + compute-metrics; TAXONOMY_AUTHORING_ENABLED gate#894

Merged
jfrench9 merged 1 commit into
mainfrom
feature/taxonomy-flag-and-metrics
Jul 20, 2026
Merged

Metrics M-1: rs-metric catalog + compute-metrics; TAXONOMY_AUTHORING_ENABLED gate#894
jfrench9 merged 1 commit into
mainfrom
feature/taxonomy-flag-and-metrics

Conversation

@jfrench9

Copy link
Copy Markdown
Member

Summary

Two workstreams in one PR (deploy-coupled by design):

Metrics backend MVP (M-1)

  • rs-metric library package (frameworks/rs-gaap/packages/rs-metric/v1, ordinal 14): the Key Financial Metrics catalog — Working Capital, Current Ratio, Quick Ratio, Debt-to-Equity, Interest Coverage. Each metric is a qname-addressable concept plus one Derive rule ($Metric = f(rs-gaap operands), same ruleVariables shape as the rollup rules), and the container node is both an abstract element and the seeded block_type='metric' Structure every tenant receives.
  • compute-metrics operation (REST + auto-generated MCP tool): binds each Derive rule's operands to the entity's most recent persisted report facts at period_end, evaluates via the existing safe AST evaluator (evaluate_derivation), and upserts a standing factset_type='metric' FactSet per (structure, entity, period_end) — the accumulating time series. Re-running a period replaces its values. Missing operands / undefined ratios skip with a reason, never error the run.
  • Metric envelope renders the standing series: one period column per FactSet, one row per catalog concept in presentation-arc order; fact_set_id pin honored.
  • Migration 0022 — the first package-adding migration: widens three vocabulary CHECKs (factset_type +'metric', rule_pattern +'Derive', element source +'rs-metric') across public + every tenant schema, seeds the package into the public library, mirrors the framework_packages junction row, and resyncs into existing tenants under the 0016 bypass GUC. Fresh deployments get everything from 0002 + provisioning (manifest + _widen_library_checks + models updated in lockstep).

TAXONOMY_AUTHORING_ENABLED (environment gate)

Walls tenant framework authoring (reporting_extension / custom_ontology taxonomy blocks) behind an environment-level flag while the surface seasons:

  • Gate sits at the taxonomy-block command dispatch chokepoint — one check covers REST and the auto-generated MCP tools (tool-listing gating is impossible: the tools are block_type-blind and must stay listed for chart_of_accounts).
  • Create + update → 403 when off; delete stays open (content removal reduces liability); chart_of_accounts is never gated.
  • Fail-closed in prod/staging: the code default is false there, so a missing SSM parameter cannot open the surface. Dev/test default on (the scenario demos author disclosure notes). Enable later with just ssm-set <env> features/TAXONOMY_AUTHORING_ENABLED true + API restart (flags read once at process start).

Verification

  • Full unit suite + ruff + basedpyright green (one known pre-existing order-dependent flake in test_incremental_materialize, passes isolated).
  • Migration 0022 ran against a dev DB with two provisioned tenant schemas — public seed, junction row, and per-tenant resync all clean.
  • Full Driftline demo e2e: catalog computes at both comparative period ends (Working Capital $88.0k → $238.5k, Current Ratio 3.27 → 5.59, Quick Ratio 2.70 → 3.74, D/E 0.27 → 0.17), Interest Coverage skips with a reason for the debt-free company, and the envelope renders the two-period series.

Deploy notes

  • Extensions migration 0022 must ship in the same window as this code (deploy-coupled with 0021 from the M3 arc).
  • Nit (not fixed here): unit='pure' facts mint a cosmetically-wrong iso4217:pure unit node on materialize.
  • bin/setup/aws.sh feature-flag seed array has pre-existing stale entries (LEDGER_ENABLED) — left as-is, only the new flag added.

… authoring

- Seed the rs-metric library package (Key Financial Metrics: working
  capital, current/quick ratio, debt-to-equity, interest coverage) --
  elements + structure + presentation arcs + Derive rules over rs-gaap
  anchors. Migration 0022 widens the vocabulary CHECKs (factset_type
  'metric', rule_pattern 'Derive', element source 'rs-metric') and
  backfills existing deployments: public library seed, framework_packages
  junction row, and per-tenant resync under the 0016 bypass GUC.
- compute-metrics operation (REST + auto-generated MCP tool): binds each
  Derive rule's operands to the entity's most recent persisted report
  facts at period_end, evaluates via the safe AST evaluator, and upserts
  a standing factset_type='metric' FactSet per (structure, entity,
  period_end) -- the accumulating time series; re-runs replace the
  period's values. Missing operands and undefined ratios skip with a
  reason, never error the run.
- Metric envelope builder renders the standing series: one period column
  per FactSet, one row per catalog concept in presentation-arc order.
- TAXONOMY_AUTHORING_ENABLED gates reporting_extension/custom_ontology
  taxonomy-block authoring (create + update -> 403) per environment,
  fail-closed in prod/staging; delete stays open and chart_of_accounts
  is never gated. One check at the command dispatch chokepoint covers
  REST and MCP.
- Driftline demo probe computes both comparative period ends and
  verifies the rendered two-period series; InterestCoverage exercises
  the skip path for the debt-free scenario.
@jfrench9
jfrench9 merged commit a4bdd27 into main Jul 20, 2026
6 checks passed
@jfrench9
jfrench9 deleted the feature/taxonomy-flag-and-metrics branch July 20, 2026 03:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant