katalyst-forge 4.2.0__tar.gz → 5.2.0__tar.gz

katalyst_forge-5.2.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+site/
+node_modules/
+.pytest_cache/
+.ruff_cache/
+
+# RIC-733 consistency eval run exhaust (transient, not the checked-in baseline)
+docs/consistency-results.json
+.prompt-cache/
+
+# Deterministic tooling-gate run artifacts (kata-gate.sh runtime output).
+# Real telemetry per run; regenerated on every gate invocation, not committed.
+.global/taxonomy/delivery/agent_runs/tooling/
+
+# Generated orientation packet (RIC-731): produced at install time, not source
+orientation/packet.json
+
+# Machine-local orientation fallback config (RIC-731): holds an absolute packetPath,
+# written beside the installed contract; never source, never commit.
+orientation-config.json
+
+# bun.lock is the committed lockfile; npm's is not
+package-lock.json
+
+# Watchdog runtime state (RIC-1592): markers and ledger entries are produced at runtime
+# outside any repo, under KATALYST_WATCHDOG_STATE_DIR. Ignored so a stray write can never
+# pollute the working tree that RIC-1591 has to diff cleanly.
+.katalyst-watchdog/

katalyst_forge-5.2.0/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog — katalyst-forge
+
+All notable changes to the **katalyst-forge** bundle are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+As of 4.2.0 this package lives in its own repository
+(`esimplicityinc/katalyst-forge`) and tags use the plain `vX.Y.Z` prefix.
+Releases 4.1.0 and earlier were cut from the `katalyst-taxonomy` monorepo
+with `forge-vX.Y.Z` tags.
+
+The Forge **bundle `schema_version`** (declared in `bundle.py`) is the
+consumer-facing node-model contract and is versioned separately from this
+PyPI package version. A breaking node-type/model change bumps `schema_version`.
+
+---
+
+## [5.2.0] -- 2026-08-08
+
+### Added
+
+- **Cost observability as metrics-wing content** (RIC-1590). Run cost is modelled as `metric_definition` plus `signal_source` content rather than bespoke reporting code. Ships `src/katalyst_forge/metrics/` with a pure computation core (no I/O), a deny-by-default projection into `CanonicalSignalBatch`, `SignalProvider` / `PriceCatalogue` / `RoutingPolicy` protocols, lazily resolved providers for OpenCode and forge-model-router, a text dashboard, an HTML report, and the `cost-observability` template bundle with its global action and Just recipe. Metered and subscription-notional spend are kept apart by construction: `MetricResult` is keyed by billing mode and offers no total, and `__add__`, `__radd__` and `__float__` raise.
+- **Routing comparison policy** (RIC-1616). `routing-headroom` and `routing-savings-realized` can now produce a figure. The comparison models come from the environment (`FORGE_COST_ORCHESTRATOR_MODEL`, `FORGE_COST_TARGET_MODEL`, `FORGE_COST_TARGET_MODEL_<STAGE>`), so no model identifier is hard-coded in code or content. An unconfigured environment yields no policy, leaving the previous behaviour of absent figures rather than zeros.
+- **`optional_fields` on a signal source** (RIC-1617). A provider-synthesized value that may legitimately be absent, such as a Forge stage inferred from a session that is not a Forge stage, no longer discards the whole batch.
+- **Bundle content and non-ownership in the writer reference** (RIC-1621). `kata-tax-writer` now has schema entries for template-bundle content, and explicitly disclaims `tests/`, `src/`, `scripts/` and `.github/workflows/`.
+
+### Fixed
+
+- **The metered cost path never returned a record** (RIC-1615). The OpenCode adapter read its root sessions from a `query_config` key that only ever existed in a test fixture, so every real run walked an empty session list. Run identity is now an explicit argument on `SignalProvider.fetch`, interpreted per adapter.
+- **The session walk dropped spend it should have counted** (RIC-1615). It began at the root's children, so an orchestrator's own tokens went uncounted and a single-session run reported nothing, and it descended only one level even though the children endpoint returns direct children only. It now yields the root and every transitive descendant once each.
+- **Router telemetry was rejected outright** (RIC-1615). A real run writes `cost_usd` as a JSON number; decoding without `parse_float=Decimal` lost the exactness `parse_money` requires and aborted the dashboard.
+- **The price catalogue was built eagerly** (RIC-1615), demanding OpenCode credentials from users who only wanted router figures. It is now built on first price lookup.
+- **`routing-headroom` reported a fabricated zero** (RIC-1616) when no record had a resolvable comparison target. A rendered `$0.00` reads as routing already being optimal rather than as routing never having been measured, so it now yields no figure unless a comparison was made.
+- **One uncomputable metric aborted the whole report** (RIC-1616). `compute` is now isolated per metric, matching the per-source isolation already in place.
+- **The action schema documentation did not match the loader** (RIC-1619). `katalyst-action-builder` documented `kind: Action` on an unrecognised apiVersion with `spec.type`, `spec.timeoutSeconds` and `spec.tags`; following it produced zero actions and, for the kind and apiVersion errors, zero errors as well.
+- **The writer's Kind Mapping carried the same defect** (RIC-1621). `plugin-action` mapped to `kind: Action` on `katalyst.taxonomy.plugins.actions/v1alpha`, so the single writer would have produced action files that no loader reads.
+
+### Changed
+
+- CI now runs `ruff format --check` over `src`, `tests` and `scripts` (RIC-1620), with the pre-existing drift reformatted first so the gate did not turn open branches red.
+
+## [5.1.0] -- 2026-07-28
+
+- **Canonical ADR/NFR storage** (RIC-1358) — ADR and NFR definitions now declare flat identity-derived storage under `.global/taxonomy/design/adrs/` and `.global/taxonomy/design/nfrs/`. Forge agents, skills, templates, fixtures, and documentation use the plural directories; legacy multi-document examples are labeled explicitly.
+- Migrated the nine Forge-owned NFR artifacts from `design/nfr/` to `design/nfrs/` and added `NFR-010` to require executable storage consumers to resolve registry metadata instead of hard-coding artifact kinds or paths.
+
+## [5.0.0] -- 2026-07-22
+
+Bundle `schema_version` bumped to **5** and manifest version to **5.0** to reflect breaking relationship renames and parent-rule changes below.
+
+### Added
+
+- **`practice` node kind** in the Practices wing (RIC-1273). A bundle node that sits between `practice_area` and standards/methods/competencies/tools, enabling strict nesting: `practice_area` → `practice` → `{standard, method, competency, tool}`. Practices are assignable units that reference (do not own) standards and methods.
+- **`INCLUDES_PRACTICE` relationship** (`practice_area` → `practice`): grouping edge for the new strict nesting hierarchy.
+- **`PRESCRIBES_STANDARD` / `PRESCRIBES_METHOD` relationships** (`practice` → `standard` / `method`): practice prescribes which standards and methods it bundles.
+- **`ADHERES_TO_PRACTICE` / `ADHERES_TO_STANDARD` / `ADHERES_TO_METHOD` relationships**: assignment edges allowing consumer nodes (system, stack, layer, library, tool, organization, project, team) to declare which practices, standards, and methods they follow.
+- **Practice assignment fields** (`practices`, `standards`, `methods`) spliced into 8 consumer ("follower") node kinds via shared `_practice_refs.py` helper.
+- **`metric_definition`, `signal_source`, `threshold_profile` node kinds** in the new Metrics wing (RIC-1272). Brings the bundle to **36 node types across 8 wings**.
+
+### Changed
+
+- **BREAKING: `competency` re-parented from `practice_area` to `practice`** (RIC-1273). The `ParentRule.allowed_parent_kinds` changed from `{"practice_area"}` to `{"practice"}`. Any existing `competency` instances parented under a `practice_area` must be re-parented under a `practice` node. No known consuming taxonomies have competency instances.
+- **BREAKING: Relationship renames** (RIC-1273). The following relationship types were renamed for naming consistency (all edge families now use verb-first, actor-centric naming):
+  - `INCLUDES_METHOD` / `INCLUDES_STANDARD` → removed (replaced by `PRESCRIBES_STANDARD` / `PRESCRIBES_METHOD` on the new `practice` node)
+  - Assignment family unified: `FOLLOWS_PRACTICE` → `ADHERES_TO_PRACTICE`, `APPLIES_METHOD` → `ADHERES_TO_METHOD` (`ADHERES_TO_STANDARD` unchanged)
+- **`standard` and `method` relocated from Design wing to Practices wing** (RIC-1273). `nfr` is now a child of `standard`; `adr` is now a child of `method`. Design wing shrinks from 8 → 6 kinds; Practices wing grows from 4 → 9 kinds.
+
+### Migration
+
+Consuming taxonomies that reference the removed/renamed relationship types in cross-references or queries must update:
+
+| Old | New |
+|-----|-----|
+| `INCLUDES_METHOD` | `PRESCRIBES_METHOD` (on `practice`, not `practice_area`) |
+| `INCLUDES_STANDARD` | `PRESCRIBES_STANDARD` (on `practice`, not `practice_area`) |
+| `FOLLOWS_PRACTICE` | `ADHERES_TO_PRACTICE` |
+| `APPLIES_METHOD` | `ADHERES_TO_METHOD` |
+| `competency` parented under `practice_area` | Re-parent under `practice` |
+| `nfr` / `adr` in design wing | Now in practices wing (no YAML change needed; wing is metadata) |
+
+## [4.2.0] -- 2026-07-06
+
+Repo split (RIC-1070). First release from the standalone
+`esimplicityinc/katalyst-forge` repository, extracted from `katalyst-taxonomy`.
+No node-model changes; bundle `schema_version` stays **4**.
+
+### Added
+
+- Standalone repository: the Forge schema bundle, the 21 kata-forge agent
+  definitions and forge skills (extracted from `katalyst-taxonomy-agents`),
+  the creation/scaffold templates, the JSON Schemas, and the Forge lifecycle
+  docs now live and version together as one product.
+- JSON Schemas ship as package data in the wheel under `katalyst_forge/schemas/`.
+
+### Changed
+
+- Release tags drop the `forge-` prefix: this repo tags plain `vX.Y.Z`.
+- Docs move to https://esimplicityinc.github.io/katalyst-forge/.
+
+## [4.1.0] -- 2026-06-26
+
+Delivery-wing evolution (#138 / #140). Bundle `schema_version` stays **4** (additive within the v4 node-model); bundle node count 29 → 30.
+
+### Added
+
+- **`agent_run` node kind** (child of `work_item`): per-stage agent telemetry (`stages`, `totals`, `entered_status` / `exited_status`, `started` / `ended`) -- identifiers and counts only, no prompts or PII.
+- **`work_item.status` 10-state lifecycle enum** (`idea, proposed, accepted, planned, in_progress, blocked, delivered, validated, released, retired`), enforced through the engine's `FieldSpec.allowed_values`.
+- **Single `TRACES_TO` relationship** on `work_item`, disambiguated by the source field's target kind, covering `capabilities`, `user_needs`, `nfrs`, `adrs`, `design_specs`, `specifications`. Adding a new traceable target is a one-line field addition.
+- **`change_entry` -> `work_item` link** (`work_item_id` + `REFERENCES_WORK_ITEM`).
+
+### Changed
+
+- Minimum `katalyst-engine` raised to `>=4.1` -- the `work_item` status enum relies on `FieldSpec.allowed_values`, added in engine 4.1.0.
+- Replaced the per-target relationship definitions (`implements_capability`, `addresses_need`, `satisfies_nfr`) with the single `TRACES_TO` edge. `road_id` / `REFERENCES_ROAD_ITEM` on `change_entry` retained as a deprecated alias of `work_item_id`.
+
+## [4.0.0] -- 2026-06-16
+
+Bundle `schema_version` bumped to **4** and manifest version to **4.0** to reflect the breaking node-kind removals below.
+
+### Removed
+
+- **BREAKING: Relocated mechanism kinds out of the Forge bundle** (#79/#82). Six node kinds no longer ship in Forge: `template`, `action`, `template_overlay`, `dx`, `cicd_job_template`, and `cicd_workflow_template`. Scaffolding/CI-CD mechanisms are now provided by the taxonomy runtime and its plugins rather than declared as Forge node types. Documents using these kinds must migrate (`kata tax migrate`); `template_overlay` becomes `node_wiring`.
+
+### Added
+
+- **`design_spec` node type** in the Design wing (#44). A pre-executable specification artifact sitting between `user_need` and `specification` in the intent chain, capturing visual structure, interaction flows, and testable design constraints. Includes a `design_specs` field + `IMPLEMENTS_DESIGN` cross-reference on `specification`, and the `DESIGNS_FOR_NEED` / `DESIGNS_CAPABILITY` / `IMPLEMENTS_DESIGN` relationships. Brings the Forge bundle to **29 node types**.
+
+## [3.0.1] -- 2026-06-11
+
+### Changed
+- **Corrected bundle `schema_version` to `3`** to reflect the breaking `user_story` → `user_need` rename that shipped in 3.0.0. The `BundleManifest.version` was bumped to `3.0` and `SchemaDefinition.schema_version` to `3`.
+- First release published independently via the per-package `forge-v*` release pipeline.
+
+## [3.0.0] -- 2026-06-10
+
+### Changed
+- **BREAKING: Renamed `user_story` node type to `user_need`** in the Design wing. The kind (`user_story` → `user_need`), directory (`user_stories/` → `user_needs/`), display labels (`User Story`/`User Stories` → `User Need`/`User Needs`), and Neo4j label (`UserStory` → `UserNeed`) all changed. Creation template `user_story.yaml.j2` → `user_need.yaml.j2`. No backward-compatibility alias is provided. (RIC-616)
+
+### Added
+- **`katalyst-xbrl` bundle** companion node types and the pluggable parser registry landed in the same `3.0.0` release train (see root `CHANGELOG.md` for cross-package detail).
+
+---
+
+> Versions prior to 3.0.0 were released in lockstep with `katalyst-taxonomy`
+> under the umbrella `vX.Y.Z` tags. See the root `CHANGELOG.md` for that history.

{katalyst_forge-4.2.0 → katalyst_forge-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 4.2.0
+Version: 5.2.0
 Summary: Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)
 Author: eSimplicity
 License: Proprietary

{katalyst_forge-4.2.0 → katalyst_forge-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "4.2.0"
+version = "5.2.0"
 description = "Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"
@@ -66,6 +66,11 @@ dev = [
     # test_wing_schemas.py validates the shipped JSON Schemas
     "jsonschema>=4.22",
     "referencing>=0.35",
+    # test_validate_templates_gates.py loads scripts/validate-templates.py, which
+    # imports these. CI's templates-validate job installs them ad hoc; the pytest
+    # job needs them in its own environment to exercise the gate logic.
+    "pyyaml>=6",
+    "jinja2>=3.1",
 ]
 
 [tool.ruff]

{katalyst_forge-4.2.0 → katalyst_forge-5.2.0}/schemas/nodes/organizational.schema.json

@@ -96,6 +96,10 @@
               "type": "string",
               "minLength": 1,
               "description": "Human-readable display name for the competency (e.g. 'Kubernetes Administration')."
+            },
+            "competency_type": {
+              "type": "string",
+              "description": "Optional free-form kind of competency: practice, system, or tools. No allowed_values enum is enforced."
             }
           }
         }

{katalyst_forge-4.2.0 → katalyst_forge-5.2.0}/src/katalyst_forge/__init__.py

@@ -1,6 +1,6 @@
 """katalyst-forge — The Forge bundle for katalyst-engine.
 
-Provides 33 node-type definitions across 8 wings for software delivery taxonomy.
+Provides 36 node-type definitions across 8 wings for software delivery taxonomy.
 """
 
 from __future__ import annotations

{katalyst_forge-4.2.0 → katalyst_forge-5.2.0}/src/katalyst_forge/bundle.py

@@ -1,6 +1,6 @@
 """Forge bundle — the pre-installed taxonomy for software delivery.
 
-Assembles 34 node types across 8 wings from the wing modules into
+Assembles 36 node types across 8 wings from the wing modules into
 a single ``ForgeBundle`` that implements the engine's ``Bundle``
 protocol. Discovered via the ``katalyst_engine.bundles`` entry point.
 
@@ -9,12 +9,13 @@ protocol. Discovered via the ``katalyst_engine.bundles`` entry point.
 Wing modules:
 - ``wings/system.py``    — system, environment, stack, layer, library, capability
 - ``wings/org.py``       — organization, program, project, team, team_member, role
-- ``wings/practices.py`` — practice_area, competency, skill, tool
-- ``wings/design.py``    — business_domain_model, user_type, user_need, design_spec, adr, nfr, specification, assertion
+- ``wings/practices.py``  — practice_area, practice, competency, skill, standard, nfr, method, adr, tool
+- ``wings/design.py``    — business_domain_model, user_type, user_need, design_spec, specification, assertion
 - ``wings/delivery.py``  — work_item, change_entry, agent_run
 - ``wings/pipeline.py``  — cicd_stage
 - ``wings/pipeline.py``  — cicd_stage, cicd_job_template, cicd_workflow_template
 - ``wings/agentic.py``   — agent, agent_skill
+- ``wings/metrics.py``   — metric_definition, signal_source, threshold_profile
 """
 
 from __future__ import annotations
@@ -36,6 +37,7 @@ from katalyst_forge.relationships import ALL_RELATIONSHIP_DEFINITIONS
 from katalyst_forge.wings.agentic import AGENTIC_WING, AGENTIC_WING_NODES
 from katalyst_forge.wings.delivery import DELIVERY_WING, DELIVERY_WING_NODES
 from katalyst_forge.wings.design import DESIGN_WING, DESIGN_WING_NODES
+from katalyst_forge.wings.metrics import METRICS_WING, METRICS_WING_NODES
 from katalyst_forge.wings.org import ORG_WING, ORG_WING_NODES
 from katalyst_forge.wings.pipeline import PIPELINE_WING, PIPELINE_WING_NODES
 from katalyst_forge.wings.practices import PRACTICES_WING, PRACTICES_WING_NODES
@@ -53,6 +55,7 @@ ALL_NODE_DEFINITIONS: list[NodeDefinition] = [
     *DELIVERY_WING_NODES,
     *PIPELINE_WING_NODES,
     *AGENTIC_WING_NODES,
+    *METRICS_WING_NODES,
 ]
 
 ALL_KINDS: frozenset[str] = frozenset(nd.describes_kind for nd in ALL_NODE_DEFINITIONS)
@@ -65,6 +68,7 @@ ALL_WING_DEFINITIONS: list[WingDefinition] = [
     PRACTICES_WING,
     PIPELINE_WING,
     AGENTIC_WING,
+    METRICS_WING,
 ]
 
 ALL_WING_NAMES: frozenset[str] = frozenset(wd.identity.name for wd in ALL_WING_DEFINITIONS)
@@ -76,7 +80,7 @@ ALL_WING_NAMES: frozenset[str] = frozenset(wd.identity.name for wd in ALL_WING_D
 
 
 class ForgeBundle:
-    """The Forge bundle — 34 node types across 8 wings.
+    """The Forge bundle — 36 node types across 8 wings.
 
     This is the pre-installed taxonomy bundle that ships with
     Katalyst Taxonomy. It models software delivery organizations
@@ -89,10 +93,10 @@ class ForgeBundle:
     def manifest(self) -> BundleManifest:
         return BundleManifest(
             identity=Identity(kind="bundle", name="forge"),
-            version=Version(major=4, minor=0),
+            version=Version(major=5, minor=1),
             provided_kinds=ALL_KINDS,
             wing_names=ALL_WING_NAMES,
-            description="Forge taxonomy — 30 node types for modeling software delivery organizations",
+            description="Forge taxonomy — 36 node types for modeling software delivery organizations",
         )
 
     def node_definitions(self) -> list[NodeDefinition]:
@@ -109,7 +113,7 @@ class ForgeBundle:
             identity=Identity(kind="schema", name="forge"),
             describes_kind="taxonomy",
             api_version="v2alpha",
-            schema_version=Version(major=4),
+            schema_version=Version(major=5),
             node_definitions=tuple(nd.identity for nd in ALL_NODE_DEFINITIONS),
             wing_definitions=tuple(wd.identity for wd in ALL_WING_DEFINITIONS),
         )

katalyst_forge-5.2.0/src/katalyst_forge/metrics/__init__.py

@@ -0,0 +1,57 @@
+"""Public API for the cost/observability metrics adapter.
+
+Must NOT import anything from .providers, which would defeat the registry's
+lazy provider resolution (see registry.py and providers/__init__.py).
+"""
+
+from __future__ import annotations
+
+from katalyst_forge.metrics.batch import CanonicalSignalBatch, project_batch
+from katalyst_forge.metrics.billing import BillingMode
+from katalyst_forge.metrics.core import MetricResult, compute, resolve
+from katalyst_forge.metrics.errors import (
+    BatchConstructionError,
+    ContractViolationError,
+    CrossBillingModeError,
+    MetricsAdapterError,
+    MissingCredentialError,
+    MissingMappedFieldError,
+    MoneyPrecisionError,
+    PriceUnavailableError,
+    ProviderPayloadError,
+    ProviderUnavailableError,
+    UnknownBillingModeError,
+    UnknownProviderError,
+    UnmappedFieldError,
+)
+from katalyst_forge.metrics.money import parse_money
+from katalyst_forge.metrics.protocols import PriceCatalogue, SignalProvider
+from katalyst_forge.metrics.redaction import redact
+from katalyst_forge.metrics.registry import SignalProviderRegistry
+
+__all__ = (
+    "BillingMode",
+    "CanonicalSignalBatch",
+    "project_batch",
+    "MetricResult",
+    "resolve",
+    "compute",
+    "SignalProviderRegistry",
+    "SignalProvider",
+    "PriceCatalogue",
+    "parse_money",
+    "redact",
+    "MetricsAdapterError",
+    "BatchConstructionError",
+    "UnmappedFieldError",
+    "MissingMappedFieldError",
+    "ContractViolationError",
+    "MoneyPrecisionError",
+    "PriceUnavailableError",
+    "UnknownBillingModeError",
+    "CrossBillingModeError",
+    "UnknownProviderError",
+    "MissingCredentialError",
+    "ProviderUnavailableError",
+    "ProviderPayloadError",
+)

katalyst_forge-5.2.0/src/katalyst_forge/metrics/batch.py

@@ -0,0 +1,174 @@
+"""Canonical signal batch: deny-by-default projection and a non-bypassable type.
+
+CanonicalSignalBatch can only be produced by project_batch. The constructor
+requires a private guard sentinel that lives only in this module, so no
+outside code, including copy.copy, copy.deepcopy, and pickle, can forge or
+clone an instance. Projection itself is deny-by-default: only canonical
+fields named in a source's field_mapping are ever copied out of a provider
+record, so any field a provider returns but nobody mapped (including
+prompt-shaped fields such as "instructions" or "system_prompt") is dropped,
+never passed through.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+from typing import Final, cast
+
+from katalyst_forge.metrics.billing import BillingMode
+from katalyst_forge.metrics.errors import BatchConstructionError, MissingMappedFieldError
+
+__all__ = ("CanonicalSignalBatch", "project_batch")
+
+
+class _ProjectionGuard:
+    """Sentinel type; only _GUARD below is a valid instance of it."""
+
+    __slots__ = ()
+
+
+_GUARD: Final[_ProjectionGuard] = _ProjectionGuard()
+
+
+class CanonicalSignalBatch:
+    """An immutable, already-projected batch of canonical signal records."""
+
+    __slots__ = ("_billing_mode", "_run_id", "_source_name", "_records")
+
+    def __init__(
+        self,
+        _guard: _ProjectionGuard,
+        *,
+        billing_mode: BillingMode,
+        run_id: str,
+        source_name: str,
+        records: tuple[Mapping[str, object], ...],
+    ) -> None:
+        if _guard is not _GUARD:
+            raise BatchConstructionError("only project_batch may construct a CanonicalSignalBatch")
+        self._billing_mode = billing_mode
+        self._run_id = run_id
+        self._source_name = source_name
+        self._records = records
+
+    @property
+    def billing_mode(self) -> BillingMode:
+        return self._billing_mode
+
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+
+    @property
+    def source_name(self) -> str:
+        return self._source_name
+
+    @property
+    def records(self) -> tuple[Mapping[str, object], ...]:
+        return self._records
+
+    def __copy__(self) -> CanonicalSignalBatch:
+        raise BatchConstructionError("CanonicalSignalBatch cannot be copied")
+
+    def __deepcopy__(self, memo: dict[int, object]) -> CanonicalSignalBatch:
+        raise BatchConstructionError("CanonicalSignalBatch cannot be deepcopied")
+
+    def __reduce__(self) -> tuple[object, ...]:
+        raise BatchConstructionError("CanonicalSignalBatch cannot be pickled")
+
+
+def _as_mapping(value: object) -> Mapping[str, object] | None:
+    """Narrow value to a concretely-typed Mapping, or None if it is not one."""
+    if isinstance(value, Mapping):
+        return cast("Mapping[str, object]", value)
+    return None
+
+
+def _get_mapping(doc: Mapping[str, object], key: str) -> Mapping[str, object]:
+    """Read doc[key] as a Mapping, defaulting to empty rather than raising."""
+    mapped = _as_mapping(doc.get(key))
+    return mapped if mapped is not None else {}
+
+
+def _str_frozenset(value: object) -> frozenset[str]:
+    """Read a YAML string list as a set, tolerating a bare string or absence."""
+    if isinstance(value, str):
+        return frozenset({value})
+    if isinstance(value, (list, tuple)):
+        items = cast("Sequence[object]", value)
+        return frozenset(item for item in items if isinstance(item, str))
+    return frozenset()
+
+
+def _read_path(record: Mapping[str, object], path: str) -> object | None:
+    """Walk a dotted path through record, returning None on any non-Mapping hop."""
+    current: object = record
+    for segment in path.split("."):
+        current_mapping = _as_mapping(current)
+        if current_mapping is None:
+            return None
+        current = current_mapping.get(segment)
+    return current
+
+
+def project_batch(
+    *,
+    signal_source_doc: Mapping[str, object],
+    records: Sequence[Mapping[str, object]],
+    billing_mode: BillingMode,
+    run_id: str,
+    source_name: str,
+) -> CanonicalSignalBatch:
+    """Deny-by-default projection: keep only canonical fields named in field_mapping.
+
+    field_mapping is canonical_input_name -> provider.dotted.path. For every
+    provider record, a new dict is built containing only those canonical
+    keys, each pulled from the mapped path. A field the provider returns but
+    no mapping references is never copied. A mapped path missing from one
+    record is simply omitted from that record's projection; a mapping
+    that resolves for zero records across the whole batch is an error, since
+    that indicates the mapping itself is wrong rather than sparse data, unless
+    the source names the field in optional_fields.
+
+    optional_fields exists for a value the provider synthesizes and may
+    legitimately not have, such as a Forge stage inferred from a session that is
+    not a Forge stage at all. Holding such a field to the zero-resolution guard
+    discarded a run's entire cost rather than only its stage attribution, so a
+    total vanished because one attribution dimension was absent. The trade is
+    that a typo in an optional field's path stops being caught, which is why it
+    is declared per source rather than assumed.
+    """
+    spec = _get_mapping(signal_source_doc, "spec")
+    field_mapping = _get_mapping(spec, "field_mapping")
+    optional_fields = _str_frozenset(spec.get("optional_fields"))
+
+    canonical_paths: tuple[tuple[str, str], ...] = tuple(
+        (canonical_key, path)
+        for canonical_key, path in field_mapping.items()
+        if isinstance(path, str)
+    )
+
+    resolved_counts: dict[str, int] = {canonical_key: 0 for canonical_key, _ in canonical_paths}
+    projected_records: list[Mapping[str, object]] = []
+
+    for record in records:
+        projected: dict[str, object] = {}
+        for canonical_key, path in canonical_paths:
+            value = _read_path(record, path)
+            if value is not None:
+                projected[canonical_key] = value
+                resolved_counts[canonical_key] += 1
+        projected_records.append(MappingProxyType(projected))
+
+    for canonical_key, count in resolved_counts.items():
+        if count == 0 and canonical_key not in optional_fields:
+            raise MissingMappedFieldError(canonical_field=canonical_key, source_name=source_name)
+
+    return CanonicalSignalBatch(
+        _GUARD,
+        billing_mode=billing_mode,
+        run_id=run_id,
+        source_name=source_name,
+        records=tuple(projected_records),
+    )

katalyst_forge-5.2.0/src/katalyst_forge/metrics/billing.py

@@ -0,0 +1,35 @@
+"""Billing mode enum and strict parsing (metered vs. subscription-notional)."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from katalyst_forge.metrics.errors import UnknownBillingModeError
+
+
+class BillingMode(StrEnum):
+    """The two ways a signal source's cost figures are billed.
+
+    METERED means the provider charges per unit consumed. SUBSCRIPTION_NOTIONAL
+    means the spend is a flat subscription and the figure is a notional
+    allocation, not an invoice line. These are different quantities and must
+    never be combined (see core.MetricResult).
+    """
+
+    METERED = "metered"
+    SUBSCRIPTION_NOTIONAL = "subscription_notional"
+
+
+def parse_billing_mode(raw: object) -> BillingMode:
+    """Parse a billing mode from a document value, never defaulting.
+
+    A missing or unrecognized billing mode is a contract error, not a hint to
+    guess metered as a safe default; guessing wrong silently mislabels cost.
+    """
+    if isinstance(raw, BillingMode):
+        return raw
+    if isinstance(raw, str):
+        for mode in BillingMode:
+            if mode.value == raw:
+                return mode
+    raise UnknownBillingModeError(raw)