Jira progress: loading…

ZX-KISMET-01

KISMET Contract Specification v1.0

00 Document control

Item	Value
Document ID	ZX-KISMET-01 (proposed; pending registration in config/system/acronyms.json)
Version	1.0.0
Status	draft
Owner	CTO, Viroway Ltd
Schemas	schemas/kismet/zayaz.kismet.*.v1.schema.json (JSON Schema 2020-12)
Examples	schemas/kismet/examples/*.yaml — every YAML block in this document is one of these files and validates against its schema
Golden vectors	schemas/kismet/vectors/
First consumers	Scope 3 category engines (composition), RIF v1 (binding, resolver, policy)
Supersedes	— (first version)

This specification is normative for every ZAYAZ component that declares itself a KISMET kernel, binding, resolver, policy or composition, and for every execution record that claims KISMET conformance. It does not define any domain's kernel catalogue; each consuming domain defines its own under these contracts.

Terminology note. The word kernel is also used elsewhere in ZAYAZ for the Constitutional Understanding Kernel (COUE) and for governance kernels. Those are governance and knowledge constructs. A KISMET kernel is a governed executable method and nothing else; where this document says kernel unqualified, it means a KISMET kernel.

---

01 Purpose and normative language

KISMET (Kernel Interoperability, Shared Methods & Execution Trust) is the ZAYAZ framework for reusable executable methods. It governs how a mathematical or procedural operation is implemented once, parameterised for many business contexts, interpreted under separately governed policies, and executed with evidence an auditor can replay.

KISMET exists because the same statistical and arithmetic operations recur across ZAYAZ domains — risk verification (RIF), Scope 3 category engines, TrustGate scoring, EVI, PEF/LCA — and each domain would otherwise implement its own copy. One governed kernel serving many governed bindings removes the duplication without removing the business meaning each domain attaches to the result.

One kernel → many governed bindings → unlimited traceable executions. Adding the 10,000th metric to ZAYAZ shall not require the 10,000th kernel.

The terms SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY and MAY NOT are normative. Requirement identifiers of the form KISMET-REQ-nnnn (§24) are stable and SHALL be cited by implementations and by the Conformance Harness.

---

02 Scope and non-goals

In scope:

• the five governed KISMET artifacts and the execution manifest;
• the contract (schema) each artifact SHALL satisfy;
• identity, versioning and compatibility rules;
• the seven KISMET invariants (KMI-01 to KMI-07);
• conformance requirements for implementations.

Out of scope:

• the kernel catalogue itself (owned per domain, consolidated under KMI-01 and KMI-04);
• orchestration — which capability is selected for which signal (ZSSR);
• regulatory or methodological authority — a binding references a governed method; KISMET does not create one;
• workflow consequences of a policy verdict — notify, escalate, block, assign audit — which belong to the consuming authority (RIF, Watchtower, VAM), never to a KISMET policy;
• the Conformance Harness itself (separate specification; its obligations are stated in §09).

---

03 The five governed artifacts

KISMET separates five concerns that earlier engine drafts (RIF v0.4 among them) mixed inside single functions. Each is a governed, versioned record with its own contract.

Artifact	Contract	Governs	Answers
Kernel	KEC — Kernel Execution Contract	Algorithm, typed inputs and outputs, unit classes, numerical guards, runtime requirements	What computation exists?
Binding	KBC — Kernel Binding Contract	Metric association, input mapping, resolver slots, selected guards, required policy slot	Which inputs feed this kernel for this metric?
Resolver	KRC — Kernel Resolver Contract	Reference-data selection, cohort construction, fallback order, snapshot identity	Which reference data, and why?
Policy	KPC — Kernel Policy Contract	Interpretation: direction, severity bands, evidence admissibility, scope, effective period	What does the result mean here?
Composition	KCC — Kernel Composition Contract	Execution graph, dependency ranges, error propagation	How do kernels combine into a capability?

A sixth record, the execution manifest (§05.6), is not a governed artifact but the immutable evidence of how the five were resolved for one run. It is written to existing ZAYAZ evidence infrastructure (ZAR lineage, ALTD, execution telemetry); KISMET SHALL NOT introduce a parallel logging system.

                ┌──────────────┐
                │   Kernel     │  KEC — the computation
                └──────┬───────┘
                       │ referenced by
                ┌──────▼───────┐        ┌──────────────┐
                │   Binding    │──slot──▶   Resolver   │  KRC — the reference data
                └──────┬───────┘        └──────────────┘
                       │ declares policy slot
                ┌──────▼───────┐
                │   Policy     │  KPC — the meaning (supplied by the consuming authority)
                └──────┬───────┘
                       │
                ┌──────▼───────────────────────────────┐
                │   Execution manifest                 │  all versions, snapshots, hashes pinned
                └──────────────────────────────────────┘

   Composition (KCC) governs graphs of kernels; it sits beside, not above, this chain.

This is a logical model. Resolver and policy selection MAY be coordinated by authorised orchestration in any order that satisfies the contracts; it is not a mandatory sequential runtime pipeline.

03.1 Kernel

A kernel is a governed reusable executable capability boundary, not necessarily a single primitive operation. Two kinds exist:

• Atomic kernel — one operation with no KISMET dependencies (z-score, signed difference, relative discrepancy, rate, weighted sum, Monte Carlo sampler, unit conversion).
• Composite kernel — an execution graph of atomic kernels, other composites and approved micro-engines (MICE), declared under a KCC.

A kernel owns its mathematics and its guards: input validation, unit-class checks, numerical precision, zero and missing-value handling, overflow behaviour. A kernel SHALL NOT own interpretation. KISMET-KERNEL-STAT-ZSCORE returns z; it does not know whether z = 2.5 is good news.

03.2 Binding

A binding is the configuration that makes a kernel meaningful for one metric in one domain. It maps each kernel input to a source — a signal reference, a resolver slot, a literal parameter, or a composition node output — fixes the numerical guards the kernel offers as options, and declares which policy slot must be filled before the result may be interpreted.

A binding SHALL NOT carry a threshold, a direction or a severity. Those belong to the policy, so that the same binding can serve an upper-tail risk check in RIF and a lower-tail benchmarking view elsewhere without duplication.

Binding identity is separate from kernel identity. Adding a metric registers a binding; it never versions the kernel.

03.3 Resolver

A resolver selects governed reference data for a binding input: a sector benchmark, an emission-factor set, a historical baseline. It is the most consequential artifact for auditability because it decides which cohort a company is compared with, which is where disputes with auditors land.

A resolver contract declares its inputs, an explicit ordered fallback chain, and a typed output that always carries cohort identity, observation count, the fallback level actually reached, and a snapshot reference with hash. Two requirements apply to every resolver:

• Atomic cohort resolution. When a kernel needs more than one statistic from the same reference population (mean and standard deviation; numerator and denominator), the resolver SHALL return them from one cohort snapshot. It SHALL NOT resolve them independently.
• Eligibility precedes admissibility. A resolver SHALL apply versioned technical cohort-eligibility criteria (including minimum observation count, data completeness and dimensional compatibility) at each fallback level. Only eligible candidates may be selected; an ineligible candidate SHALL be recorded as skipped with a reason. After selecting a technically eligible cohort, the resolver reports the level and provenance; whether that cohort is acceptable evidence for a particular decision belongs exclusively to KPC. If no eligible level exists, resolution fails explicitly. The policy SHALL NOT silently change the resolver cohort.

03.4 Policy

A policy interprets a kernel result for one purpose. Its conditions SHALL use a declared, restricted, typed evaluation grammar with specified operator precedence, null handling and interval boundaries; arbitrary executable expressions and side effects are forbidden. A conformance evaluator SHALL produce the same verdict for the same pinned inputs and policy version. It carries direction, severity bands, the governed parameters those bands reference, evidence-admissibility rules (including which resolver fallback levels are acceptable), scope, and an effective period. Its output is a typed verdict — severity, admissibility, rationale — and nothing else.

A policy SHALL NOT carry consequences. Mapping a verdict to a notification, an escalation, a blocked execution or an audit assignment is the consuming authority's workflow, governed under that authority's own rules. Keeping actions out of KPC keeps verdicts immutable evidence (KMI-07) and keeps KISMET from becoming a workflow engine.

Thresholds are versioned independently of kernels and bindings. A changed threshold is a new policy version; it never forces a new kernel version.

Reference expression grammar (KPC v2). interpretation.variables declares each scalar result input as number, string or boolean. Governed numeric parameters occupy a separate, non-overlapping namespace. Enum values are quoted string literals, for example state in ['satisfied', 'not_applicable']; unquoted words are variable references. The shipped reference evaluator supports finite numeric literals (including signed literals), string and boolean literals, declared names, numeric <, <=, >, >=, same-type == / !=, in / not in against nonempty homogeneous literal lists, parentheses and boolean and. Comparisons bind before and; chained comparisons require every adjacent comparison to hold. There is no coercion between booleans, numbers and strings. Null and non-finite inputs are rejected before interpretation; a consumer receiving a null mathematical result reports that no verdict was evaluated. Calls, attribute access, subscripts, arithmetic and all other syntax are rejected, including in unreachable branches.

Catalogue validation checks every condition against the declared types, independently of test values. Evaluation requires exactly one matching band: both overlaps and gaps are errors. Static grammar validation does not claim exhaustive partition proof for every possible input. Boundary and domain vectors remain required. Optional band label values are governed display metadata; consumers read them from the selected band instead of assigning meaning to its position. A reference evaluator may calculate draft fixtures for conformance, but successful calculation is not policy approval or runtime admission. If verdict.fields includes score, the policy SHALL declare verdict.score_source naming a numeric interpretation.variables input. The verdict copies that evaluated input exactly, without rounding or a separately supplied score. Parameters and undeclared or non-numeric inputs cannot be score sources. A policy without a score field SHALL NOT declare a score source.

03.5 Composition

A composition declares an execution graph: which kernels, resolvers and micro-engines participate, how outputs feed inputs, which dependency versions are compatible, and how errors propagate. Compositions declare compatibility ranges; executions pin the exact dependency graph used. A composition SHALL NOT change its dependencies during a running execution.

Scope 3 category engines are the reference consumer: thin category controllers expressed as compositions over shared method kernels, with the Scope 3 post office as orchestration outside KISMET.

03.6 Execution manifest

Every KISMET execution SHALL produce one immutable manifest recording: kernel ID and version; binding ID and version; resolver ID, version, cohort, fallback level, snapshot reference and hash for every resolved input; policy ID and version; composition ID and version with the exact transitive dependency graph; input and output hashes; result and verdict; and, for stochastic kernels, seed, RNG algorithm and version, iteration count, distribution specification and model artifact reference.

03.7 Evidence custody and replay boundary

KISMET SHALL NOT create another audit store. ZAR is the authority for identities, typed provenance and parent/child execution lineage; ALTD is the authority for immutable integrity evidence and anchoring. Existing execution telemetry remains the operational record. KISMET's manifest is a content-addressed execution attestation that references these authorities; it SHALL NOT treat a mere hash as proof that the hashed payload remains available. The manifest MUST identify immutable, retrievable input/output artifacts, their integrity hashes, the exact executable build digest, the resolved guard set, the policy/resolver artifacts, and the transitive dependency closure (or an immutable closure reference with an integrity digest).

ALTD anchoring may complete asynchronously, but its state must be explicit. A completed mathematical calculation without an accepted integrity anchor SHALL NOT be misrepresented as an anchored record. Cross-store referential validity, retention, tenant boundaries and finality MUST be checked by the admission/conformance service, not assumed from JSON Schema validity.

Reproduction levels: statistical reproducibility to a declared tolerance is mandatory for applicable stochastic execution; bitwise identity is best-effort on matched builds and infrastructure only. Deterministic operations declare their numerical tolerance and environment assumptions. Missing input payloads, model artifacts or cohort snapshots mean replay is not established, even when hashes still match the manifest.

---

04 Identity and namespace

JiraTaskUnlinkedZYZ-1149ZX-KISMET-01#04-identity-and-namespace#1

KISMET identifiers form a namespace distinct from engine identifiers (MEID), component manifests (CMI) and signal contracts (CSI). A kernel is not an engine: engines are deployed runtime components with lifecycle and ownership; kernels are governed executable contracts that engines and micro-engines implement and compose.

The namespace is proposed for constitutional registration under the Canonical Identifier Architecture and the Artifact Constitution. Until registered, every KISMET identifier in this document is a proposed identifier and SHALL NOT be used as a graph reference in frontmatter relationship fields.

04.1 Grammar

KISMET-<KIND>-<OWNER>-<NAME>

KIND   ∈ { KERNEL, BINDING, RESOLVER, POLICY, COMPOSITION }
OWNER  =  UPPER alphanumeric, 2–8 chars
          kernels:  family code   STAT | SIM | SCORE | DATA | RATE | UNIT | …
          others:   authority     RIF | S3 | TG | EVI | CORE | …
NAME   =  UPPER_SNAKE, 3–48 chars

regex  ^KISMET-(KERNEL|BINDING|RESOLVER|POLICY|COMPOSITION)-[A-Z][A-Z0-9]{1,7}-[A-Z][A-Z0-9_]{2,47}$

Version is a separate semver field on every artifact and is never embedded in the identifier. Execution manifests are identified by a runtime identifier (KXID, proposed identifier type) rather than by this grammar.

Examples (proposed):

KISMET-KERNEL-STAT-ZSCORE
KISMET-KERNEL-STAT-SIGNED_DIFFERENCE
KISMET-KERNEL-STAT-REL_DISCREPANCY
KISMET-KERNEL-SIM-MC_SAMPLER
KISMET-BINDING-RIF-ESG_OVERPERFORMANCE
KISMET-RESOLVER-RIF-SECTOR_BENCHMARK
KISMET-POLICY-RIF-ESG_OVERPERFORMANCE_UPPER_TAIL
KISMET-COMPOSITION-S3-CAT04_UPSTREAM_TRANSPORT

04.2 Relationship to existing identifier classes

Identifier	Owns	Relationship to KISMET
MEID	Logical engine concept	An engine implements one or more kernels; its MDX declares kismet.implements: [KISMET-KERNEL-…]
CMI	Deployed component manifest	A CMI pins which kernel versions a component build carries; the manifest's executed_by is a CMI
CSI	Signal transport contract	Kernel inputs reference signals through binding input maps
MICE type	Micro-engine classification	A micro-engine may be a kernel implementation, a composition node, or neither
ARTIF	Persistent business artifact	A manifest is evidence, not a business artifact; verdicts that become artifacts are declared by the consuming authority under the ARTIF namespace
ZCT contract	Contract taxonomy record	Each KISMET contract type SHOULD be registered as a schema_contract in ZCT once the namespace is approved

---

05 Contracts

JiraStoryUnlinkedZYZ-1147ZX-KISMET-01#05-contracts#1

Each contract is published as a JSON Schema (draft 2020-12) under schemas/kismet/ so the Conformance Harness can validate artifacts mechanically. The YAML below is the authored form, taken verbatim from schemas/kismet/examples/; the schema is normative where the two differ.

Contract	Schema ID
KEC	zayaz.kismet.kernel.v1
KBC	zayaz.kismet.binding.v1
KRC	zayaz.kismet.resolver.v1
KPC	zayaz.kismet.policy.v2 (typed policies); zayaz.kismet.policy.v1 retained unchanged for schema validation
KCC	zayaz.kismet.composition.v1
Manifest	zayaz.kismet.execution-manifest.v1

05.1 KEC — Kernel Execution Contract

contract_type: KEC
kernel_id: KISMET-KERNEL-STAT-ZSCORE
version: 1.0.0
kind: atomic
family: STAT
title: Standard score
description: Returns (x - mu) / sigma for one observation against a reference distribution. Carries no interpretation.
inputs:
  observed_value:
    type: number
    unit_class: any
    required: true
  reference_mean:
    type: number
    unit_class: same_as:observed_value
    required: true
  reference_std_dev:
    type: number
    unit_class: same_as:observed_value
    required: true
    constraints: { minimum_exclusive: 0 }
outputs:
  z_score:
    type: number
    unit_class: dimensionless
guards:
  zero_variance: { options: [reject, return_null], default: reject }
  missing_input: { options: [reject], default: reject }
  non_finite:    { options: [reject], default: reject }
numerics:
  precision: float64
  deterministic: true
runtime:
  stochastic: false
  seed_required: false
conformance:
  golden_vectors: schemas/kismet/vectors/KISMET-KERNEL-STAT-ZSCORE.1.0.0.json
  property_tests: [symmetry_about_mean, scale_invariance]
governance:
  status: draft
  owner: architecture@viroway.com

Normative rules:

1. A kernel SHALL declare every input and output with a type and a unit class. A binding that maps an input of an incompatible unit class fails validation; units are checked, never "interpreted".
2. A kernel SHALL declare its guards as options with defaults. A binding MAY select among the options and SHALL NOT add behaviour.
3. deterministic: true kernels SHALL produce identical output for identical input on the same numeric platform. Stochastic kernels SHALL declare seed_required: true and a reproducibility tolerance.
4. Every kernel version SHALL ship golden test vectors. A kernel version without vectors is not conformant.
5. A composite kernel SHALL reference its KCC through composition_ref.

05.2 KBC — Kernel Binding Contract

contract_type: KBC
binding_id: KISMET-BINDING-RIF-ESG_OVERPERFORMANCE
version: 1.0.0
kernel:
  id: KISMET-KERNEL-STAT-ZSCORE
  version: ">=1.0.0 <2.0.0"
owner: RIF
title: ESG score versus sector cohort
aliases: [Anomaly Detection for ESG Overperformance (RIF v0.4 §106.19)]
inputs:
  observed_value:
    source: signal
    ref: sssr:metrics.esg_score
  reference_mean:
    source: resolver
    slot: sector_benchmark
    field: statistics.mean
  reference_std_dev:
    source: resolver
    slot: sector_benchmark
    field: statistics.standard_deviation
resolver_slots:
  sector_benchmark:
    resolver_id: KISMET-RESOLVER-RIF-SECTOR_BENCHMARK
    version: ">=1.0.0 <2.0.0"
    dimensions: [nace_code, geography, reporting_period]
guards:
  zero_variance: reject
policy_slot:
  required: true
  verdict_type: tail_threshold
method_ref: null
governance:
  status: draft

Normative rules:

1. A binding references a kernel by ID and a compatibility range, never a single pinned version; the manifest pins the version used.
2. Every kernel input SHALL be mapped exactly once, to a signal reference, a resolver slot field, a literal parameter, or a composition node output.
3. A binding SHALL declare a required policy slot and the verdict type it expects. It SHALL NOT carry a threshold, direction or severity.
4. Resolver slots name a resolver ID, a compatibility range and the dimensions the resolver must receive; the dimensions SHALL be resolvable from the execution context.
5. When several business functions share one canonical configuration they share one binding; aliases are documentation, never separate records.
6. method_ref names the governed method or regulatory basis the binding implements, when one exists. KISMET does not confer methodological authority.

05.3 KRC — Kernel Resolver Contract

contract_type: KRC
resolver_id: KISMET-RESOLVER-RIF-SECTOR_BENCHMARK
version: 1.0.0
owner: RIF
title: Sector benchmark statistics by NACE and geography
inputs:
  metric_id:        { required: true }
  nace_code:        { required: true }
  geography:        { required: true, format: ISO 3166-1 alpha-3 }
  reporting_period: { required: true }
  as_of:            { required: true, format: date }
fallback_chain:
  - { level: 1, match: [metric_id, nace_code, geography] }
  - { level: 2, match: [metric_id, nace_code, region], description: "region derived from geography, e.g. EUR" }
  - { level: 3, match: [metric_id, nace_code, global] }
  - { level: 4, match: [metric_id, cross_industry] }
atomic_cohort: true
output:
  statistics:
    mean: number
    standard_deviation: number
  unit: string
  cohort_id: string
  observation_count: integer
  fallback_level: integer
  snapshot_ref: string
  snapshot_hash: string
  source_refs: array
  quality_metadata: object
failure:
  no_eligible_cohort: insufficient_evidence
  snapshot_unavailable: unresolved
governance:
  status: draft
  data_sources: [reference-data engine, Eurostat, E-PRTR]

Normative rules:

1. The fallback chain SHALL be explicit, ordered and complete. An implementation that stops short of the declared chain is non-conformant. (RIF v0.4 §106.39 declared four levels and implemented three; under KRC that is a registration failure.)
2. fallback_level SHALL always be reported. Whether a level is admissible is decided by the policy, never by the resolver.
3. atomic_cohort: true resolvers SHALL return all statistics from one snapshot; mixing populations or periods is a contract violation.
4. snapshot_ref and snapshot_hash are mandatory; a resolver output without them cannot be pinned in a manifest and the execution fails KMI-05.
5. failure outcomes are typed: insufficient_evidence when no eligible cohort exists, unresolved when the snapshot cannot be reached. Neither is a kernel error.

05.4 KPC — Kernel Policy Contract

contract_type: KPC
$schema: https://schemas.zayaz.io/kismet/zayaz.kismet.policy.v2.schema.json
policy_id: KISMET-POLICY-RIF-ESG_OVERPERFORMANCE_UPPER_TAIL
version: 2.0.0
owner: RIF
verdict_type: tail_threshold
applies_to:
  binding_ids: [KISMET-BINDING-RIF-ESG_OVERPERFORMANCE]
  scope: { nace_codes: "*", geographies: "*" }
effective: { from: "2026-11-01", to: null }
interpretation:
  variables: { z: number }
  direction: upper_tail
  parameters: { warn_at: 2.0, fail_at: 3.0 }
  bands:
    - { severity: info, when: "z < warn_at" }
    - { severity: warn, when: "warn_at <= z < fail_at" }
    - { severity: fail, when: "z >= fail_at" }
admissibility:
  max_resolver_fallback_level: 2
  min_observation_count: 30
verdict:
  fields: [severity, admissible, rationale]
authority_ref: RIF
calibration:
  proposals_allowed_from: [rif_calibration_service]
  auto_apply: false
governance:
  status: draft

Normative rules:

1. A policy SHALL output a verdict and nothing else. Consequences are declared and executed by the authority named in authority_ref.
2. direction, thresholds and bands live only here. A kernel or binding that carries any of them is non-conformant. Band expressions reference named parameters; governed values are never hard-coded.
3. Admissibility rules reference resolver outputs (fallback_level, observation_count, quality_metadata) by name. A verdict on inadmissible evidence SHALL be recorded with admissible: false, never suppressed.
4. Calibration services MAY propose a new policy version. calibration.auto_apply is always false; a proposal becomes effective only through the policy-governance process and only for subsequent executions (KMI-07).
5. effective.from / effective.to bound the policy in time; an execution selects the policy version effective at executed_at.

The reference selector uses an inclusive effective.from and exclusive effective.to (null means no upper bound), checks the binding and all declared scope dimensions, and requires the consuming adapter to supply the declared input types. Cohort admissibility fields are optional, but when declared they require valid fallback/count evidence. Failed admissibility is retained in the verdict's rationale. required_evidence requires a literal boolean attestation for each named field from the consuming adapter; absent evidence is inadmissible. The reference evaluator rejects nonempty required_quality constraints until their evaluation is implemented; it never silently ignores them. This bounded evaluator does not perform governance approval or evidence-custody verification.

05.5 KCC — Kernel Composition Contract

contract_type: KCC
composition_id: KISMET-COMPOSITION-S3-CAT04_UPSTREAM_TRANSPORT
version: 1.0.0
owner: S3
title: Scope 3 category 4 — upstream transportation and distribution
nodes:
  - { id: activity_quantity, kind: kernel,   ref: KISMET-KERNEL-UNIT-CONVERT,            version: ">=1.0.0 <2.0.0" }
  - { id: factor,            kind: resolver, ref: KISMET-RESOLVER-CORE-EMISSION_FACTOR,   version: ">=1.0.0 <2.0.0" }
  - { id: emissions,         kind: kernel,   ref: KISMET-KERNEL-RATE-PRODUCT,             version: ">=1.0.0 <2.0.0" }
  - { id: dq,                kind: mice,     ref: MEID_GHG_QUALITY_SCORE,                 version: ">=2.0.0 <3.0.0" }
edges:
  - { from: activity_quantity.output.value, to: emissions.input.a }
  - { from: factor.output.value,            to: emissions.input.b }
  - { from: emissions.output.value,         to: dq.input.emissions }
error_propagation:
  on_node_failure: halt
  on_inadmissible_evidence: propagate_verdict
outputs:
  - { name: category_emissions, from: emissions.output.value }
  - { name: data_quality,       from: dq.output.score }
governance:
  status: draft

Normative rules:

1. Nodes reference dependencies by compatibility range. The manifest records the exact versions resolved at execution start; they SHALL NOT change during the run.
2. Edges are typed. The harness SHALL check unit-class and type compatibility on every edge at registration time, not at run time.
3. A composition MAY include approved micro-engines by MEID. It SHALL NOT include an unregistered implementation.
4. Error propagation is declared, not left to implementation. substitute requires substitute_policy_ref.

05.6 Execution manifest

manifest_type: KISMET_EXECUTION
kxid: KXID-01JD3M8Q7V2K
executed_at: "2026-11-03T09:14:22Z"
executed_by: risk.RIF-VERIFY.ENGINE.CORE.1_0_0
kernel:  { id: KISMET-KERNEL-STAT-ZSCORE, version: 1.0.0 }
binding: { id: KISMET-BINDING-RIF-ESG_OVERPERFORMANCE, version: 1.0.0 }
resolvers:
  - slot: sector_benchmark
    id: KISMET-RESOLVER-RIF-SECTOR_BENCHMARK
    version: 1.0.0
    cohort_id: C23.51/NOR/2025
    fallback_level: 1
    observation_count: 42
    snapshot_ref: refdata/benchmarks/2026-10-31
    snapshot_hash: sha256:6f56530173b441ca6d048be908b6628c45e1f853415fff248c25979a83fc5d35
policy: { id: KISMET-POLICY-RIF-ESG_OVERPERFORMANCE_UPPER_TAIL, version: 2.0.0 }
composition: null
inputs_hash:  sha256:4836f299c497ad2ee93caa42a3d5578284f26b9ac7ed719e30272b30527d34db
outputs_hash: sha256:b797bab5f9f5c359f8ab2388edabe1c96aa45b3abc243ad9f4f1b80e944bd8d2
result:  { z_score: 2.5 }
verdict: { severity: warn, admissible: true, rationale: "z in [2.0, 3.0); resolver fallback level 1; n = 42" }
stochastic: null
runtime: { platform: linux-x86_64, numeric_libs: { numpy: "2.1.0" } }
lineage: { zar_ref: "zar:lineage:…", altd_ref: null }
status: completed

The manifest SHALL contain immutable payload references and SHA-256 digests, an executable build digest, resolved numerical guards and explicit evidence anchoring state. An ALTD reference MAY be pending while an anchoring transaction is underway, but an unanchored manifest SHALL never be advertised as anchored. The manifest SHALL be written to the existing ZAYAZ execution evidence infrastructure. Domain-specific views (RIF, Scope 3) MAY be layered over it; no component SHALL write a parallel execution log.

---

05.7 Shared monetary conversion boundary

Monetary inputs that participate in the same calculation SHALL share an explicit calculation currency before kernel execution. USD 100 and JPY 100 are not equal allocation bases. Quantities, percentages, allocation shares and emissions SHALL NOT undergo currency conversion. This boundary is a shared capability within the existing Shared Intelligence Stack (SIS) module (omr_module_ids: [sis]), consistent with this specification's module ownership. It is not a separate module, new kernel, policy authority or MICE type.

The reusable conversion implementation consumes frozen rates and does not depend on ECB. A separate acquisition adapter implements the provider interface; ECB is the first provider, not a KISMET requirement. Replacing it requires an approved provider policy and a conforming adapter, with no change to kernel mathematics. Future calculations use the newly selected provider; historical replay keeps its original provider, policy and snapshot. Provider substitution must never rewrite historical evidence.

If independent routing and execution identity are later needed, a Micro Engine may wrap this shared capability. Its type, registered MEID and concrete contract must be assessed separately; this change neither creates a Micro Engine identity nor treats the shared library as an already approved engine. Reuse the shared conversion implementation rather than duplicating it in each consumer.

The host SHALL select a versioned reporting/valuation policy specifying the calculation currency, approved provider and currencies, required rate date, decimal scale and rounding mode. EUR is an available choice, not an implicit universal default. Where reference data requires another currency and price year, those requirements constrain the calculation. FX conversion does not perform inflation or price-year adjustment: mismatched price years fail until a separately governed adjustment has been applied and retained in lineage.

Rate acquisition belongs to a separate service outside the kernel and replay path. It SHALL request the policy-selected date, validate quote direction (target units per one source unit), and retain the provider response/version. Current valuation policy may select current reference rates; historical transaction policy selects the applicable historical date. A missing quote, unsupported currency or date mismatch fails closed. Do not silently substitute today's rate, a prior business day, an inverse rate or another provider. Any such selection must be made explicitly by the governing policy before acquisition.

For each calculation retain the complete immutable rate snapshot and policy, including provider, source reference, effective date, target currency, direct rates, scale and rounding mode. The content digest is fx_rate_id; it is an integrity reference, not evidence of provider authenticity or authorization. The host SHALL bind that digest and the retained evidence to the existing execution evidence's input closure. Replay SHALL verify the independently retained digest and reuse the snapshot without network access. A provider revision creates a new snapshot and must not rewrite historical results.

Preserve amount_native, currency_native, amount_reporting, currency_reporting and fx_rate_id, following the accounting specification. Normalization never overwrites the native values. The host passes normalized monetary values to the existing kernel input contract and retains the conversion records alongside it. Explicitly define line-level rounding and derive totals from those rounded lines; independently rounding an invoice total may otherwise break reconciliation. Choose a scale suitable for the calculation, not merely the display's decimal places. Rounding is part of reproducible numerical policy.

Monetary output display conversion is a separate operation with its own retained policy and snapshot. Preserve the calculation result, and do not feed a display conversion back into allocation or emissions calculations. Percentages and emissions remain unchanged.

The provider-neutral reference implementation is schemas/kismet/reference/currency.py; its tests cover mixed monetary inputs, provenance/date rejection, exact decimal rounding, price-year checks and replay. The first acquisition adapter, schemas/kismet/reference/ecb_currency.py, uses ECB daily reference rates. These are working-day reference rates, not intraday trading quotes. The adapter selects the exact requested publication from ECB's historical XML, records its response hash, and derives target/source quotes from the EUR-based publication using an explicitly supplied rate precision and rounding mode. This derivation policy is frozen separately from amount rounding. The host SHALL retain the returned raw response before calculation. Weekends, missing dates and unsupported currencies fail rather than selecting another publication implicitly.

Provider authentication, approved-policy storage and execution-evidence custody remain host responsibilities. No production service or new authority is activated by this reference implementation. Existing KISMET schemas and kernel signatures are unchanged, and the Scope 3 Post Office continues to reject unnormalized mixed-currency envelopes.

---

06 Versioning and compatibility

Change	Required governance action
New metric using an existing kernel	Register a new binding; do not version the kernel
Change a binding's input mapping or selected guard	New binding version
Change interpretation, parameters, direction or admissibility	New policy version
Change resolver fallback logic or cohort semantics	New resolver version
Change kernel computation or execution contract	New kernel version; major bump when inputs, outputs or guard semantics change incompatibly
Update a compatible dependency in a composition	Resolve under the KCC range; record exact versions in the manifest
Execute a stochastic kernel	Record seed, RNG algorithm and version, iteration count, distribution specification, model artifact reference and runtime details

Semantic versioning applies to every artifact. A major bump signals an incompatible change to the contract (inputs, outputs, guard semantics, fallback semantics, verdict type). A minor bump adds optional capability. A patch changes nothing observable through the contract.

KPC v1 → v2 migration. The typed input contract is incompatible with the original KPC v1 schema, so it is published as zayaz.kismet.policy.v2, with its own $id. The original v1 schema remains unchanged. V2 artifacts SHALL select it using $schema: https://schemas.zayaz.io/kismet/zayaz.kismet.policy.v2.schema.json; absence of a selector identifies original v1, and unknown selectors are rejected rather than downloaded or inferred from the artifact version. Schema generation and the policy's own version are separate identifiers.

To migrate a policy, create a new major artifact version, declare interpretation.variables, validate every expression, and declare a numeric verdict.score_source if the verdict includes score. Optional band labels belong to v2. Recheck boundary, type and admissibility vectors and pin the new artifact version for subsequent executions. The reference validator continues to accept original v1 artifacts for schema-only validation; typed evaluation requires an explicit v2 policy and is never silently inferred for v1. This delivery updates only development catalogue/example policies and synthetic manifest pins to 2.0.0; no operational execution migration is required. If retained executions exist later, preserve their original policy artifacts and manifests; never rewrite historical results or pins as part of migration.

Reproducibility. Statistical reproducibility within the tolerance declared by the kernel is mandatory for every execution. Bitwise reproducibility is not promised: the manifest records enough (seed, RNG, numeric library versions, platform) to make it possible on matched infrastructure.

---

07 KISMET invariants

The invariant prefix is KMI (KISMET Invariant). KRI- is already used for the Constitutional Knowledge Resolver's Resolution Invariants (CIKF-2) and SHALL NOT be reused here.

ID	Invariant	Statement
KMI-01	Kernel Reuse	A reusable executable algorithm SHALL be represented by one governed kernel identity per implementation contract, independently of the number of metrics, business functions, models or engines that invoke it. Context-specific behaviour SHALL be expressed through governed, versioned bindings and policies. A new kernel identity is required only when the executable semantics cannot be represented safely by an existing kernel contract.
KMI-02	Policy Independence	Bindings declare required policy slots; interpretation, thresholds, direction and admissibility remain externally governed by policies. No kernel or binding SHALL carry interpretation.
KMI-03	Resolver Authority	Every governed reference-data resolver SHALL have a versioned contract, an explicit and complete fallback chain, atomic cohort resolution where more than one statistic is returned, and reproducible snapshot-identified outputs.
KMI-04	Algorithmic Equivalence	Consolidation of two deployed kernels into one SHALL require demonstrated contract and semantic compatibility through the Conformance Harness (schema compatibility, golden vectors, property tests, guard equivalence). Design-time consolidation of not-yet-implemented functions is a recorded design decision, not a proof obligation.
KMI-05	Execution Reproducibility	Every execution SHALL preserve the exact resolved artifacts, versions, inputs, dependency graph, data snapshots and runtime parameters in an immutable manifest on existing ZAYAZ evidence infrastructure.
KMI-06	Composition Compatibility	Compositions SHALL declare approved dependency ranges; executions SHALL pin the exact dependency graph, and no composition SHALL change its dependencies during a running execution.
KMI-07	Evidence Immutability	Subsequent changes to policies, resolvers, bindings or implementations SHALL NOT retroactively alter prior execution outcomes. A failed execution SHALL NOT change its own governing policy; calibration MAY propose, never apply.

---

08 Consolidation test (KMI-01 and KMI-04 in practice)

Two named business functions are treated as follows:

Test	Outcome
Same arity, types, dimensions and unit classes (lossless adaptations only)	Necessary for sharing a kernel
Same mathematical transformation and numerical behaviour	Necessary for sharing a kernel
Compatible guards (missing values, zero denominators, overflow, precision)	Necessary for sharing a kernel
Different reference data	One kernel; different binding and/or resolver
Different interpretation (threshold, direction, severity)	One kernel; different policy
Different evidence requirements (admissibility)	One kernel; different policy
Different algorithm	Separate kernel, or explicit composition

For design-time consolidation (functions specified but never implemented) the consuming domain records the mapping and its rationale in its catalogue. For deployed kernels, the Conformance Harness SHALL pass before two kernel identities are merged.

---

09 Conformance

JiraSpikeUnlinkedZYZ-1145ZX-KISMET-01#09-conformance#1

A component claims KISMET conformance for a kernel when:

1. its KEC validates against zayaz.kismet.kernel.v1;
2. its golden vectors pass on the target platform within the declared tolerance;
3. its declared property tests pass;
4. every guard option behaves as declared;
5. its executions emit a manifest validating against zayaz.kismet.execution-manifest.v1.

Beyond JSON Schema validation, conformance SHALL execute negative tests for cross-cohort mixing, ineligible fallback levels, unsupported policy operators, zero-variance and mismatched unit classes; SHALL verify artifact-reference closure, compatibility ranges and executable build digests; and SHALL test the replay evidence pointers and custody/anchoring states. Schema validation alone is insufficient.

Bindings, resolvers, policies and compositions claim conformance when they validate against their schema and every reference they carry resolves to a registered artifact within the declared compatibility range. Registration of any artifact SHALL be refused when validation fails; there is no provisional registration.

The golden-vector file format is shown by the reference kernel:

{
  "kernel_id": "KISMET-KERNEL-STAT-ZSCORE",
  "version": "1.0.0",
  "tolerance": 1e-12,
  "vectors": [
    { "name": "basic",            "inputs": { "observed_value": 85, "reference_mean": 70, "reference_std_dev": 6 },   "expected": { "z_score": 2.5 } },
    { "name": "at_mean",          "inputs": { "observed_value": 70, "reference_mean": 70, "reference_std_dev": 6 },   "expected": { "z_score": 0.0 } },
    { "name": "below_mean",       "inputs": { "observed_value": 58, "reference_mean": 70, "reference_std_dev": 6 },   "expected": { "z_score": -2.0 } },
    { "name": "zero_variance",    "inputs": { "observed_value": 70, "reference_mean": 70, "reference_std_dev": 0 },   "guards": { "zero_variance": "reject" }, "expected_error": "zero_variance" },
    { "name": "non_finite_input", "inputs": { "observed_value": "NaN", "reference_mean": 70, "reference_std_dev": 6 }, "expected_error": "non_finite" }
  ]
}

---

10 Responsibility model

ZSSR            Orchestration — selects the authorised capability and execution pathway
   │
RIF / S3 / …    Consuming authority — decides which checks apply, supplies policies, owns consequences
   │
KISMET          Reusable execution contracts — resolves bindings, resolvers, kernels, compositions
   ├── Atomic kernels        z-score, signed difference, ratios, rates, sampling, conversion
   ├── Composite kernels     Scope 3 category controllers, verification pipelines
   └── MICE                  approved micro-engine implementations referenced by MEID
   │
ZAR / ALTD      Execution evidence and audit — manifests, lineage, telemetry

RIF owns its risk semantics. Scope 3 owns its methodological semantics. KISMET owns neither; it owns the contracts that let both execute the same mathematics once, with evidence.

---

11 First consumers and sequencing

JiraEpicUnlinkedZYZ-1143ZX-KISMET-01#11-first-consumers-and-sequencing#1

Step	Deliverable	Depends on
1	This contract specification, JSON Schemas under schemas/kismet/, namespace registration proposal	—
2	Scope 3 category engines re-expressed as KCC compositions over shared method kernels	Step 1
3	RIF function-to-kernel mapping (25 v0.4 functions → kernels, bindings, resolvers, policy slots), then RIF v1 specification	Step 1
4	Shared kernel registry consolidation across Scope 3 and RIF under KMI-01 / KMI-04; registry v1.0 freeze	Steps 2, 3

Steps 2 and 3 run in parallel and are deliberately different consumers: Scope 3 exercises composition (KCC); RIF exercises binding, resolver and policy (KBC, KRC, KPC). Together they validate every contract before the registry is frozen.

---

24 Stable normative requirements

Requirement IDs are stable across versions of this specification. Each maps to one or more schema constraints or harness checks.

KISMET-REQ-0001 — One kernel identity per executable contract

A reusable algorithm SHALL have exactly one kernel identity per implementation contract. Registering a second kernel with an equivalent KEC SHALL be refused (KMI-01, §08).

KISMET-REQ-0002 — Kernels carry no interpretation

A KEC SHALL NOT contain thresholds, directions, severities or admissibility rules. The schema has no fields for them; a kernel that encodes them in guards or outputs is non-conformant (KMI-02).

KISMET-REQ-0003 — Bindings declare a policy slot and nothing interpretive

A KBC SHALL declare policy_slot.required and policy_slot.verdict_type, and SHALL NOT carry thresholds, direction or severity (KMI-02, §05.2).

KISMET-REQ-0004 — Complete, explicit resolver fallback chain

A KRC SHALL enumerate its full fallback chain in order; an implementation SHALL traverse exactly that chain and report fallback_level (KMI-03, §05.3).

KISMET-REQ-0005 — Atomic cohort resolution

A resolver declared atomic_cohort: true SHALL return all statistics from one cohort snapshot identified by cohort_id, snapshot_ref and snapshot_hash (KMI-03).

KISMET-REQ-0006 — Policies output verdicts only

A KPC SHALL produce severity, admissible and rationale and SHALL NOT declare or trigger consequences; authority_ref names who does (§05.4).

KISMET-REQ-0007 — Calibration proposes, never applies

calibration.auto_apply SHALL be false in every KPC. A proposed threshold becomes effective only as a new approved policy version for subsequent executions (KMI-07).

KISMET-REQ-0008 — Compatibility ranges in contracts, exact pins in manifests

KBC and KCC SHALL reference dependencies by version range; the execution manifest SHALL record the exact versions resolved at execution start (KMI-06).

KISMET-REQ-0009 — Immutable execution manifest on existing evidence infrastructure

Every execution SHALL emit one manifest validating against zayaz.kismet.execution-manifest.v1, written to ZAR/ALTD-backed infrastructure, and SHALL NOT write a parallel log (KMI-05).

KISMET-REQ-0010 — Stochastic execution evidence

Executions of kernels with runtime.stochastic: true SHALL record seed, RNG algorithm and version, iteration count and distribution specification reference; statistical reproducibility within the kernel's declared tolerance is mandatory, bitwise reproducibility is not promised (§06).

KISMET-REQ-0011 — Golden vectors per kernel version

Every kernel version SHALL ship a golden-vector file at the path declared in conformance.golden_vectors, and the harness SHALL run it before registration (§09).

KISMET-REQ-0012 — Typed edges checked at registration

Composition edges SHALL be type- and unit-class-checked when the KCC is registered; a composition with an incompatible edge SHALL NOT be registered (§05.5).

KISMET-REQ-0013 — No retroactive change to prior outcomes

No change to any artifact SHALL alter a recorded manifest, result or verdict. Re-evaluation under a new policy is a new execution with a new kxid (KMI-07).

KISMET-REQ-0014 — Deployed-kernel merges require harness proof

Merging two deployed kernel identities SHALL require passing the Conformance Harness equivalence suite; design-time mappings are recorded decisions (KMI-04, §08).

---

25 Verification and acceptance

Check	Method	Where
Artifact schema validity	JSON Schema 2020-12 validation against schemas/kismet/*.schema.json	Registration, CI
Example consistency	Every YAML block in this document validates against its schema	CI (schemas/kismet/examples/)
Golden vectors	Vector runner per kernel version within declared tolerance	Registration, CI
Property tests	Declared properties (e.g. symmetry_about_mean) executed against the implementation	Registration, CI
Edge typing	Unit-class and type compatibility across KCC edges	Registration
Reference resolution	Every ID and version range in a binding, policy or composition resolves to a registered artifact	Registration
Manifest emission	Execution emits a valid manifest with pinned versions and hashes	Runtime, sampled in CI
Negative tests	Threshold on a binding, auto_apply: true on a policy, short fallback chain — each SHALL be refused	CI

---

27 Delivery and change governance

• Changes to any contract schema SHALL follow §06 versioning; a major schema bump SHALL be accompanied by a migration note in this document's history.
• New kernel families (beyond STAT, SIM, SCORE, DATA, RATE, UNIT) SHALL be added to the controlled family vocabulary before use.
• Consuming domains SHALL NOT fork these contracts. Domain-specific needs are expressed as additional governed fields proposed back into the schema, never as parallel schemas.

---

Appendix A — Open items requiring registration or decision

Item	Needed from	Status
Document ID ZX-KISMET-01	Registration in config/system/acronyms.json (generator run)	proposed
Identifier namespace KISMET-<KIND>-<OWNER>-<NAME>	Constitutional amendment under CIA / ANC	proposed
Runtime identifier type KXID	Entry in config/system/identifier-types.json	proposed
Kernel family vocabulary (STAT, SIM, SCORE, DATA, RATE, UNIT)	Controlled registry entry	proposed
OMR module for KISMET	This document uses sis (Shared Intelligence Stack) as the foundational cross-module layer; confirm, or register a KISMET module	decision
Signal reference syntax in KBC inputs.*.ref	Confirm sssr: form against the canonical CSI / SSSR reference grammar	decision
ZCT registration of the six contract types as schema_contract entries	ZCT update	proposed
Conformance Harness specification	Separate document	not started
RIF calibration service referenced by KPC calibration.proposals_allowed_from	RIF-owned component, not a KISMET artifact	not started

Appendix B — Reference kernel set expected by the first consumers

Proposed atomic kernels, to be registered by the consuming domains under KMI-01 (not registered by this document):

Kernel	Family	First consumer	Replaces (RIF v0.4)
KISMET-KERNEL-STAT-ZSCORE	STAT	RIF	§106.19, §106.22, §106.28
KISMET-KERNEL-STAT-SIGNED_DIFFERENCE	STAT	RIF	§106.11, §106.12
KISMET-KERNEL-STAT-REL_DISCREPANCY	STAT	RIF	§106.16, §106.29
KISMET-KERNEL-STAT-PAIRED_ERROR_SERIES	STAT	RIF	§106.15
KISMET-KERNEL-SIM-MC_SAMPLER	SIM	RIF	§106.13, §106.14 (shared sampler; separate composites)
KISMET-KERNEL-SCORE-WEIGHTED_SUM	SCORE	RIF	§106.17, §106.26, §106.27
KISMET-KERNEL-DATA-COMPLETENESS	DATA	RIF	§106.31
KISMET-KERNEL-RATE-RATIO	RATE	RIF, S3	§106.20 (f / n with guards)
KISMET-KERNEL-RATE-DETECTION_ADJUSTED	RATE	RIF	§106.21, §106.36 core formula
KISMET-KERNEL-RATE-PRODUCT	RATE	S3	— (activity × factor)
KISMET-KERNEL-UNIT-CONVERT	UNIT	S3	—