feat(ontology): promote O*NET occupation-rating stack onto main

ARCHITECTURE.md

@@ -86,7 +86,9 @@ flowchart LR
 | `commitment_extraction.py` | Pluggable LLM derivation of a customer commitment (promise + deadline) from a post; `Null` default, `ContextualOrchestrator` real impl |
 | `temporal_expressions.py` | Pure Korean relative-time resolver for Global Ask (ADR 0150) |
 | `ask_time_axis.py` | Event-time vs ingestion-time clock choice for that window (ADR 0202) |
-| `ontology.py` | Loads `docs/ontology/lineageweave-kg.ttl`, the formal OWL 2/RDFS/SKOS vocabulary for the Knowledge Graph's node/edge types (ADR 0004) |
+| `ontology.py` | Loads the governed Turtle source tree (`lineageweave-kg.ttl` plus generated fragments), the formal OWL 2/RDFS/SKOS vocabulary for the Knowledge Graph's node/edge types, source taxonomies, and published O*NET linkages (ADR 0004, ADR 0252, ADR 0255, ADR 0256) |
+| `backend/app/occupation_rating_ingestion.py` | Projects authenticated occupation-rating evidence plus persisted source and represented-occupation catalogs (ADR 0258, ADR 0260, ADR 0261) |
+| `frontend/src/components/OccupationRatingProfile.tsx` | Selects an imported source, filters stored occupation titles without ranking, and reads exact Dashboard evidence while preserving absence, uncertainty, and warning semantics (ADR 0259–0262) |
 | `ontology_neighborhood.py` | Bounded typed ontology/provenance neighborhood (ADR 0184); PostgreSQL stays authoritative, OWL subclass is not an instance edge |
 | `ontology_source_cursor.py` | Opaque HMAC source-window continuation (ADR 0124); keyset pagination, never OFFSET |
 | `period_report.py` | Fit GRM/GPCM on persisted IRT rows, FIPC-select, EAP-score a period (ADR 0003 slice 3; Bock & Mislevy, 1982) |
@@ -679,7 +681,8 @@ vocabulary (`node_type`, `edge_type`, `entity_relationship_type`,
 `person_side`, `corporate_entity_level`) actually matches what the
 Ontology/Semantic-Layer claim implies.
 
-`docs/ontology/lineageweave-kg.ttl` is a real OWL 2 / RDFS / SKOS
+`docs/ontology/lineageweave-kg.ttl` and its deterministic governed fragments
+are a real OWL 2 / RDFS / SKOS
 ontology in Turtle syntax: classes for `Post`/`Person`/`CorporateEntity`
 (with `OurSidePerson`/`CounterpartyPerson` subclasses), object
 properties for each `edge_type_code` and `entity_relationship_type`
@@ -693,7 +696,7 @@ specification over it, in the same sense W3C's own stack uses "semantic
 layer" (RDFS/OWL as the governed conceptual layer over raw data), not a
 separate BI-metrics product and not a parallel triple store.
 
-`lineageweave/ontology.py` parses the Turtle file once with `rdflib`
+`lineageweave/ontology.py` parses the Turtle source tree once with `rdflib`
 (pure Python, no Rust toolchain, unlike `fast-mlsirm`) and exposes the
 vocabulary as importable IRI constants, so application code has one
 canonical name per class/property instead of re-typing lookup codes as
@@ -710,6 +713,19 @@ enforcement mechanism: a future PR that adds a new `edge_type` or
 `entity_relationship_type` code without updating the ontology fails
 this test, not just a docstring's word.
 
+### Authorized job architecture snapshots
+
+The public SOC/O*NET vocabulary and an employer's job architecture remain
+different graphs. ADR 0263 adds an organization-scoped PostgreSQL source
+boundary for private job-family/job-series snapshots: immutable source
+metadata owns normalized nodes, source-declared broader/narrower edges, and
+optional explicit bindings to a versioned external occupation scheme. An edge
+table preserves multiple-family membership; the importer rejects cycles and
+never derives a parent or binding from a label or code pattern. The snapshot
+is source evidence only. It does not create a person, post, organizational
+unit, competency, score, weight, or ontology assertion, and runtime rows never
+enter repository artifacts.
+
 ## Phase 6c: post content normalization before any LLM/embedding call
 
 The brief's latest revision calls out, explicitly, that a post body mixing

