@yottagraph-app/data-model-skill 0.0.34 → 0.0.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "description": "Data model skill documentation for AI agents - entity types, properties, and schemas from Lovelace fetch sources",
   "repository": {
     "type": "git",

package/skill/blscew/DATA_DICTIONARY.md

@@ -0,0 +1,389 @@
+# Data Dictionary: BLS CEW (QCEW)
+
+## Purpose
+
+This dictionary documents the entity types, properties, and attributes
+that the BLS Quarterly Census of Employment and Wages (QCEW) source
+contributes to the Lovelace knowledge graph. It is the contract between
+the source and downstream consumers (ingest, query server, UI).
+
+QCEW is a quarterly count of employment and wages reported by employers,
+covering more than 95 % of US jobs. It is published by the U.S. Bureau
+of Labor Statistics for every state, MSA, and county, broken out by
+ownership (federal/state/local/private) and by industry (NAICS), at the
+sector / 3-digit / 4-digit / 5-digit / 6-digit detail levels. The
+Lovelace QCEW source ingests the published quarterly data slices —
+specifically the by-area CSV slices for the United States as a whole
+plus all 50 states and DC — and emits one record per area × ownership ×
+industry × quarter combination.
+
+**Pipeline:** Download → Extract → Atomize.
+- Download fetches the per-area CSV slice for each (area, year, quarter)
+  from `https://data.bls.gov/cew/data/api/{year}/{quarter}/area/{area_fips}.csv`.
+- Extract is a pass-through (the raw CSV is the structured input).
+- Atomize parses each CSV row into KG records.
+
+**Cadence:** BLS publishes each quarter's QCEW release roughly 5–7
+months after the close of the quarter (Q1 in late Aug/Sep, Q2 in late
+Nov/Dec, Q3 in early Mar of the next year, Q4 in early Jun). The
+streamer polls weekly; new quarters are detected and atomized when they
+appear.
+
+**Disclosure suppression.** Rows with `disclosure_code == "N"` are
+withheld by BLS to protect employer confidentiality (typically when an
+industry has very few establishments in an area). All numeric values on
+those rows are zero. The atomizer drops "N"-disclosed rows entirely so
+the KG never contains zero-valued QCEW observations that would be
+mistaken for real data.
+
+**Series identity.** A QCEW "series" is uniquely identified by the
+4-tuple (area_fips, own_code, industry_code, agglvl_code). The atomizer
+constructs a synthetic series id of the form
+`{area_fips}.{own_code}.{industry_code}.{agglvl_code}` and emits this
+as the `cew_series_id` strong id on a `cew_series` entity. `size_code`
+is always `0` for the quarterly area slices ingested today (size-class
+slices are an annual-only artifact and are out of scope for v1).
+
+**Source name:** `blscew-source`
+
+---
+
+## Entity Types
+
+### `cew_series`
+
+A single QCEW time series — the unique combination of geographic area,
+ownership, industry, and aggregation level — that carries quarterly
+employment, wages, and establishment metrics over time.
+
+- Primary key: `cew_series_id` (synthetic id, see above) used as the
+  strong id for resolution.
+- Entity resolver: named entity, NOT_MERGEABLE. The strong id is
+  `cew_series_id`. The disambiguation snippet includes area title,
+  ownership title, industry title, and aggregation level title.
+- Source: `blscew-source`
+- Examples produced: `US000.0.10.10` (US national, total ownership, all
+  industries), `06000.5.31-33.55` (California, private ownership,
+  Manufacturing supersector), `06037.0.5111.74` (Los Angeles County,
+  total ownership, NAICS 5111 Newspaper / Periodical Publishers).
+
+### `location`
+
+A US geographic area (national, state, MSA, or county) for which BLS
+publishes QCEW data, identified by its FIPS-based `area_fips` code.
+
+- Primary key: `area_fips` strong id.
+- Entity resolver: named entity, NOT_MERGEABLE. Strong id is
+  `area_fips`. Snippet includes the area title and the area type
+  (national / statewide / MSA / county).
+- Source: `blscew-source`
+- Examples produced: `US000` (U.S. TOTAL), `06000` (California -- Statewide),
+  `06037` (Los Angeles County, California), `C1018` (Albany-Schenectady-Troy,
+  NY MSA).
+
+### `industry`
+
+An economic activity category from the North American Industry
+Classification System (NAICS), or a BLS-defined supersector that rolls
+up multiple NAICS sectors.
+
+- Primary key: `naics_code` strong id (the BLS QCEW `industry_code`,
+  which can be a NAICS sector / 3-digit / 4-digit / 5-digit / 6-digit
+  code, a 2-digit BLS supersector aggregate (e.g. `31-33` for
+  Manufacturing), or the special aggregate `10` meaning "Total, all
+  industries").
+- Entity resolver: named entity, NOT_MERGEABLE. Strong id is
+  `naics_code`. Snippet includes the industry title.
+- Source: `blscew-source`
+- Examples produced: `10` (Total, all industries), `31-33`
+  (Manufacturing), `5111` (Newspaper, Periodical, Book, and Directory
+  Publishers), `541` (Professional, Scientific, and Technical Services).
+
+---
+
+## Properties
+
+### Identity & Metadata Properties (cew_series)
+
+These atoms appear once per series, timestamped at the first quarter
+the series is observed in the current run.
+
+* `cew_series_id`
+  * Definition: synthetic identifier for a QCEW series, built by
+    joining the area, ownership, industry, and aggregation-level codes
+    with dots.
+  * Examples: `"US000.0.10.10"`, `"06000.5.31-33.55"`,
+    `"06037.0.5111.74"`
+  * Derivation: built by the atomizer from the QCEW `area_fips`,
+    `own_code`, `industry_code`, and `agglvl_code` fields of each CSV
+    row.
+
+* `name`
+  * Definition: human-readable label for the series, combining area,
+    ownership, and industry titles.
+  * Examples: `"U.S. TOTAL · Total Covered · Total, all industries"`,
+    `"California · Private · Manufacturing"`
+  * Derivation: built from the `area_title`, `own_title`, and
+    `industry_title` fields on the CSV row.
+
+* `area_fips`
+  * Definition: BLS-assigned 5-character area identifier (FIPS-based).
+    Acts as strong id on the `location` entity that the series points
+    to.
+  * Examples: `"US000"`, `"06000"`, `"06037"`, `"C1018"`
+  * Derivation: `area_fips` field of the CSV row.
+
+* `area_title`
+  * Definition: human-readable title for the geographic area.
+  * Examples: `"U.S. TOTAL"`, `"California -- Statewide"`,
+    `"Los Angeles County, California"`,
+    `"Albany-Schenectady-Troy, NY MSA"`
+  * Derivation: `area_title` field of the CSV row.
+
+* `ownership_code`
+  * Definition: BLS one-character code identifying the ownership
+    sector covered by the series.
+  * Examples: `"0"` (Total Covered), `"1"` (Federal Government),
+    `"2"` (State Government), `"3"` (Local Government),
+    `"5"` (Private)
+  * Derivation: `own_code` field of the CSV row.
+
+* `ownership_title`
+  * Definition: human-readable label for the ownership sector.
+  * Examples: `"Total Covered"`, `"Federal Government"`,
+    `"State Government"`, `"Local Government"`, `"Private"`
+  * Derivation: `own_title` field of the CSV row.
+
+* `naics_code`
+  * Definition: industry code used by BLS — NAICS at varying levels of
+    aggregation, plus BLS supersector aggregates and the special
+    "Total, all industries" code `10`. Acts as strong id on the
+    `industry` entity that the series points to.
+  * Examples: `"10"`, `"31-33"`, `"5111"`, `"541211"`
+  * Derivation: `industry_code` field of the CSV row.
+
+* `naics_description`
+  * Definition: human-readable name of the industry / supersector.
+  * Examples: `"Total, all industries"`, `"Manufacturing"`,
+    `"Newspaper, periodical, book and directory publishers"`
+  * Derivation: `industry_title` field of the CSV row.
+
+* `aggregation_level_code`
+  * Definition: BLS two-character code describing the geographic and
+    industry aggregation level the series represents (e.g. national
+    total, statewide ownership × supersector, county × 6-digit NAICS).
+  * Examples: `"10"` (national, by ownership × total), `"55"`
+    (statewide, by ownership × supersector),
+    `"74"` (county, by ownership × 5-digit NAICS),
+    `"78"` (county, by ownership × 6-digit NAICS)
+  * Derivation: `agglvl_code` field of the CSV row.
+
+* `aggregation_level_title`
+  * Definition: human-readable description of the aggregation level.
+  * Examples: `"National, by ownership sector"`,
+    `"Statewide, by ownership sector and supersector"`,
+    `"County, by ownership sector and 6-digit NAICS"`
+  * Derivation: `agglvl_title` field of the CSV row.
+
+* `area_type`
+  * Definition: classification of the area as one of `national`,
+    `statewide`, `msa`, or `county` derived from the leading characters
+    of `area_fips` and the trailing zeros pattern.
+  * Examples: `"national"`, `"statewide"`, `"county"`, `"msa"`
+  * Derivation: heuristic on `area_fips`: `US000` → national; FIPS
+    starting with `C` → MSA; 5-digit ending in `000` → statewide; any
+    other 5-digit code → county.
+
+* `naics_level`
+  * Definition: granularity of the NAICS code on this row, where
+    higher values are more specific. Stored as a float to keep with
+    the schema's float-for-numeric convention.
+  * Examples: `2.0` (sector or supersector), `3.0` (subsector),
+    `4.0` (industry group), `5.0` (NAICS industry), `6.0` (national
+    industry).
+  * Derivation: length of the `industry_code` string, with the special
+    case `10` (Total) and any 2-character supersector code mapped to
+    `2.0`.
+
+* `publisher`
+  * Definition: organization that publishes the data (always BLS).
+  * Examples: `"U.S. Bureau of Labor Statistics"`
+  * Derivation: hard-coded constant; QCEW is exclusively a BLS product.
+
+### Quarterly Observation Properties (cew_series)
+
+These atoms appear on the per-quarter observation records, timestamped
+at the last day of the quarter (e.g. 2024-03-31 for Q1 2024).
+
+* `establishment_count`
+  * Definition: count of establishments (physical locations of
+    employers) covered by the series in the quarter.
+  * Examples: `11907855` (US total Q1 2024), `61375` (US Federal
+    Government total Q1 2024)
+  * Derivation: `qtrly_estabs` field of the CSV row.
+
+* `monthly_employment_m1`, `monthly_employment_m2`, `monthly_employment_m3`
+  * Definition: number of employees on payrolls covered in the first /
+    second / third month of the quarter (BLS uses the pay period
+    including the 12th of the month).
+  * Examples (US Q1 2024 total): `152393725`, `153129544`, `153848430`
+  * Derivation: `month1_emplvl`, `month2_emplvl`, `month3_emplvl`
+    fields of the CSV row.
+
+* `employment_level`
+  * Definition: representative quarterly employment level for the
+    series, taken as the third-month employment (final month of the
+    quarter), aligned to the way QCEW publications report "QCEW
+    employment".
+  * Examples: `153848430` (US Q1 2024 total)
+  * Derivation: `month3_emplvl` field of the CSV row.
+
+* `total_quarterly_wages`
+  * Definition: total wages paid (in current US dollars) to all covered
+    workers during the quarter.
+  * Examples: `3037790324790` (US Q1 2024 total = $3.04 trillion)
+  * Derivation: `total_qtrly_wages` field of the CSV row.
+
+* `taxable_quarterly_wages`
+  * Definition: portion of total quarterly wages subject to UI tax
+    contributions (in current US dollars). Always 0 for federal
+    government employment, which is not subject to UI tax.
+  * Examples: `1151875077520` (US Q1 2024 total)
+  * Derivation: `taxable_qtrly_wages` field of the CSV row.
+
+* `quarterly_contributions`
+  * Definition: total UI tax contributions (in current US dollars)
+    associated with this employment in the quarter.
+  * Examples: `19555346530` (US Q1 2024 total)
+  * Derivation: `qtrly_contributions` field of the CSV row.
+
+* `avg_weekly_wage`
+  * Definition: average weekly wage (in current US dollars) per
+    employee covered in the quarter, computed by BLS as
+    `total_qtrly_wages / (avg_emplvl × 13)`.
+  * Examples: `1526` (US Q1 2024 total = $1,526/week)
+  * Derivation: `avg_wkly_wage` field of the CSV row.
+
+### Year-over-Year Change Properties (cew_series)
+
+BLS pre-computes over-the-year (OTY) absolute and percent changes for
+each quarterly metric, comparing the current quarter to the same quarter
+of the prior year. The atomizer emits the percent-change variants as
+their own atoms so downstream consumers can directly query
+"Employment growth YoY" without recomputing it from observation history.
+
+* `employment_yoy_pct_chg`
+  * Definition: year-over-year percent change in the canonical
+    `employment_level` (= third-month / end-of-quarter snapshot).
+  * Examples: `1.5` (US total Q1 2024 vs Q1 2023 = +1.5 %)
+  * Derivation: `oty_month3_emplvl_pct_chg` field of the CSV row. We
+    intentionally do *not* also emit `monthly_employment_m3_yoy_pct_chg`
+    -- it would duplicate this number under a redundant property name.
+
+* `monthly_employment_m1_yoy_pct_chg`, `monthly_employment_m2_yoy_pct_chg`
+  * Definition: year-over-year percent change in mid-quarter monthly
+    employment (the M1 and M2 snapshots that have no canonical alias;
+    the M3 snapshot is exposed as `employment_yoy_pct_chg` above).
+  * Examples (US Q1 2024 total): `1.4`, `1.4`
+  * Derivation: `oty_month1_emplvl_pct_chg`, `oty_month2_emplvl_pct_chg`,
+    `oty_month3_emplvl_pct_chg` fields of the CSV row.
+
+* `establishments_yoy_pct_chg`
+  * Definition: year-over-year percent change in the count of
+    establishments.
+  * Examples: `1.2` (US Q1 2024 total = +1.2 %)
+  * Derivation: `oty_qtrly_estabs_pct_chg` field of the CSV row.
+
+* `total_quarterly_wages_yoy_pct_chg`
+  * Definition: year-over-year percent change in total quarterly
+    wages.
+  * Examples: `5.7` (US Q1 2024 total = +5.7 %)
+  * Derivation: `oty_total_qtrly_wages_pct_chg` field of the CSV row.
+
+* `avg_weekly_wage_yoy_pct_chg`
+  * Definition: year-over-year percent change in the average weekly
+    wage.
+  * Examples: `4.2` (US Q1 2024 total = +4.2 %)
+  * Derivation: `oty_avg_wkly_wage_pct_chg` field of the CSV row.
+
+* `taxable_quarterly_wages_yoy_pct_chg`
+  * Definition: year-over-year percent change in taxable quarterly
+    wages.
+  * Examples: `3.3`
+  * Derivation: `oty_taxable_qtrly_wages_pct_chg` field of the CSV row.
+
+* `quarterly_contributions_yoy_pct_chg`
+  * Definition: year-over-year percent change in UI contributions.
+  * Examples: `4.3`
+  * Derivation: `oty_qtrly_contributions_pct_chg` field of the CSV row.
+
+### Location Properties (location)
+
+* `area_fips`
+  * Definition: BLS-assigned area identifier (FIPS-based) used as the
+    location's strong id.
+  * Examples: `"US000"`, `"06000"`, `"06037"`, `"C1018"`
+  * Derivation: `area_fips` field of the CSV row.
+
+* `name`
+  * Definition: human-readable name of the geographic area.
+  * Examples: `"U.S. TOTAL"`, `"California -- Statewide"`,
+    `"Los Angeles County, California"`
+  * Derivation: `area_title` field of the CSV row.
+
+* `area_type`
+  * Definition: classification of the area as `national`, `statewide`,
+    `msa`, or `county`.
+  * Examples: `"national"`, `"statewide"`, `"county"`, `"msa"`
+  * Derivation: heuristic on `area_fips`; see the `cew_series` entry of
+    the same name above.
+
+### Industry Properties (industry)
+
+* `naics_code`
+  * Definition: industry code used by BLS (NAICS at sector / 3-digit /
+    4-digit / 5-digit / 6-digit detail, plus BLS supersector aggregates
+    and `10` = Total, all industries). Strong id for `industry`.
+  * Examples: `"10"`, `"31-33"`, `"5111"`, `"541211"`
+  * Derivation: `industry_code` field of the CSV row.
+
+* `naics_description`
+  * Definition: human-readable industry name.
+  * Examples: `"Total, all industries"`, `"Manufacturing"`,
+    `"Newspaper, periodical, book and directory publishers"`
+  * Derivation: `industry_title` field of the CSV row.
+
+* `naics_level`
+  * Definition: granularity of the NAICS code (see the `cew_series`
+    entry of the same name above for derivation).
+  * Examples: `2.0`, `3.0`, `4.0`, `5.0`, `6.0`
+
+---
+
+## Entity Relationships Summary
+
+The QCEW source emits two relationship types — both pointing from the
+real-world contextual entity (a US area or an industry) to the
+`cew_series` it appears in. This mirrors the FRED source's
+`appears_in_fred_series` pattern.
+
+```
+location  ──[appears_in_cew_series]──→ cew_series
+industry  ──[appears_in_cew_series]──→ cew_series
+```
+
+* `appears_in_cew_series`
+  * Definition: the subject (a US geographic area or an industry)
+    appears as the area / industry dimension of a QCEW time series.
+  * Domain flavors: `location`, `industry`
+  * Target flavor: `cew_series`
+  * Derivation: emitted once per series per quarter on the location and
+    industry context records.
+
+---
+
+## Attributes
+
+None. All quarterly metrics are timestamped scalar atoms; there are no
+per-atom attributes (unit / frequency / etc.) on this source — those are
+carried as atoms on the `cew_series` metadata record.

package/skill/blscew/schema.yaml

@@ -0,0 +1,345 @@
+# Dataset schema for BLS QCEW (Quarterly Census of Employment and Wages).
+#
+# Architecture mirrors FRED:
+#   For each unique QCEW series — the (area_fips, own_code, industry_code,
+#   agglvl_code) tuple — the atomizer emits:
+#     1. A metadata record: subject is the cew_series entity, atoms are
+#        identifying metadata (cew_series_id, area_fips, area_title,
+#        ownership_code/title, naics_code/description, aggregation level,
+#        publisher, etc.). Timestamped at the quarter end date.
+#     2. One quarterly observation record per (series, quarter): subject is
+#        the cew_series, atoms are all quarterly metrics — establishment
+#        count, employment levels, wages, year-over-year percent changes —
+#        all timestamped at the quarter end date.
+#     3. A location context record: subject is the geographic area
+#        (location flavor), single appears_in_cew_series atom pointing at
+#        the cew_series.
+#     4. An industry context record: subject is the NAICS industry
+#        (industry flavor), single appears_in_cew_series atom pointing at
+#        the cew_series.
+#
+# All elements are passive — created by the atomizer from QCEW CSV data,
+# not by LLM extraction.
+#
+# Source identifier used on all records: "blscew-source"
+name: "blscew"
+description: "Quarterly Census of Employment and Wages from the U.S. Bureau of Labor Statistics — quarterly establishment counts, employment levels, total and taxable wages, average weekly wages, and BLS-computed year-over-year changes by US area, ownership sector, and NAICS industry"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "cew_series"
+    description: "A QCEW (Quarterly Census of Employment and Wages) time series identified by the unique combination of area, ownership, industry, and aggregation level. The entity carries metadata atoms and per-quarter observations of employment, wages, and establishment counts."
+    display_name: "QCEW Series"
+    mergeability: not_mergeable
+    strong_id_properties: ["cew_series_id"]
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    strong_id_properties: ["area_fips"]
+    passive: true
+
+  - name: "industry"
+    description: "An industry classification of economic activity (e.g. NAICS or SIC) identifying the line of business associated with an organization or award"
+    display_name: "Industry"
+    mergeability: not_mergeable
+    strong_id_properties: ["naics_code"]
+    passive: true
+
+properties:
+  # --- Strong-id properties ---
+
+  - name: "cew_series_id"
+    type: string
+    description: "Synthetic identifier for a QCEW series formed by joining area_fips, own_code, industry_code, and agglvl_code with dots. Strong id for cew_series entities."
+    display_name: "QCEW Series ID"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["US000.0.10.10", "06000.5.31-33.55", "06037.0.5111.74"]
+    passive: true
+
+  - name: "area_fips"
+    type: string
+    description: "BLS-assigned 5-character QCEW area identifier (FIPS-based). For US states the value is the 2-digit FIPS state code followed by '000' (e.g. '06000' = California). For counties it is the 5-digit county FIPS (e.g. '06037' = Los Angeles County). For MSAs the BLS prefixes a 'C' (e.g. 'C1018' = Albany–Schenectady–Troy MSA). Strong id for the location entity that a cew_series is attached to."
+    display_name: "QCEW Area FIPS"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["US000", "06000", "06037", "C1018"]
+    passive: true
+
+  - name: "naics_code"
+    type: string
+    description: "North American Industry Classification System code (typically 6 digits) identifying the industry of work performed under a contract (e.g., \"524114\" for Direct Health and Medical Insurance Carriers)"
+    display_name: "NAICS code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: ["10", "31-33", "5111", "541211"]
+    passive: true
+
+  # --- Identity / metadata properties on cew_series ---
+
+  - name: "name"
+    type: string
+    description: "Display name of the entity"
+    display_name: "Name"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["California -- Statewide", "U.S. TOTAL · Total Covered · Total, all industries"]
+    passive: true
+
+  - name: "area_title"
+    type: string
+    description: "Human-readable title for a QCEW geographic area (national, state, MSA, or county) as published by BLS."
+    display_name: "QCEW Area Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["U.S. TOTAL", "California -- Statewide", "Los Angeles County, California", "Albany-Schenectady-Troy, NY MSA"]
+    passive: true
+
+  - name: "ownership_code"
+    type: string
+    description: "BLS one-character QCEW ownership-sector code: 0 = Total Covered, 1 = Federal Government, 2 = State Government, 3 = Local Government, 5 = Private."
+    display_name: "QCEW Ownership Code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["0", "1", "2", "3", "5"]
+    passive: true
+
+  - name: "ownership_title"
+    type: string
+    description: "Human-readable QCEW ownership-sector title (Total Covered, Federal Government, State Government, Local Government, Private)."
+    display_name: "QCEW Ownership Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["Total Covered", "Federal Government", "State Government", "Local Government", "Private"]
+    passive: true
+
+  - name: "naics_description"
+    type: string
+    description: "Human-readable name of the NAICS industry (e.g., \"DIRECT HEALTH AND MEDICAL INSURANCE CARRIERS\")"
+    display_name: "NAICS description"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: ["Total, all industries", "Manufacturing", "Newspaper, periodical, book and directory publishers"]
+    passive: true
+
+  - name: "aggregation_level_code"
+    type: string
+    description: "BLS QCEW two-character aggregation-level code describing the geographic and industry granularity of a series — for example national vs statewide vs county, and total vs supersector vs detailed NAICS."
+    display_name: "QCEW Aggregation Level Code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["10", "55", "74", "78"]
+    passive: true
+
+  - name: "aggregation_level_title"
+    type: string
+    description: "Human-readable description of a QCEW aggregation level (e.g. \"National, by ownership sector\", \"County, by ownership sector and 6-digit NAICS\")."
+    display_name: "QCEW Aggregation Level Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["National, by ownership sector", "Statewide, by ownership sector and supersector", "County, by ownership sector and 6-digit NAICS"]
+    passive: true
+
+  - name: "area_type"
+    type: string
+    description: "Classification of a QCEW area as one of national, statewide, msa, or county, derived from the shape of the area_fips code."
+    display_name: "QCEW Area Type"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["national", "statewide", "msa", "county"]
+    passive: true
+
+  - name: "naics_level"
+    type: float
+    description: "Granularity of the NAICS code on a QCEW series, expressed as the number of digits. 2.0 = sector or BLS supersector aggregate, 3.0 = subsector, 4.0 = industry group, 5.0 = NAICS industry, 6.0 = national industry."
+    display_name: "QCEW NAICS Level"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: [2.0, 3.0, 4.0, 5.0, 6.0]
+    passive: true
+
+  - name: "publisher"
+    type: string
+    description: "Name of the organization that publishes or maintains the data series, inferred from the release URL domain"
+    display_name: "Publisher"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["U.S. Bureau of Labor Statistics"]
+    passive: true
+
+  # --- Quarterly observation properties on cew_series ---
+
+  - name: "establishment_count"
+    type: float
+    description: "Count of QCEW-covered establishments (physical locations of employers) reported by BLS for the series during the quarter."
+    display_name: "QCEW Establishment Count"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [11907855.0, 61375.0]
+    passive: true
+
+  - name: "monthly_employment_m1"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the first month of the quarter (BLS uses the pay period including the 12th of the month)."
+    display_name: "QCEW Employment (Month 1)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [152393725.0]
+    passive: true
+
+  - name: "monthly_employment_m2"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the second month of the quarter (pay period including the 12th)."
+    display_name: "QCEW Employment (Month 2)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153129544.0]
+    passive: true
+
+  - name: "monthly_employment_m3"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the third month of the quarter (pay period including the 12th)."
+    display_name: "QCEW Employment (Month 3)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153848430.0]
+    passive: true
+
+  - name: "employment_level"
+    type: float
+    description: "Representative quarterly employment level for the series — taken as the third-month employment, matching the convention BLS uses when publishing single-number QCEW employment figures."
+    display_name: "QCEW Quarterly Employment Level"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153848430.0]
+    passive: true
+
+  - name: "total_quarterly_wages"
+    type: float
+    description: "Total wages paid (in current US dollars) to all QCEW-covered workers for the series during the quarter."
+    display_name: "QCEW Total Quarterly Wages (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [3037790324790.0]
+    passive: true
+
+  - name: "taxable_quarterly_wages"
+    type: float
+    description: "Portion of total quarterly wages (in current US dollars) subject to UI tax contributions. Always 0 for federal-government employment, which is not subject to UI tax."
+    display_name: "QCEW Taxable Quarterly Wages (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1151875077520.0]
+    passive: true
+
+  - name: "quarterly_contributions"
+    type: float
+    description: "Total UI tax contributions (in current US dollars) associated with the series' employment during the quarter."
+    display_name: "QCEW Quarterly UI Contributions (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [19555346530.0]
+    passive: true
+
+  - name: "avg_weekly_wage"
+    type: float
+    description: "Average weekly wage (in current US dollars) per QCEW-covered employee for the series during the quarter, computed by BLS as total_qtrly_wages / (avg_emplvl × 13)."
+    display_name: "QCEW Average Weekly Wage (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1526.0]
+    passive: true
+
+  # --- BLS-computed year-over-year percent change properties on cew_series ---
+
+  - name: "employment_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in third-month employment for the series, computed by BLS by comparing the current quarter against the same quarter of the prior year."
+    display_name: "QCEW Employment YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.5, -0.4]
+    passive: true
+
+  - name: "monthly_employment_m1_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in first-month employment for the series."
+    display_name: "QCEW Employment (Month 1) YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.4]
+    passive: true
+
+  - name: "monthly_employment_m2_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in second-month employment for the series."
+    display_name: "QCEW Employment (Month 2) YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.4]
+    passive: true
+
+  - name: "establishments_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in establishment count for the series."
+    display_name: "QCEW Establishments YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.2]
+    passive: true
+
+  - name: "total_quarterly_wages_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in total quarterly wages for the series."
+    display_name: "QCEW Total Wages YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [5.7]
+    passive: true
+
+  - name: "avg_weekly_wage_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in average weekly wage for the series."
+    display_name: "QCEW Avg Weekly Wage YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [4.2]
+    passive: true
+
+  - name: "taxable_quarterly_wages_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in taxable quarterly wages for the series."
+    display_name: "QCEW Taxable Wages YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [3.3]
+    passive: true
+
+  - name: "quarterly_contributions_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in quarterly UI contributions for the series."
+    display_name: "QCEW UI Contributions YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [4.3]
+    passive: true
+
+relationships:
+  - name: "appears_in_cew_series"
+    description: "Links a real-world contextual entity (a US geographic area or a NAICS industry) to a QCEW time series whose area or industry dimension is that entity."
+    display_name: "Appears in QCEW Series"
+    mergeability: not_mergeable
+    domain_flavors: ["location", "industry"]
+    target_flavors: ["cew_series"]
+    passive: true
+
+attributes: []

package/skill/fjcidb/DATA_DICTIONARY.md

@@ -0,0 +1,178 @@
+# Data Dictionary: FJC IDB (Federal Judicial Center — Civil Cases)
+
+Last updated: 2026-05-20
+
+## Source Overview
+
+The **Federal Judicial Center Integrated Database (IDB)** provides administrative statistics on civil cases filed in U.S. district courts. Lovelace ingests the **civil SAS extract** published on the FJC site (annual FY files such as `cv26.sas7bdat`), not PACER dockets. Each SAS row is one civil case with coded fields for court location, docket number, party labels, nature of suit, and disposition.
+
+The streamer uses a **diffing** pipeline: it materializes the SAS file (HTTP download or local path), parses rows in chunks, stores a normalized JSON snapshot per case under the raw store (`fjcidb/download/{case-id}.json`), and republishes atom batches only when a row’s JSON changes.
+
+| Item | Value |
+|------|--------|
+| Stream source constant | `fjcidb-source` |
+| `Record.Source` | `fjcidb` |
+| Default dataset URL | FJC FY civil SAS (see FJC civil cases landing page) |
+| Poll cadence | Configurable (`pollTimeMin`); typical dev runs use a large interval or one-shot via fetcheval |
+
+**Data quality notes**
+
+- Party fields **PLT** and **DEF** are short text labels (often truncated). They are not full party rosters; numeric values mean “count of plaintiffs/defendants” rather than a name.
+- Person vs organization for textual parties uses **regex heuristics** on the label (see `party_regex.go`), not LLM classification in the default ingest path.
+- Code values (district, disposition, etc.) follow the FJC codebook; this dictionary documents KG mapping, not codebook semantics.
+
+---
+
+## Entity Types
+
+### `legal_case`
+
+One civil case in the IDB extract, identified by district, office, docket, and filing year.
+
+- **Subject name:** Human-readable label including `fjcidb_case_id`.
+- **Strong id:** `fjcidb_case_id` on the case subject.
+- **Resolver:** `NOT_MERGEABLE` — passive administrative case node.
+- **Timestamp:** Atomization time (microseconds) for the ingest pass.
+
+### `person`
+
+An individual named on the plaintiff or defendant side when the IDB field is **textual** (not digits-only) and classified as a person by regex rules.
+
+- **Subject name:** Normalized party display (trailing `, ET AL` removed from the raw field).
+- **Property:** `name` (normalized party label from PLT/DEF).
+- **Resolver:** `MERGEABLE` named entity; lawsuit-context snippet on the record (who sues whom; NOS phrase included).
+- **Examples:** `SHANKS`, `BECERRA`, `BIDEN` (with or without `, ET AL`).
+
+### `organization`
+
+An institution or collective named on the plaintiff or defendant side when the field is textual and classified as organization (regex), or when classification is ambiguous and defaults to organization.
+
+- **Subject name:** Same normalization as person parties.
+- **Property:** `name` (normalized party label from PLT/DEF).
+- **Resolver:** `MERGEABLE` named entity; same lawsuit snippet pattern as person parties.
+- **Examples:** `DEPARTMENT OF DEFENSE`, `CUMMINS INC.`, `INTERNATIONAL UNION OF , ET AL`.
+
+### `nature_of_suit`
+
+A federal civil **nature of suit (NOS)** code from the U.S. Courts classification, linked from the case’s **NOS** field.
+
+- **Subject name:** Short title when known, e.g. `Employment`; otherwise `Nature of suit {code} (federal civil)`.
+- **Strong id:** `nos_code`.
+- **Resolver:** `NOT_MERGEABLE`.
+- **Reference:** U.S. Courts civil NOS code descriptions PDF (titles/descriptions embedded in ingest).
+
+---
+
+## Properties
+
+### Legal case
+
+* `fjcidb_case_id`
+  * Definition: Stable case identifier for this IDB row.
+  * Examples: `3-1-12345-2025`, `90-1-2303817-2023`
+  * Derivation: `{DISTRICT}-{OFFICE}-{DOCKET}-{year}` where year comes from `FILEDATE`, or from `FDATEUSE` when `FILEDATE` is absent. Row omitted if year cannot be determined.
+
+* `district_code`
+  * Definition: FJC district court code (`DISTRICT`).
+  * Examples: `3`, `90`
+  * Derivation: SAS `DISTRICT`.
+
+* `office_code`
+  * Definition: FJC office within the district (`OFFICE`).
+  * Examples: `1`
+  * Derivation: SAS `OFFICE`.
+
+* `case_docket_number`
+  * Definition: Court docket number (`DOCKET`).
+  * Examples: `12345`, `2303817`
+  * Derivation: SAS `DOCKET`.
+
+* `case_filing_date`
+  * Definition: Filing date as stored in the extract.
+  * Derivation: SAS `FILEDATE`.
+
+* `termination_date`
+  * Definition: Termination date when present.
+  * Derivation: SAS `TERMDATE`.
+
+* `origin_code`, `jurisdiction_code`, `disposition_code`, `class_action_code`, `procedural_progress_code`
+  * Definition: FJC codebook fields for procedural status.
+  * Derivation: SAS `ORIGIN`, `JURIS`, `DISP`, `CLASSACT`, `PROCPROG` when non-empty.
+
+### Person and organization (shared)
+
+* `name`
+  * Definition: Normalized party label from PLT or DEF.
+  * Examples: `SHANKS`, `INTERNATIONAL UNION OF`
+  * Derivation: Trim and remove trailing `, ET AL` from the raw IDB field; matches the record subject name.
+
+### Nature of suit
+
+* `nos_code`
+  * Definition: Numeric NOS code from the case row.
+  * Examples: `110`, `442`
+  * Derivation: SAS `NOS`.
+
+* `nos_title`
+  * Definition: Short title from the U.S. Courts NOS codebook.
+  * Examples: `Insurance`, `Employment`
+  * Derivation: Lookup table when code is known; omitted if unknown.
+
+* `nos_description`
+  * Definition: Long description from the same codebook.
+  * Derivation: Lookup table when code is known; omitted if unknown.
+
+---
+
+## Entity Relationships
+
+```
+legal_case  ──[has_nature_of_suit]──→  nature_of_suit
+
+person       ──[is_plaintiff_in]────→  legal_case
+organization ──[is_plaintiff_in]────→  legal_case
+
+person       ──[is_defendant_in]────→  legal_case
+organization ──[is_defendant_in]────→  legal_case
+```
+
+- **`is_plaintiff_in` / `is_defendant_in`:** Emitted on the **party** record; target atom points at the case entity (with case strong id on the target for graph linkage). Only for non-empty, non-numeric, non-`SEALED` PLT/DEF values.
+- **`has_nature_of_suit`:** Emitted on the **case** record when `NOS` is present; target is the `nature_of_suit` entity for that code.
+
+---
+
+## Records Per Case
+
+Typical atomization for one row with textual PLT and DEF, and a NOS code:
+
+1. One `legal_case` record (case properties + `has_nature_of_suit` target).
+2. One `nature_of_suit` record (when NOS present).
+3. Up to two party records (`person` or `organization` per side).
+
+Rows with only numeric PLT/DEF produce a case record with count properties only (no party entities). `SEALED` parties produce no party entities.
+
+---
+
+## Party labeling (person vs organization)
+
+Textual PLT/DEF labels are classified before flavor assignment:
+
+1. **Skip** — empty, all digits, or withheld (`SEALED`).
+2. **Organization** — label matches org indicators (legal suffixes, government words, `OF`/`AND`/`THE`, commas, truncated org stems) or has **three or more** name tokens after normalization.
+3. **Person** — one or two tokens that look like personal name parts (letters, hyphen, apostrophe).
+4. **Default** — organization.
+
+Consumers should treat regex labels as heuristic, especially on truncated government and corporate strings.
+
+---
+
+## Citations
+
+Citation text on atoms and entities: `Federal Judicial Center Integrated Database, civil SAS extract` with link to the FJC IDB research page. NOS entities additionally cite the U.S. Courts NOS descriptions document.
+
+---
+
+## Validation
+
+- **Unit fixture:** `testdata/sample_fjcidb_case.pb.txt` (SHANKS vs International Union, NOS 442) — regenerate via `./run_legal_test.sh` at repo root.
+- **recordeval:** Same script runs schema validation on `testdata/*.pb.txt`.

package/skill/fjcidb/schema.yaml

@@ -0,0 +1,206 @@
+# Dataset schema for FJC Integrated Database — U.S. district court civil cases (SAS extracts).
+#
+# Source: https://www.fjc.gov/research/idb/civil-cases-filed-terminated-and-pending-sy-1988-present
+# Codebook: Civil Codebook 1988 Forward (FJC PDF).
+#
+# Default ingest target is the FY civil SAS file (e.g. cv26.sas7bdat), refreshed by FJC on a schedule.
+name: "fjcidb"
+description: "Federal Judicial Center Integrated Database civil case records for U.S. district courts, including office and docket identity, party labels (paintif/defendant), filing and termination timing, jurisdiction, nature-of-suit entities linked from each case, and disposition codes"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "legal_case"
+    description: "A civil case docketed in a U.S. federal district court, identified by FJC administrative codes rather than PACER"
+    display_name: "Legal case"
+    mergeability: not_mergeable
+    strong_id_properties: ["fjcidb_case_id"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: mergeable
+    passive: true
+
+  - name: "person"
+    description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure"
+    display_name: "Person"
+    mergeability: mergeable
+    passive: true
+
+  - name: "nature_of_suit"
+    description: "Federal civil nature-of-suit (NOS) code from the U.S. Courts classification"
+    display_name: "Nature of suit"
+    mergeability: not_mergeable
+    strong_id_properties: ["nos_code"]
+    passive: true
+
+properties:
+  - name: "fjcidb_case_id"
+    namespace: "fjcidb"
+    type: string
+    description: "Stable FJC civil case identifier formed from district, office, docket, and filing year"
+    display_name: "FJC civil case ID"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "name"
+    namespace: "fjcidb"
+    type: string
+    description: "Display name of the entity"
+    display_name: "Name"
+    mergeability: not_mergeable
+    domain_flavors: ["organization", "person"]
+    passive: true
+
+  - name: "nos_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Nature of suit numeric code (matches IDB NOS and the U.S. Courts civil NOS codebook)"
+    display_name: "NOS code"
+    mergeability: not_mergeable
+    domain_flavors: ["nature_of_suit"]
+    passive: true
+
+  - name: "nos_title"
+    namespace: "fjcidb"
+    type: string
+    description: "Short title for this nature of suit code from the U.S. Courts civil NOS descriptions"
+    display_name: "Nature of suit title"
+    mergeability: not_mergeable
+    domain_flavors: ["nature_of_suit"]
+    passive: true
+
+  - name: "nos_description"
+    namespace: "fjcidb"
+    type: string
+    description: "Official description for this nature of suit code from the U.S. Courts civil NOS descriptions"
+    display_name: "Nature of suit description"
+    mergeability: not_mergeable
+    domain_flavors: ["nature_of_suit"]
+    passive: true
+
+  - name: "district_code"
+    namespace: "fjcidb"
+    type: string
+    description: "FJC district court code for where the civil action was filed (IDB DISTRICT)"
+    display_name: "FJC district code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "office_code"
+    namespace: "fjcidb"
+    type: string
+    description: "FJC office code within the district where the case was filed (IDB OFFICE)"
+    display_name: "FJC office code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "case_docket_number"
+    namespace: "fjcidb"
+    type: string
+    description: "Docket number assigned by the filing office (IDB DOCKET)"
+    display_name: "Docket number"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "case_filing_date"
+    namespace: "fjcidb"
+    type: string
+    description: "Case filing date"
+    display_name: "Filing date"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "termination_date"
+    namespace: "fjcidb"
+    type: string
+    description: "Termination date if the case terminated in the reporting window"
+    display_name: "Termination date"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "origin_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Procedural origin code for the filing"
+    display_name: "Origin code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "jurisdiction_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Jurisdiction code"
+    display_name: "Jurisdiction code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "disposition_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Disposition code when the case terminated"
+    display_name: "Disposition code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "class_action_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Class action designation code"
+    display_name: "Class action code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+  - name: "procedural_progress_code"
+    namespace: "fjcidb"
+    type: string
+    description: "Procedural progress code"
+    display_name: "Procedural progress code"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    passive: true
+
+relationships:
+  - name: "is_plaintiff_in"
+    namespace: "fjcidb"
+    description: "The party is named as the plaintiff side in this FJC civil case"
+    display_name: "Is plaintiff in"
+    mergeability: not_mergeable
+    domain_flavors: ["organization", "person"]
+    target_flavors: ["legal_case"]
+    passive: true
+
+  - name: "is_defendant_in"
+    namespace: "fjcidb"
+    description: "The party is named as the defendant side in this FJC civil case"
+    display_name: "Is defendant in"
+    mergeability: not_mergeable
+    domain_flavors: ["organization", "person"]
+    target_flavors: ["legal_case"]
+    passive: true
+
+  - name: "has_nature_of_suit"
+    namespace: "fjcidb"
+    description: "The civil case is classified under this federal nature-of-suit code (IDB NOS field)"
+    display_name: "Has nature of suit"
+    mergeability: not_mergeable
+    domain_flavors: ["legal_case"]
+    target_flavors: ["nature_of_suit"]
+    passive: true