flyersworder
diff --git a/‎CHANGELOG.md‎
Lines changed: 42 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 42 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 75 additions & 5 deletions b/‎README.md‎
Lines changed: 75 additions & 5 deletions
@@ -2,6 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.42.0] - 2026-08-16
+
+### Added
+
+- **`OssieSource` — read semantics from an Apache Ossie (incubating) model.** [Apache Ossie](https://ossie.apache.org/), formerly Open Semantic Interchange, is the vendor-neutral spec for exchanging semantic models across analytics, AI, and BI platforms; it entered the Apache Incubator with 50+ participating organizations behind it. Declare it like any other source:
+
+  ```yaml
+  semantic:
+    source:
+      type: ossie
+      path: "./semantic/model.yml"
+  ```
+
+  The strategic read is that Ossie standardises what a metric *is*, while this library enforces what an agent may *do* with it. Nothing in the spec or its roadmap validates a generated query against a policy — their `validation/` checks models against the JSON Schema, and the planned reference engine *compiles* semantic queries into SQL. So Ossie is a fourth input to `SemanticSource`, not a competitor to the enforcement layer, and the protocol was built for exactly this.
+
+  Four decisions define the adapter, each one a place where the easy choice is a silent correctness bug:
+
+  - **Table keys drop the database qualifier.** Ossie sources are `database.schema.table`; our keys are two-part because `Relationship` endpoints are `schema.table.column` and `build_relationship_index` recovers the table with a single `rsplit`. A three-part key would make every endpoint four deep. Collisions are logged; query-backed datasets register no table.
+  - **Cardinality is derived from both sides.** Ossie never writes the join type down — it is implicit in the keys. The spec documents `to` as the one side, but nothing validates it, and trusting it is not free: `RelationshipChecker._check_fan_out` fires only on `one_to_many`, so reading a backwards-declared join as `one_to_one` silently disables the row-multiplication warning on an aggregate. The type is read off `(from_columns are a key, to_columns are a key)`. Keys are optional in Ossie and their absence is not evidence of fan-out, so when the `to` dataset declares no keys at all the spec's declaration stands — otherwise every key-less model would flood the checker with false positives.
+  - **Composite joins are skipped, not split.** Ossie carries parallel `from_columns`/`to_columns` lists; our `Relationship` has single-column endpoints. One edge per column pair would assert two joins that are each individually wrong, and the join planner walks those edges. The skip is logged with the relationship's name, matching the precedent `CubeSource` set for Cube's `AND`-chained joins.
+  - **Dialect is an opaque string.** Resolution is deterministic as the spec requires — caller's choice, then `ANSI_SQL`, then `Ossie_SQL_2026`, then the first declared entry — but never validated against the enum. The accepted expression-language proposal adds `Ossie_SQL_2026` and makes it the default, so a closed check would break on the next spec bump for no benefit.
+
+- **Governance vocabulary round-trips through Ossie's `custom_extensions`.** Ownership, review dates, tiers, domains, `decompositions`, `drill_by`, and the metric-impact graph have no home in the Ossie spec — every `$def` in `osi-schema.json` sets `additionalProperties: false`, so they cannot be smuggled in as extra keys. They ride in the spec's own escape hatch under the `AGENTIC_DATA_CONTRACTS` vendor name, whose `data` is a JSON *string* per the spec. Restored `decompositions` / `drill_by` pass through the same `validate_decompositions` / `validate_drill_by` as `YamlSource`, so a bad identity still fails loudly at load.
+
+  This makes `OssieSource` the second source after `YamlSource` to populate `business_owner` / `operational_owner` / `last_reviewed` and `decompositions` / `drill_by`; dbt and Cube still leave them unset.
+
+- **`ai_context` and foreign vendor blocks are carried, not interpreted.** Every `ai_context` in the model (Ossie's AI-grounding channel — instructions, synonyms, example questions, in either its string or object form) reaches `get_extras()["ossie_ai_context"]`, and every non-`AGENTIC_DATA_CONTRACTS` vendor block reaches `get_extras()["ossie_custom_extensions"]`. This is the boundary `YamlSource.get_extras` already draws: the framework carries extras and, on request, places them in the prompt, but never interprets, validates, indexes, or computes over them. In particular `search_metrics` still matches on name and description only — Ossie synonyms do not silently change retrieval.
+
+  A foreign vendor's malformed JSON payload is carried verbatim and logged rather than raised on. Another vendor's typo must not stop this library from enforcing a contract.
+
+  Both sections are keyed by **semantic-model name first**. Ossie's top level is a list and it namespaces entity names per model, so a file with two models — each declaring a `customer` dataset, or each carrying a block from the same vendor — would otherwise silently lose the first. Both are omitted entirely when empty rather than emitted as `{}`: extras ride into the contract's inline snapshot and its canonical bytes, so an always-present empty dict would add a noise key to every Ossie contract's digest and would trip a contract declaring `expected_extras` on rehydrate.
+
+- **`expected_extras` on a non-`yaml` source now warns instead of being silently dropped.** The policy is threaded only into `YamlSource`. An Ossie source *does* produce extras, so declaring it there looks like it should work; without a warning the author believes strict mode is on, and the mismatch surfaces much later as a load failure on a frozen contract.
+
+### Changed
+
+- **Shared parser helpers promoted to `semantic/base.py`.** `_normalize_extras` / `_jsonify` became `jsonify_extras`. Extras ride into `contract_canonical_bytes` through `json.dumps`, so every source that carries them needs the same date coercion and JSON-safety check — a YAML-native date inside an Ossie `ai_context` would otherwise reach a published ARD attestation unconverted. The error now names the parser that raised it.
+
+- **`_parse_date` became `parse_review_date`.** Two sources now parse review dates, and the helper's whole reason for existing is a trap worth stating once: `datetime` must be checked before `date` because it subclasses it, or downstream `date - datetime` staleness arithmetic raises `TypeError`. A second copy would have been a second chance to get that ordering wrong. It sits alongside the other shared helpers (`build_relationship_index`, `fuzzy_search_metrics`, the validators) rather than being reached into privately from a sibling module.
+
+- **All locked dependencies upgraded.** Notably `sqlglot` 30.14.0 → 30.17.0 (Layer 1 static analysis), `pydantic-ai-slim` 2.22.0 → 2.31.0, `starlette` 1.3.1 → 1.6.0, and `xxhash` 3.8.1 → 4.0.0. The pinned `contract_digest` guard in `tests/test_ard/test_catalog_entry.py` still holds, so published contract bytes and every existing ARD attestation are unaffected.
+
 ## [0.41.1] - 2026-08-11
 
 ### Fixed
 
@@ -19,7 +19,7 @@ You teach agents your business domains, metrics, and governance rules upfront
 - **Resource governance built in** — per-session cost, retry, row, and token budgets, and wall-clock limits.
 - **Per-caller row/column security** — allow/deny tables and filter values by principal, for multi-user bots.
 - **Framework-agnostic** — plain-function tools for the Claude Agent SDK, LangChain/deepagents, Pydantic AI, or no framework at all.
-- **Bring your own semantics** — read metrics from dbt, Cube, or inline YAML.
+- **Bring your own semantics** — read metrics from dbt, Cube, Apache Ossie, or inline YAML.
 
 ### Without a contract vs. with one
 
@@ -652,9 +652,9 @@ tables:
         type: VARCHAR
 ```
 
-`tier`, `indicator_kind`, and `domains` are all optional. For dbt and Cube sources, these fields live under the metric's `meta:` block and are read through the same field names.
+`tier`, `indicator_kind`, and `domains` are all optional. For dbt and Cube sources, these fields live under the metric's `meta:` block and are read through the same field names. For Ossie, they live in the model's `custom_extensions` block (see [Apache Ossie](#apache-ossie) below).
 
-**Ownership & review cadence (optional).** `business_owner` / `operational_owner` (always *teams*, not individuals — owners outlive any one person) and `last_reviewed` declare who owns a metric's definition vs. its data health, and when it was last vetted. `last_reviewed` feeds `DataContract.find_stale()` (see [Governance Staleness](docs/architecture.md#governance-staleness)) and surfaces in `lookup_metric` / `lookup_domain` as a `stale` flag so the agent can disclose drift at query time. The same three fields are accepted on a `domain`. They are read from the **YAML source** today; dbt/Cube metrics default to unset.
+**Ownership & review cadence (optional).** `business_owner` / `operational_owner` (always *teams*, not individuals — owners outlive any one person) and `last_reviewed` declare who owns a metric's definition vs. its data health, and when it was last vetted. `last_reviewed` feeds `DataContract.find_stale()` (see [Governance Staleness](docs/architecture.md#governance-staleness)) and surfaces in `lookup_metric` / `lookup_domain` as a `stale` flag so the agent can disclose drift at query time. The same three fields are accepted on a `domain`. They are read from the **YAML source** and from an **Ossie** model's `custom_extensions` block; dbt/Cube metrics default to unset.
 
 **dbt** — point to a `manifest.json`:
 ```yaml
@@ -709,6 +709,76 @@ cubes:
 
 Joins whose SQL doesn't match the single-equality pattern (composite keys with `AND`-chained equalities) or whose target cube can't be resolved by name are skipped silently — fall back to declaring those in your contract YAML via `YamlSource`.
 
+### Apache Ossie
+
+[Apache Ossie (incubating)](https://ossie.apache.org/) — formerly Open Semantic Interchange — is the vendor-neutral spec for exchanging semantic models across analytics, AI, and BI tools. Point at a model file:
+
+```yaml
+semantic:
+  source:
+    type: ossie
+    path: "./semantic/model.yml"
+```
+
+Ossie standardises what a metric *is*; this library enforces what an agent may *do* with it. So the spec is a strict subset of the vocabulary here — an Ossie `Metric` carries only `name`, `expression`, `description`, `datatype`, and `ai_context`.
+
+| Ossie | Read as |
+| --- | --- |
+| `datasets[].source` + `fields[]` | Table schemas. A three-part `database.schema.table` is keyed on its trailing `schema.table`; a query-backed dataset registers no table |
+| `metrics[].expression.dialects[]` | `sql_expression`, resolved deterministically — your `dialect=` first, then `ANSI_SQL`, then `Ossie_SQL_2026`, then the first declared entry |
+| `relationships[]` | `Relationship`, with cardinality *derived from both sides* — see below |
+| `ai_context` (anywhere) | Carried into `get_extras()["ossie_ai_context"]`, keyed by model then entity kind, never interpreted |
+| `custom_extensions[]` | Ours read as real vocabulary; every other vendor's carried into `get_extras()["ossie_custom_extensions"]`, keyed by model then vendor |
+
+**Cardinality.** Ossie never writes the join type down; it is implied by which endpoints are keys. The spec documents `to` as the one side, but nothing validates that — and trusting it is not free, because `RelationshipChecker` fires its fan-out warning only on `one_to_many`. So both sides are checked:
+
+| `from_columns` a key | `to_columns` a key | Type |
+| --- | --- | --- |
+| ✓ | ✓ | `one_to_one` |
+| ✗ | ✓ | `many_to_one` |
+| ✓ | ✗ | `one_to_many` |
+| ✗ | ✗ | `many_to_many` |
+
+Keys are optional in Ossie, and their absence is not evidence of fan-out — when the `to` dataset declares no keys at all, the spec's declaration stands and the join reads as `many_to_one`.
+
+Composite-key relationships are **skipped with a warning** rather than split into one edge per column pair — our `Relationship` has single-column endpoints, and splitting would assert two joins that are each individually wrong. Declare those in a `YamlSource` overlay.
+
+**Governance fields.** Ownership, review dates, tiers, decompositions, and the metric-impact graph have no home in the Ossie spec, and every `$def` in its JSON Schema sets `additionalProperties: false` — so they cannot be added as extra keys. They ride in the spec's own escape hatch, `custom_extensions`, under this project's vendor name:
+
+```yaml
+    custom_extensions:
+      - vendor_name: AGENTIC_DATA_CONTRACTS
+        data: |
+          {
+            "metrics": {
+              "total_sales": {
+                "business_owner": "revenue-analytics",
+                "operational_owner": "data-platform",
+                "last_reviewed": "2026-05-01",
+                "tier": ["gold"],
+                "domains": ["sales"],
+                "decompositions": [
+                  {"operator": "sum", "operands": ["total_profit", "total_cost"]}
+                ],
+                "drill_by": [
+                  {"dimension": "region", "column": "public.customer.c_region"}
+                ]
+              }
+            },
+            "metric_impacts": [
+              {"from": "total_cost", "to": "total_profit",
+               "direction": "negative", "confidence": "verified",
+               "evidence": "Margin bridge reconciled 2026-Q1."}
+            ]
+          }
+```
+
+Ossie stores extension payloads as a JSON *string*, so `data` is JSON nested inside YAML (a plain YAML mapping is accepted too). Restored decompositions and `drill_by` go through the same validators as `YamlSource`, failing loudly at load, and a bare `"tier": "gold"` is promoted to a list exactly as `YamlSource` does. Another vendor's malformed payload is carried verbatim and logged rather than raised on — a neighbour's typo must not stop your contract from being enforced.
+
+`expected_extras` does not apply to an Ossie source: its extras are synthesized by the parser under fixed keys, not authored as free top-level sections. Declaring it on a non-`yaml` source logs a warning rather than being silently dropped.
+
+> The spec is at `0.2.0.dev0` with no tagged releases yet, so expect churn. `dialect` is deliberately treated as an opaque string and never validated against the enum, since the accepted expression-language proposal adds `Ossie_SQL_2026` and makes it the default.
+
 ## Table Relationships
 
 Define join paths so the agent knows how to combine tables correctly:
@@ -849,7 +919,7 @@ await trace.callable({
 #                      "kind": "identity", "operator": "product"}
 ```
 
-Today `decompositions` / `drill_by` are declared directly in YAML contracts; dbt/Cube extraction and a variance-diagnosis tool are deferred.
+Today `decompositions` / `drill_by` are declared directly in YAML contracts or in an Ossie model's `custom_extensions`; dbt/Cube extraction and a variance-diagnosis tool are deferred.
 
 ## Validating a verified-examples corpus
 
@@ -1205,7 +1275,7 @@ DATA_PLUGIN_PATH=/tmp/kwp/data \
 
 **Does it execute my SQL?** Only `run_query` does, and only after validation passes (plus an optional EXPLAIN dry-run). `inspect_query` validates without executing, and forbidden operations (DELETE/DROP/UPDATE/…) are blocked before they ever reach the database.
 
-**Do I have to use dbt or Cube?** No. Author metrics inline in a `semantic.yml` with `YamlSource`. dbt (`manifest.json`) and Cube are supported if you already have them — the agent-facing behavior is identical regardless of source.
+**Do I have to use dbt or Cube?** No. Author metrics inline in a `semantic.yml` with `YamlSource`. dbt (`manifest.json`), Cube, and Apache Ossie are supported if you already have them — the agent-facing behavior is identical regardless of source.
 
 **Does it work without the Claude Agent SDK?** Yes. The tools are plain async functions usable from LangChain/deepagents, Pydantic AI, or directly; the example agents fall back to a no-SDK demo mode.