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

{katalyst_forge-5.1.0 → katalyst_forge-5.2.0}/.gitignore

@@ -21,3 +21,11 @@ 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.1.0 → katalyst_forge-5.2.0}/CHANGELOG.md

@@ -16,6 +16,30 @@ 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.

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "5.1.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-5.1.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-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)

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

@@ -0,0 +1,128 @@
+"""Contract validation: does a source's field_mapping cover a metric's inputs?
+
+field_mapping is canonical_input_name -> provider.dotted.path, so "does this
+source cover this metric's inputs" is checked against the mapping's KEYS
+(the canonical side), never the provider paths on the right. unit_price_usd
+is exempt from coverage because it is supplied by the injected price
+catalogue at compute time, not projected out of a provider record. Inputs
+listed in BILLING_MODE_SCOPED_INPUTS are exempt in any billing mode other
+than the ones listed, because the quantity they describe (e.g. headroom
+against a subscription cap) simply does not exist outside that mode.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Final, cast
+
+from katalyst_forge.metrics.billing import BillingMode
+from katalyst_forge.metrics.errors import ContractViolationError
+
+CATALOGUE_PROVIDED_INPUTS: Final[frozenset[str]] = frozenset({"unit_price_usd"})
+
+# Supplied by the resolve() caller, not projected from a provider record.
+# Neither provider carries a Forge run identifier in its payload, so requiring
+# a field_mapping entry for run_id would mean naming a path that does not exist.
+CONTEXT_PROVIDED_INPUTS: Final[frozenset[str]] = frozenset({"run_id"})
+
+# Supplied by the injected RoutingPolicy. A routing counterfactual compares
+# against a model nobody's payload reports, so these are policy, not data.
+POLICY_PROVIDED_INPUTS: Final[frozenset[str]] = frozenset(
+    {"orchestrator_model", "routing_target_model"}
+)
+
+BILLING_MODE_SCOPED_INPUTS: Final[Mapping[str, frozenset[BillingMode]]] = {
+    "metered_cost_usd": frozenset({BillingMode.METERED}),
+    "notional_cost_usd": frozenset({BillingMode.SUBSCRIPTION_NOTIONAL}),
+}
+
+
+def _as_mapping(value: object) -> Mapping[str, object] | None:
+    if isinstance(value, Mapping):
+        return cast("Mapping[str, object]", value)
+    return None
+
+
+def _get_mapping(doc: Mapping[str, object], key: str) -> Mapping[str, object]:
+    mapped = _as_mapping(doc.get(key))
+    return mapped if mapped is not None else {}
+
+
+def _str_tuple(value: object) -> tuple[str, ...]:
+    """Normalise a scalar-or-list document field to a tuple of strings.
+
+    A bare string must normalise to a one-element tuple, not an empty one.
+    metric_ref widened from a scalar to a list in slice A and stayed
+    backwards compatible, so the two shipped scalar docs still reach here as
+    plain strings; returning () for them would silently skip contract
+    validation entirely rather than checking it.
+    """
+    if isinstance(value, str):
+        return (value,)
+    if isinstance(value, (list, tuple)):
+        items = cast("Sequence[object]", value)
+        return tuple(item for item in items if isinstance(item, str))
+    return ()
+
+
+def required_inputs(
+    metric_definition_doc: Mapping[str, object], billing_mode: BillingMode
+) -> frozenset[str]:
+    """Return the metric's inputs a source must map, given a billing mode."""
+    spec = _get_mapping(metric_definition_doc, "spec")
+    inputs = frozenset(_str_tuple(spec.get("inputs")))
+
+    scoped_out = {
+        name
+        for name in inputs
+        if name in BILLING_MODE_SCOPED_INPUTS
+        and billing_mode not in BILLING_MODE_SCOPED_INPUTS[name]
+    }
+    return (
+        inputs
+        - CATALOGUE_PROVIDED_INPUTS
+        - CONTEXT_PROVIDED_INPUTS
+        - POLICY_PROVIDED_INPUTS
+        - scoped_out
+    )
+
+
+def validate_source_contract(
+    *,
+    signal_source_doc: Mapping[str, object],
+    metric_definitions: Mapping[str, Mapping[str, object]],
+    billing_mode: BillingMode,
+) -> None:
+    """Raise ContractViolationError if source's field_mapping under-covers a metric_ref."""
+    spec = _get_mapping(signal_source_doc, "spec")
+    source_name = _doc_name(signal_source_doc)
+    metric_refs = _str_tuple(spec.get("metric_ref"))
+    field_mapping = _get_mapping(spec, "field_mapping")
+
+    mapped_keys = frozenset(field_mapping.keys())
+
+    for metric_name in metric_refs:
+        metric_doc = metric_definitions.get(metric_name)
+        if metric_doc is None:
+            raise ContractViolationError(
+                metric_name=metric_name,
+                source_name=source_name,
+                missing_inputs=("<unknown metric>",),
+            )
+        needed = required_inputs(metric_doc, billing_mode)
+        missing = needed - mapped_keys
+        if missing:
+            raise ContractViolationError(
+                metric_name=metric_name,
+                source_name=source_name,
+                missing_inputs=tuple(sorted(missing)),
+            )
+
+
+def _doc_name(doc: Mapping[str, object]) -> str:
+    identity = _get_mapping(doc, "identity")
+    name = identity.get("name")
+    if isinstance(name, str):
+        return name
+    name = doc.get("name")
+    return name if isinstance(name, str) else "<unnamed>"