CHANGELOG.d/2.21.0-occupation-catalog-filter.md

@@ -0,0 +1,5 @@
+### Added
+
+- Occupation evidence now filters the imported occupation catalog by published
+  title or retained code without ranking or typed SOC fallback, and fails closed
+  when the filter matches nothing (ADR 0262).

backend/app/main.py

@@ -30,7 +30,7 @@
 
 import asyncpg
 import redis.asyncio as redis
-from fastapi import Depends, FastAPI, HTTPException, Query, status
+from fastapi import Depends, FastAPI, HTTPException, Path, Query, status
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 
@@ -154,6 +154,11 @@
     fetch_post_evaluation,
     ingest_post_evaluation,
 )
+from backend.app.occupation_rating_ingestion import (
+    fetch_occupation_rating_sources,
+    fetch_occupation_ratings,
+    fetch_rating_source_occupations,
+)
 from backend.app.post_summary_ingestion import (
     fetch_persisted_summary,
     persist_post_summary,
@@ -2484,6 +2489,62 @@ async def read_worker_function_construct_catalog(
     return construct_catalog_payload()
 
 
+@app.get("/api/occupations/{onetsoc_code}/ratings")
+async def read_occupation_ratings(
+    onetsoc_code: str = Path(..., pattern=r"^[0-9]{2}-[0-9]{4}\.[0-9]{2}$"),
+    data_release_code: str = Query(
+        ..., min_length=1, max_length=63, pattern=r"^[a-z0-9][a-z0-9.-]*$"
+    ),
+    source_table_code: str = Query(
+        ..., min_length=1, max_length=63, pattern=r"^[a-z][a-z0-9_]*$"
+    ),
+    limit: int = Query(100, ge=1, le=500),
+    offset: int = Query(0, ge=0, le=10000),
+    _account: CurrentAccount = Depends(get_current_account),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, object]:
+    """Return one authenticated, provenance-bearing occupation source profile."""
+    async with pool.acquire() as conn:
+        return await fetch_occupation_ratings(
+            conn,
+            data_release_code=data_release_code,
+            source_table_code=source_table_code,
+            onetsoc_code=onetsoc_code,
+            limit=limit,
+            offset=offset,
+        )
+
+
+@app.get("/api/occupation-rating-sources")
+async def read_occupation_rating_sources(
+    _account: CurrentAccount = Depends(get_current_account),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, list[dict[str, object]]]:
+    """Return the authenticated catalog of imported occupation-rating sources."""
+    async with pool.acquire() as conn:
+        return await fetch_occupation_rating_sources(conn)
+
+
+@app.get("/api/occupation-rating-occupations")
+async def read_rating_source_occupations(
+    data_release_code: str = Query(
+        ..., min_length=1, max_length=63, pattern=r"^[a-z0-9][a-z0-9.-]*$"
+    ),
+    source_table_code: str = Query(
+        ..., min_length=1, max_length=63, pattern=r"^[a-z][a-z0-9_]*$"
+    ),
+    _account: CurrentAccount = Depends(get_current_account),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, object]:
+    """Return occupations represented in one imported rating source."""
+    async with pool.acquire() as conn:
+        return await fetch_rating_source_occupations(
+            conn,
+            data_release_code=data_release_code,
+            source_table_code=source_table_code,
+        )
+
+
 @app.get("/api/posts/{post_id}/counterparties")
 async def read_post_counterparties(
     post_id: str,

backend/app/occupation_rating_ingestion.py

@@ -0,0 +1,198 @@
+"""Read exact imported occupation ratings without deriving a score or weight."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Protocol
+
+
+class RatingReadConnection(Protocol):
+    """Small asyncpg-compatible surface used by the rating read projection."""
+
+    async def fetchrow(self, query: str, *args: object) -> Any:
+        """Return one row or ``None``."""
+
+    async def fetch(self, query: str, *args: object) -> list[Any]:
+        """Return ordered rows."""
+
+
+def _decimal_text(value: Decimal | None) -> str | None:
+    """Return the exact database decimal representation or honest absence."""
+    return str(value) if value is not None else None
+
+
+async def fetch_occupation_ratings(
+    conn: RatingReadConnection,
+    *,
+    data_release_code: str,
+    source_table_code: str,
+    onetsoc_code: str,
+    limit: int,
+    offset: int,
+) -> dict[str, object]:
+    """Return one bounded source profile and explicit artifact availability."""
+    source = await conn.fetchrow(
+        """select rating_source.source_table_name,
+                  rating_source.source_artifact_url,
+                  rating_source.source_artifact_sha256,
+                  rating_source.source_row_count,
+                  scale_source.source_artifact_url as scale_artifact_url,
+                  scale_source.source_artifact_sha256 as scale_artifact_sha256,
+                  scale_source.source_row_count as scale_source_row_count
+             from occupational_source_table rating_source
+             left join occupational_source_table scale_source
+               on scale_source.data_release_code = rating_source.data_release_code
+              and scale_source.source_table_code = 'scales_reference'
+            where rating_source.data_release_code = $1
+              and rating_source.source_table_code = $2""",
+        data_release_code,
+        source_table_code,
+    )
+    if source is None:
+        return {
+            "data_release_code": data_release_code,
+            "source_table_code": source_table_code,
+            "onetsoc_code": onetsoc_code,
+            "source_available": False,
+            "source": None,
+            "items": [],
+            "next_offset": None,
+        }
+    rows = await conn.fetch(
+        """select observation.element_id, element.element_name,
+                  observation.scale_id, scale.scale_name,
+                  scale.minimum_value, scale.maximum_value,
+                  observation.category_value, observation.data_value,
+                  observation.sample_size, observation.standard_error,
+                  observation.lower_ci_bound, observation.upper_ci_bound,
+                  observation.recommend_suppress, observation.not_relevant,
+                  observation.source_updated_month, observation.domain_source_code
+             from occupational_rating_observation observation
+             join occupational_element_definition element
+               on element.data_release_code = observation.data_release_code
+              and element.element_id = observation.element_id
+             join occupational_scale_definition scale
+               on scale.data_release_code = observation.data_release_code
+              and scale.scale_id = observation.scale_id
+            where observation.data_release_code = $1
+              and observation.source_table_code = $2
+              and observation.onetsoc_code = $3
+            order by observation.element_id, observation.scale_id,
+                     observation.category_value nulls first
+            limit $4 offset $5""",
+        data_release_code,
+        source_table_code,
+        onetsoc_code,
+        limit + 1,
+        offset,
+    )
+    page = rows[:limit]
+    items = [
+        {
+            "element_id": row["element_id"],
+            "element_name": row["element_name"],
+            "scale_id": row["scale_id"],
+            "scale_name": row["scale_name"],
+            "minimum_value": _decimal_text(row["minimum_value"]),
+            "maximum_value": _decimal_text(row["maximum_value"]),
+            "category_value": row["category_value"],
+            "data_value": _decimal_text(row["data_value"]),
+            "sample_size": row["sample_size"],
+            "standard_error": _decimal_text(row["standard_error"]),
+            "lower_ci_bound": _decimal_text(row["lower_ci_bound"]),
+            "upper_ci_bound": _decimal_text(row["upper_ci_bound"]),
+            "recommend_suppress": row["recommend_suppress"],
+            "not_relevant": row["not_relevant"],
+            "source_updated_month": row["source_updated_month"],
+            "domain_source_code": row["domain_source_code"],
+        }
+        for row in page
+    ]
+    return {
+        "data_release_code": data_release_code,
+        "source_table_code": source_table_code,
+        "onetsoc_code": onetsoc_code,
+        "source_available": True,
+        "source": {
+            "source_table_name": source["source_table_name"],
+            "source_artifact_url": source["source_artifact_url"],
+            "source_artifact_sha256": source["source_artifact_sha256"],
+            "source_row_count": source["source_row_count"],
+            "scale_artifact_url": source["scale_artifact_url"],
+            "scale_artifact_sha256": source["scale_artifact_sha256"],
+            "scale_source_row_count": source["scale_source_row_count"],
+        },
+        "items": items,
+        "next_offset": offset + limit if len(rows) > limit else None,
+    }
+
+
+async def fetch_occupation_rating_sources(
+    conn: RatingReadConnection,
+) -> dict[str, list[dict[str, object]]]:
+    """Return imported rating artifacts that contain at least one observation."""
+    rows = await conn.fetch(
+        """select source.data_release_code, release.release_version,
+                  release.source_publisher_name, release.source_license_url,
+                  source.source_table_code, source.source_table_name,
+                  source.source_artifact_url, source.source_artifact_sha256,
+                  source.source_row_count
+             from occupational_source_table source
+             join occupational_data_release release
+               on release.data_release_code = source.data_release_code
+            where source.source_table_code <> 'scales_reference'
+              and exists (
+                    select 1
+                      from occupational_rating_observation observation
+                     where observation.data_release_code = source.data_release_code
+                       and observation.source_table_code = source.source_table_code
+              )
+            order by release.imported_at desc, source.data_release_code,
+                     source.source_table_name, source.source_table_code"""
+    )
+    return {"sources": [dict(row) for row in rows]}
+
+
+async def fetch_rating_source_occupations(
+    conn: RatingReadConnection,
+    *,
+    data_release_code: str,
+    source_table_code: str,
+) -> dict[str, object]:
+    """Return occupations with observations in one exact imported source."""
+    source = await conn.fetchrow(
+        """select 1
+             from occupational_source_table
+            where data_release_code = $1 and source_table_code = $2""",
+        data_release_code,
+        source_table_code,
+    )
+    if source is None:
+        return {
+            "data_release_code": data_release_code,
+            "source_table_code": source_table_code,
+            "source_available": False,
+            "occupations": [],
+        }
+    rows = await conn.fetch(
+        """select classification.onetsoc_code, classification.occupation_title
+             from occupational_classification_entry classification
+            where classification.data_release_code = $1
+              and exists (
+                    select 1
+                      from occupational_rating_observation observation
+                     where observation.data_release_code = classification.data_release_code
+                       and observation.source_table_code = $2
+                       and observation.onetsoc_code = classification.onetsoc_code
+              )
+            order by classification.occupation_title,
+                     classification.onetsoc_code""",
+        data_release_code,
+        source_table_code,
+    )
+    return {
+        "data_release_code": data_release_code,
+        "source_table_code": source_table_code,
+        "source_available": True,
+        "occupations": [dict(row) for row in rows],
+    }

docs/adr/0159-published-ontology-pages.md

@@ -40,12 +40,17 @@ and consumer migration plan.
 3. Publish equivalent machine-readable artifacts beside the HTML:
    `ontology.ttl`, `ontology.jsonld`, `ontology.nt`, the PROV-O support profile,
    and a source-digest manifest.
-4. Preserve `lineageweave-kg.ttl` byte-for-byte as the published Turtle
-   artifact. JSON-LD and N-Triples are generated from a canonicalized RDF graph
-   and are tested for semantic isomorphism with the source.
+4. For a single governed Turtle source, preserve `lineageweave-kg.ttl`
+   byte-for-byte as the published Turtle artifact. When a later accepted ADR
+   adds governed fragments, publish the merged graph as deterministic canonical
+   RDF that parses as Turtle; test every machine format for semantic
+   isomorphism with the complete source graph. Never concatenate independent
+   Turtle documents because their prefix and base declarations have
+   document-local scope.
 5. Do not add a build timestamp. The same source tree must produce the same
-   artifact bytes. The manifest records the source SHA-256 and the complete
-   published ontology-directory inventory instead.
+   artifact bytes. The manifest records every governed source path and SHA-256,
+   the ordered source-tree SHA-256, and the complete published
+   ontology-directory inventory instead.
 6. Run publication through `scripts/publish_ontology_site.py`, a fail-closed
    boundary that rejects duplicate HTML fragments, non-HTTP(S) linked IRIs,
    symlink outputs, source-overlapping outputs, and replacement of directories

docs/adr/0245-io-occupational-taxonomy-in-the-published-ontology.md

@@ -3,6 +3,10 @@
 **Status:** Accepted
 **Date:** 2026-08-26
 **Extends:** [ADR 0004](0004-knowledge-graph-ontology.md), [ADR 0145](0145-psychometric-channel-weight-estimation.md), [ADR 0207](0207-repository-case-ontology-namespace-canonical.md), [ADR 0232](0232-worker-function-taxonomy-in-the-published-ontology.md)
+<<<<<<< HEAD
+=======
+**Superseded in part by:** [ADR 0252](0252-complete-2018-soc-hierarchy.md), which expands the major-group-only scheme into the complete 2018 SOC hierarchy.
+>>>>>>> origin/feat/onet-rating-occupation-filter
 
 ## Context