@capsiynau/intelligence-contracts 0.1.1 → 0.1.2

package/README.md

@@ -22,9 +22,21 @@ in the platform.
 
 ## The additive rule
 
-Within a major version, a status, code, scope or capability may be **added**,
-never removed or repurposed. `scripts/check-contract-additive.mjs` fails the
-build on a removal, checked against `contract-baseline.json`.
+Within a major version, a status, code, scope, capability or record field may
+be **added**, never removed or repurposed. `scripts/check-contract-additive.mjs`
+fails the build on a removal, checked against `contract-baseline.json`.
+
+## Records
+
+The execution record (AIOG's audit account of one execution) and the external
+execution report (a product-side fallback reported to AIOG) are defined in
+`src/execution.js` and documented field by field in [SCHEMA.md](./SCHEMA.md).
+Both are contract only as of 18.09.2026: nothing writes them yet. Every
+jurisdiction in them carries its source, so "unknown" is recorded rather than
+left out. An execution is identified at four separate layers - route
+(`provider`), execution platform (`platform`), model (`model_id`,
+`model_version`) and runtime/worker (`runtime_version`, `placement`) - and a
+platform is neither a language nor a jurisdiction; see SCHEMA.md.
 
 ## Usage
 

package/SCHEMA.md

@@ -0,0 +1,214 @@
+# @capsiynau/intelligence-contracts: record schemas
+
+Shapes that are records rather than messages. Today that is the execution
+record and the external execution report, both added on 18.09.2026 (remediation
+plan stage 0.5). Source: `src/execution.js`. Types: `types/index.d.ts`.
+
+## The rules both shapes follow
+
+- **Contract only, for now.** Nothing in the platform writes either shape yet.
+  Populating the execution record is stage 0.2; the endpoint that accepts an
+  external report comes after that. The existing table,
+  `aiog.intelligence_api_execution_records`, is unchanged.
+- **Every key is present.** A value that is not known is `null`, never an
+  omitted key. A record that omits a field looks complete; one that says `null`
+  is honestly incomplete.
+- **Unknown is recorded as unknown.** Every jurisdiction and every serving
+  region is paired with its source: `unknown`, `declared-config` (an operator
+  set it, on the provider's written attestation) or `provider-attested` (the
+  provider's own response said so). `null` goes with `unknown` and only with
+  `unknown`. Nothing is inferred from a provider's name, endpoint host, model
+  name or publishing country, and a `null` jurisdiction never satisfies
+  `uk_only`.
+- **Additive.** `record_version` and `report_version` are integers, currently
+  `1`. A later version may add fields; it may not remove or repurpose one. The
+  validators accept a later version's extra fields. Every field path, nested
+  ones included (`attempts[].provider`), is in `scripts/contract-baseline.json`,
+  and `scripts/check-contract-additive.mjs` fails the build if one disappears.
+- **Audit documents, not job results.** Provider names appear here because an
+  operator, a regulator or a product's compliance team reads these. They are
+  opaque strings: the contract enumerates no provider, no model and no fallback
+  order. A job result still never names its provider (ADR 0006).
+
+## Four identities, kept apart
+
+Corrected 18.09.2026, before the contract shipped. One execution is identified
+at four layers, and no field stands in for another:
+
+    capability + requirements -> AIOG route -> execution platform -> model -> worker
+
+| Layer | Field | What it is | What it is NOT |
+|---|---|---|---|
+| Route | `provider` | AIOG's adapter: the route AIOG chose (`openai-whisper`, `welsh-selfhosted`). An AIOG concept. | The company that ran the work. Several routes can reach one platform. |
+| Platform | `platform` | The execution platform the route called (`pendra`, `openai`). | A language, a jurisdiction, or a model. |
+| Model | `model_id`, `model_version` | The model the platform ran, as it reported executing, and the model's own identity or version: a weights digest, or a version label the platform publishes for that model. | The runtime build. A worker's software version never goes in `model_version`, even when it is the only version on offer. |
+| Runtime / worker | `runtime_version`, `placement.node_id` | The serving runtime or worker software build, and the worker instance that served. | The model's version. The same weights under a new decoder build can score differently, which is why the two are separate. |
+
+**`model_version` and `runtime_version` answer different questions.**
+`model_version` says *which weights ran*: two runs with the same value ran the
+same model. `runtime_version` says *which serving software ran them*. For
+Pendra today that maps as:
+
+| Pendra source | Field |
+|---|---|
+| response `model` | `model_id` |
+| catalogue `gguf_sha256` for that variant | `model_version` |
+| header `x-worker-version` / `x-runtime-version` | `runtime_version` |
+| header `x-worker-id`, `x-worker-name` | `placement.node_id`, `placement.node_name` |
+| header `x-request-id` | `provider_execution_id` |
+
+A value is never moved between rows to fill a gap: a missing `model_version`
+stays `null` rather than borrowing the worker's build number.
+
+**`provider` means the route, and only the route.** It is used that way
+consistently: in the runners (`attempts.push({ provider: provider.name })`), the
+policy observation (`{ id: routeProvider }`), and the `route_provider` column.
+Nobody should read `provider === 'pendra'`. It is not, and will not be: the
+platform has its own field for exactly that reason.
+
+An execution on Pendra therefore reads the same whichever model it ran:
+
+| | Welsh ASR on Pendra | Gemma on Pendra |
+|---|---|---|
+| `provider` | the ASR route | the analysis route |
+| `platform` | `pendra` | `pendra` |
+| `model_id` | the Welsh ASR model id | the Gemma model id |
+| `model_version` | its weights hash, or `null` | its weights hash, or `null` |
+| `runtime_version` | Pendra's worker build | Pendra's worker build |
+| `placement.node_id` | the worker that served | the worker that served |
+| `provider_execution_id` | Pendra's `x-request-id` | Pendra's `x-request-id` |
+| `jurisdiction`, `jurisdiction_source` | as evidenced, else `null` / `unknown` | as evidenced, else `null` / `unknown` |
+
+Gemma needs no special case. It is an ordinary model id on a platform.
+
+### Two invariants
+
+- **A platform is not a language.** Pendra is not "Welsh". Language and
+  specialism belong to the model and the capability.
+- **A platform is not a jurisdiction.** Pendra is not "UK-only". Where work ran
+  is `jurisdiction` and `placement.region`, each with its evidence source. A
+  platform's name, like a route's name, is never that evidence, and a `null`
+  never satisfies `uk_only`.
+
+### Retry and fallback
+
+Defined across all three identities, not by "the provider changed", because one
+platform hosts several models:
+
+| Event | Means | `fallback_scope` |
+|---|---|---|
+| `retry` | Another attempt at the same route, platform and model, after a transient failure. `to_*` repeats `from_*`. | `null` |
+| `fallback` | Execution moved. `fallback_scope` is the widest identity that changed, and must agree with `from_*` / `to_*` (`fallbackScopeOf`). | `model` (same route and platform, another model), `route` (another route onto the same platform), `platform` (another platform) |
+
+A fallback that changes none of the three is a retry recorded under the wrong
+type, and is refused.
+
+## The execution record
+
+AIOG's authoritative account of one intelligence-layer execution. It must be
+sufficient to audit a request without consulting the calling product's
+database. Validate with `validateExecutionRecord(record)`.
+
+"Today" says where each value can come from at `origin/main` on 18.09.2026:
+**column** means the existing row already stores it, **runner** means the
+runner or job holds it but does not store it, **not yet** means nothing
+produces it and stage 0.2 has to.
+
+| Field | Meaning | Today |
+|---|---|---|
+| `record_version` | Schema version, `1` | new |
+| `execution_record_id` | `exr_…` | column |
+| `request_id`, `job_id` | Platform request and job | column |
+| `client_id` | The calling product's credential client | column |
+| `tenant_reference` | The product's organisation, opaque to AIOG | column |
+| `user_reference` | The product's user, when sent | column (writer passes none) |
+| `capability`, `task_class` | What was asked for | column (`task_class` never set) |
+| `requirements.language` | `source_language` as submitted | runner (job request) |
+| `requirements.residency` | A per-request residency requirement | not yet: no request field exists |
+| `requirements.quality_profile` | As submitted | column `quality_profile` |
+| `requirements.diarisation` | `off`, `auto`, `speakers:<n>` | runner (job request) |
+| `requirements.data_class` | As submitted | column `data_class` |
+| `policy_id`, `policy_version` | Citation of the tenant's policy | column (null without a policy) |
+| `effective_policy` | Resolved hard constraints plus `enforced`; `null` when the tenant has no policy | runner can resolve it (`resolveHard`); stored only as `execution_profile.policy_observation` |
+| `eligible_candidates[]` | `provider`, `platform`, `model_id`, `reason`, `jurisdiction`, `jurisdiction_source`. A candidate is a route, a platform AND a model: one platform can offer several models, and policy may admit one and block another | runner can have the route (`candidatesFor`); no adapter declares its platform, and no reason is produced today |
+| `blocked_candidates[]` | `provider`, `platform`, `model_id`, `rule` (the `rejectionReason` vocabulary), `jurisdiction`, `jurisdiction_source` | not yet: policy is not evaluated per candidate before dispatch, and `supports()` returns a bare false with no reason |
+| `selected_provider`, `selected_platform`, `selected_model_id` | The routing decision, before any attempt | runner can have the route (first candidate); not stored |
+| `route_reason` | Why that route (`static-chain` today) | column |
+| `attempts[]` | `provider` (route), `platform` (required), `model_id`, `model_version`, `runtime_version` (worker build), `started_at`, `latency_ms`, `outcome`, `error_code`, `provider_execution_id`, `jurisdiction`, `jurisdiction_source`, `placement` | partial: the runner sees each attempt start (`onAttempt`) but keeps only the last; a failed attempt's error is swallowed inside the registry. Pendra adapters return the model as `execution.runtimeId` (an internal name that pre-dates this contract; it maps to `model_id`) and the worker build as `execution.runtimeVersion` |
+| `attempts[].placement` | `node_id`, `node_name`, `region`, `region_source` | Pendra adapters return node id and name; no provider reports a region |
+| `events[]` | `type` (`retry`, `fallback`), `fallback_scope`, `at`, `from_provider`, `from_platform`, `from_model_id`, `to_provider`, `to_platform`, `to_model_id`, `reason` | not yet: fallbacks happen inside the registry unreported; AIOG has no in-place retry, so `retry` stays empty |
+| `final_provider` | The route whose answer was kept | column `route_provider` on success (on failure that column holds the last attempted) |
+| `final_platform`, `final_model_id`, `final_model_version`, `final_runtime_version` | The platform, model and worker build that served. Required to match a succeeded attempt | not yet: no column; the Pendra adapters return model and worker build, the transcription runner keeps neither |
+| `final_jurisdiction`, `final_jurisdiction_source` | Where the served attempt ran, and how that is known | not yet: no adapter declares one |
+| `provider_execution_id` | The provider's own request id (Pendra's `x-request-id`) | column; the transcription runner fills it when the adapter reports one (stage 0.1) |
+| `prompt_version` | Prompt identity for prompted capabilities | column (writer passes none) |
+| `usage` | `{ unit, amount }` in platform units | column |
+| `provider_cost_internal` | Platform margin analysis, never shown to a caller | column (never populated) |
+| `queue_ms`, `provider_ms`, `total_ms` | Timings | column |
+| `outcome` | A terminal job status | column |
+| `error_code` | Contract error code; required when `outcome` is `failed` | column |
+| `created_at` | ISO 8601 | column |
+
+The validator also refuses contradictions: a `completed` or
+`partially_completed` record with no succeeded attempt or no `final_platform`, a
+`final_provider`, `final_platform` or `final_model_id` that no succeeded attempt
+matches, an attempt with no platform, a failed attempt without an `error_code`,
+a succeeded one with one, an event that does not name both ends in full, a
+retry that changed anything, and a fallback whose `fallback_scope` disagrees
+with what changed.
+
+## The external execution report
+
+While traffic migrates, a product still makes some provider calls itself and
+may fall back on its own side (Capsiynau's direct Pendra path falls back to
+other engines, for example). **A product-side fallback that is not reported to
+AIOG cannot count as canary evidence**, because AIOG's own records would then
+describe a cleaner route than the one the customer got. This is the shape the
+report takes. There is no endpoint for it yet.
+
+Validate with `validateExternalExecutionReport(report)`.
+
+| Field | Meaning |
+|---|---|
+| `report_version` | Schema version, `1` |
+| `report_id` | Chosen by the product; the idempotency key for the report |
+| `tenant_reference` | The product's organisation |
+| `capability` | As in the record |
+| `product_reference` | The product's own job or project id, opaque to AIOG |
+| `job_id`, `request_id` | The AIOG job and request this relates to, or `null` when the work never touched AIOG |
+| `occurred_at` | ISO 8601 |
+| `requirements` | Same shape as the record's |
+| `attempts[]` | Same shape as the record's, product-side providers included |
+| `events[]` | Same shape as the record's; at least one `fallback` is required |
+| `final_provider`, `final_platform`, `final_model_id`, `final_model_version` | What served in the end: the route, the platform and the model |
+| `final_jurisdiction`, `final_jurisdiction_source` | As in the record |
+| `provider_execution_id` | The final provider's request id, when known |
+| `usage`, `outcome`, `error_code` | As in the record |
+
+There is no `client_id`. The reporting product is whoever holds the credential
+the report arrives with; a body that could name its own client could name
+another's.
+
+## What stage 0.2 has to populate
+
+This contract is the target; filling it is stage 0.2. Found while correcting
+the identities on 18.09.2026 and deliberately NOT fixed here:
+
+- **Every adapter declares its platform.** No adapter carries one today, so
+  nothing can fill `platform` yet.
+- **Pendra analysis drops all provenance.** `pendraAnalysis.js` returns text and
+  usage only, discarding the `execution` its runtime call returned: model,
+  worker build, worker and request id never reach a record.
+- **The transcription runner keeps only `provider_execution_id`.**
+  `normaliseResult` carries the model, worker build and placement up; the runner
+  stores none of them.
+- **`model_version` has no producer.** Pendra publishes a weights hash in its
+  catalogue (`gguf_sha256`, read as `contentHash`) but not on an execution
+  response, so `identifiesExecution()` can never be satisfied by a Pendra run.
+- **Policy lists match route labels.** Observation builds candidates as
+  `{ id: routeProvider }`, so a `provider_denylist` naming a platform matches
+  nothing. Platform- and model-level policy needs the candidate identity above.
+- **Usage and cost carry no route, platform or model.** The usage ledger joins
+  to the record by job only, and `provider_cost_internal` is never populated.
+- **Internal names pre-date the contract.** Adapters say `runtimeId` for what the
+  contract calls `model_id`; align them when 0.2 maps one onto the other.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsiynau/intelligence-contracts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Wire contracts between products and the Intelligence Layer: job statuses, error codes, capability names, the segment model, and event schemas. Types and constants only - no implementation, no prompts, no provider names.",
   "type": "module",
   "license": "MIT",
@@ -16,12 +16,14 @@
     "./errors": "./src/errors.js",
     "./capabilities": "./src/capabilities.js",
     "./segments": "./src/segments.js",
-    "./events": "./src/events.js"
+    "./events": "./src/events.js",
+    "./execution": "./src/execution.js"
   },
   "files": [
     "src",
     "types",
     "README.md",
+    "SCHEMA.md",
     "LICENSE"
   ],
   "engines": {
@@ -36,7 +38,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aledprysparry/capsiynau-intelligence.git",
+    "url": "git+https://github.com/aledprysparry/aiog.git",
     "directory": "packages/intelligence-contracts"
   }
 }

package/src/errors.js

@@ -49,6 +49,13 @@ export const ERROR_CODE = Object.freeze({
   RATE_LIMIT_EXCEEDED:            { status: 429, retryable: true,  message: 'Too many requests.' },
   PROVIDER_UNAVAILABLE:           { status: 503, retryable: true,  message: 'The upstream service is temporarily unavailable.' },
   PROVIDER_REJECTED:              { status: 502, retryable: false, message: 'The upstream service rejected the request.' },
+  // Added 18.09.2026. The upstream ACCEPTED the request and answered success,
+  // but the answer cannot be used (a transcript with no timed segments), or it
+  // failed in some other way a retry will not fix. PROVIDER_REJECTED says the
+  // upstream refused, which is untrue here; PROCESSING_FAILED and
+  // PROVIDER_UNAVAILABLE both tell a client to retry, which would resubmit
+  // work that fails the same way and is paid for each time.
+  PROVIDER_FAILED:                { status: 502, retryable: false, message: 'The upstream service failed in a way that retrying will not fix.' },
   PROCESSING_FAILED:              { status: 500, retryable: true,  message: 'Processing failed.' },
   TIMEOUT_EXCEEDED:               { status: 504, retryable: true,  message: 'The operation timed out.' },
   CONFLICT_JOB_TERMINAL:          { status: 409, retryable: false, message: 'The job has already reached a terminal state.' },

package/src/execution.js

@@ -0,0 +1,546 @@
+/**
+ * @capsiynau/intelligence-contracts/execution
+ *
+ * The execution record: AIOG's authoritative account of one intelligence-layer
+ * execution (remediation plan stage 0.5, 18.09.2026). It must be sufficient to
+ * audit a request without consulting the calling product's database, so it
+ * carries who asked, what they required, what policy was in force, which
+ * candidates were eligible or blocked and why, every attempt, every retry and
+ * fallback, what finally served, what it cost and how it ended.
+ *
+ * And the external execution report: the shape a PRODUCT uses to report a
+ * fallback that happened on its own side, outside AIOG, while traffic is
+ * migrating. The rule it exists for: a product-side fallback that is not
+ * reported to AIOG cannot count as canary evidence, because AIOG's records
+ * would then describe a cleaner route than the one customers actually got.
+ *
+ * CONTRACT ONLY. Nothing in the platform writes this shape yet: populating it
+ * is stage 0.2, and the endpoint that accepts a report comes later. The
+ * existing row (`aiog.intelligence_api_execution_records`) keeps its columns;
+ * every field below reuses a column's name where one exists, so filling the
+ * record is a mapping rather than a renaming. See SCHEMA.md for the field
+ * table and where each value comes from today.
+ *
+ * WHY PROVIDER NAMES MAY APPEAR HERE, when ADR 0006 keeps them from callers:
+ * this is an audit document read by an operator, a regulator or the product's
+ * own compliance team, not a job result. Providers are opaque strings; the
+ * contract enumerates none of them, and no model id, prompt or fallback ORDER
+ * is published by it. The record says what happened, never how routing works.
+ *
+ * FOUR IDENTITIES, KEPT APART (18.09.2026). One execution is identified at four
+ * layers, and no field stands in for another:
+ *
+ *   provider         AIOG's route: the adapter that made the call
+ *                    (`openai-whisper`, `welsh-selfhosted`). An AIOG concept.
+ *                    It is NOT the company that ran the work, and it never
+ *                    will be - several routes can reach one platform.
+ *   platform         The execution platform the route called (`pendra`,
+ *                    `openai`). Where the work was sent.
+ *   model_id         The model the platform ran (a Gemma variant, a Welsh ASR
+ *                    model), as the platform reported it executing.
+ *   model_version    The identity or version of the MODEL ITSELF: a digest of
+ *                    its weights (e.g. Pendra's catalogue `gguf_sha256`), or a
+ *                    version label the platform publishes for that model. Two
+ *                    runs with the same model_version ran the same weights.
+ *                    NEVER the serving software: a worker or runtime build
+ *                    (`x-worker-version`, `x-runtime-version`) is
+ *                    runtime_version, and must not be copied here even when it
+ *                    is the only version on offer. Null when the platform gives
+ *                    no model identity - an honest gap, not a reason to borrow
+ *                    another layer's number.
+ *   runtime_version  The serving runtime or worker BUILD. Not the model's
+ *                    version: the same weights under a new decoder build can
+ *                    score differently, which is why it is kept separately.
+ *   placement        The worker INSTANCE that served (`node_id`), and where it
+ *                    ran as far as is evidenced.
+ *
+ * So an execution on Pendra reads `provider: <route>, platform: 'pendra',
+ * model_id: <model>`, whether the model is Gemma or Welsh ASR. Two invariants
+ * follow, and nothing in this contract may encode either assumption:
+ *
+ *   A PLATFORM IS NOT A LANGUAGE. Pendra is not "Welsh": language and
+ *   specialism belong to the model and the capability, not to the platform.
+ *
+ *   A PLATFORM IS NOT A JURISDICTION. Pendra is not "UK-only": where work ran
+ *   is `jurisdiction` / `placement.region` with their evidence sources, and a
+ *   platform's name, like a route's name, is never that evidence.
+ *
+ * UNKNOWN IS RECORDED AS UNKNOWN. Wherever the record carries a jurisdiction
+ * or a serving region it carries the SOURCE beside it: `unknown`,
+ * `declared-config` (an operator set it, on a provider's written attestation)
+ * or `provider-attested` (the provider's own response said so). A null with
+ * source `unknown` is a finding; a missing field would be a gap nobody can
+ * tell from one. Nothing here may be inferred from a provider's name, host,
+ * model or publishing country, and a null never satisfies `uk_only`.
+ *
+ * ADDITIVE, like everything in this package. `record_version` and
+ * `report_version` are integers; a later version may add fields and must not
+ * remove or repurpose one, and a validator for version N accepts a record of a
+ * later version whose extra fields it does not know. The field lists are
+ * guarded by scripts/check-contract-additive.mjs.
+ */
+import { ALL_CAPABILITIES } from './capabilities.js'
+import { TERMINAL_STATUSES, JOB_STATUS } from './jobs.js'
+import { isValidDiarisation } from './segments.js'
+
+export const EXECUTION_RECORD_VERSION = 1
+export const EXTERNAL_EXECUTION_REPORT_VERSION = 1
+
+/** How one attempt ended. A skipped candidate is not an attempt. */
+export const ATTEMPT_OUTCOME = Object.freeze({
+  SUCCEEDED: 'succeeded',
+  FAILED: 'failed',
+})
+
+/**
+ * Something that happened BETWEEN attempts, with the identity it moved from and
+ * to. Both carry the reason, which is normally the error code of the attempt
+ * that prompted them.
+ *
+ *   retry     another attempt at the SAME route, platform and model, after a
+ *             transient failure. `to_*` repeats `from_*`.
+ *   fallback  execution moved to a different identity. Which kind of move is
+ *             `fallback_scope`, below - "the provider changed" is not the
+ *             definition, because a platform hosts several models and a model
+ *             change on one platform is a fallback too.
+ */
+export const EXECUTION_EVENT_TYPE = Object.freeze({
+  RETRY: 'retry',
+  FALLBACK: 'fallback',
+})
+
+/**
+ * The widest identity a fallback changed. Derived from `from_*` / `to_*` and
+ * checked against them, so the label cannot contradict the evidence:
+ *
+ *   platform  a different execution platform (and so, normally, a different route)
+ *   route     a different AIOG route onto the same platform
+ *   model     the same route and platform, a different model
+ *
+ * A retry carries `fallback_scope: null`. A fallback that changes none of the
+ * three is a retry recorded under the wrong type, and is refused.
+ */
+export const FALLBACK_SCOPE = Object.freeze({
+  MODEL: 'model',
+  ROUTE: 'route',
+  PLATFORM: 'platform',
+})
+
+/**
+ * Where a jurisdiction or region value came from. `unknown` pairs with null
+ * and only with null: a value with no source is a guess, and a source with no
+ * value is a contradiction.
+ */
+export const JURISDICTION_SOURCE = Object.freeze({
+  UNKNOWN: 'unknown',
+  DECLARED_CONFIG: 'declared-config',
+  PROVIDER_ATTESTED: 'provider-attested',
+})
+
+/** What the caller required. Every key present; null where it was not stated. */
+export const EXECUTION_REQUIREMENT_KEYS = Object.freeze([
+  'language', 'residency', 'quality_profile', 'diarisation', 'data_class',
+])
+
+/**
+ * The policy in force, resolved for this execution's data class. Named as the
+ * policy resolver names its hard constraints, plus `enforced`, which records
+ * whether anything actually gated on it (observe-only records false).
+ */
+export const EXECUTION_POLICY_KEYS = Object.freeze([
+  'enforced', 'residency', 'external_providers', 'training_use', 'data_class',
+  'on_unsatisfiable', 'provider_allowlist', 'provider_denylist',
+])
+
+/**
+ * A candidate is a route, a platform AND a model, because one platform can
+ * offer several models for the same requirement and policy may admit one and
+ * block another. `model_id` is null only where a route has not resolved a
+ * model at candidate time.
+ */
+const CANDIDATE_IDENTITY_KEYS = Object.freeze(['provider', 'platform', 'model_id'])
+
+/** An eligible candidate, why it was eligible, and where it runs as far as is known. */
+export const ELIGIBLE_CANDIDATE_KEYS = Object.freeze([
+  ...CANDIDATE_IDENTITY_KEYS, 'reason', 'jurisdiction', 'jurisdiction_source',
+])
+
+/** A blocked candidate and the rule that blocked it (`residency_undeclared`...). */
+export const BLOCKED_CANDIDATE_KEYS = Object.freeze([
+  ...CANDIDATE_IDENTITY_KEYS, 'rule', 'jurisdiction', 'jurisdiction_source',
+])
+
+/**
+ * Where one attempt was served, as evidenced. A worker id with no serving
+ * region is recorded exactly so: `region: null`, `region_source: 'unknown'`.
+ */
+export const EXECUTION_PLACEMENT_KEYS = Object.freeze(['node_id', 'node_name', 'region', 'region_source'])
+
+/** One call, through one route, to one model on one platform. */
+export const EXECUTION_ATTEMPT_KEYS = Object.freeze([
+  'provider', 'platform', 'model_id', 'model_version', 'runtime_version',
+  'started_at', 'latency_ms', 'outcome', 'error_code', 'provider_execution_id',
+  'jurisdiction', 'jurisdiction_source', 'placement',
+])
+
+export const EXECUTION_EVENT_KEYS = Object.freeze([
+  'type', 'fallback_scope', 'at',
+  'from_provider', 'from_platform', 'from_model_id',
+  'to_provider', 'to_platform', 'to_model_id',
+  'reason',
+])
+
+/** Every top-level key of the execution record, version 1. */
+export const EXECUTION_RECORD_KEYS = Object.freeze([
+  'record_version', 'execution_record_id', 'request_id', 'job_id',
+  'client_id', 'tenant_reference', 'user_reference',
+  'capability', 'task_class', 'requirements',
+  'policy_id', 'policy_version', 'effective_policy',
+  'eligible_candidates', 'blocked_candidates',
+  'selected_provider', 'selected_platform', 'selected_model_id', 'route_reason',
+  'attempts', 'events',
+  'final_provider', 'final_platform', 'final_model_id', 'final_model_version', 'final_runtime_version',
+  'final_jurisdiction', 'final_jurisdiction_source', 'provider_execution_id',
+  'prompt_version', 'usage', 'provider_cost_internal',
+  'queue_ms', 'provider_ms', 'total_ms',
+  'outcome', 'error_code', 'created_at',
+])
+
+/** Keys that must be present AND non-null. The rest may be an honest null. */
+const RECORD_NON_NULL = Object.freeze([
+  'record_version', 'execution_record_id', 'client_id', 'tenant_reference', 'capability',
+  'requirements', 'eligible_candidates', 'blocked_candidates', 'route_reason',
+  'attempts', 'events', 'final_jurisdiction_source', 'outcome', 'created_at',
+])
+
+/**
+ * Every top-level key of an external execution report, version 1. There is no
+ * `client_id`: the reporting product is whoever holds the credential it
+ * reports with, and a body that named its own client could name another's.
+ */
+export const EXTERNAL_EXECUTION_REPORT_KEYS = Object.freeze([
+  'report_version', 'report_id', 'tenant_reference', 'capability',
+  'product_reference', 'job_id', 'request_id', 'occurred_at',
+  'requirements', 'attempts', 'events',
+  'final_provider', 'final_platform', 'final_model_id', 'final_model_version',
+  'final_jurisdiction', 'final_jurisdiction_source',
+  'provider_execution_id', 'usage', 'outcome', 'error_code',
+])
+
+const REPORT_NON_NULL = Object.freeze([
+  'report_version', 'report_id', 'tenant_reference', 'capability', 'product_reference',
+  'occurred_at', 'requirements', 'attempts', 'events', 'final_jurisdiction_source', 'outcome',
+])
+
+/**
+ * Dotted paths, `[]` marking an array of objects (`attempts[].provider`): the
+ * unit the additive guard compares, so removing a nested field fails the build
+ * exactly as removing a top-level one does.
+ */
+function fieldPaths(topKeys, objects = {}, arrays = {}) {
+  const paths = []
+  for (const key of topKeys) {
+    paths.push(key)
+    for (const child of objects[key] || []) paths.push(`${key}.${child}`)
+    for (const child of arrays[key] || []) {
+      paths.push(`${key}[].${child}`)
+      if (key === 'attempts' && child === 'placement') {
+        for (const leaf of EXECUTION_PLACEMENT_KEYS) paths.push(`${key}[].${child}.${leaf}`)
+      }
+    }
+  }
+  return Object.freeze(paths.sort())
+}
+
+/** Every field of the execution record, as a sorted list of paths. */
+export const EXECUTION_RECORD_FIELDS = fieldPaths(EXECUTION_RECORD_KEYS, {
+  requirements: EXECUTION_REQUIREMENT_KEYS,
+  effective_policy: EXECUTION_POLICY_KEYS,
+}, {
+  eligible_candidates: ELIGIBLE_CANDIDATE_KEYS,
+  blocked_candidates: BLOCKED_CANDIDATE_KEYS,
+  attempts: EXECUTION_ATTEMPT_KEYS,
+  events: EXECUTION_EVENT_KEYS,
+})
+
+/** Every field of the external execution report, as a sorted list of paths. */
+export const EXTERNAL_EXECUTION_REPORT_FIELDS = fieldPaths(EXTERNAL_EXECUTION_REPORT_KEYS, {
+  requirements: EXECUTION_REQUIREMENT_KEYS,
+}, {
+  attempts: EXECUTION_ATTEMPT_KEYS,
+  events: EXECUTION_EVENT_KEYS,
+})
+
+// ── Shared checks ───────────────────────────────────────────────────────────
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const isText = (v) => typeof v === 'string' && v.trim().length > 0
+const isInstant = (v) => typeof v === 'string' && Number.isFinite(Date.parse(v))
+const isQuantity = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0
+
+const SOURCES = Object.values(JURISDICTION_SOURCE)
+
+/**
+ * A value and its source, checked together. Null pairs with `unknown`; a
+ * value pairs with a source that is not `unknown`.
+ */
+function checkSourced(obj, valueKey, sourceKey, where, problems) {
+  const value = obj[valueKey]
+  const source = obj[sourceKey]
+  if (source === undefined) return
+  if (!SOURCES.includes(source)) return problems.push(`${where}${sourceKey} must be one of ${SOURCES.join(', ')}`)
+  if (value != null && !isText(value)) return problems.push(`${where}${valueKey} must be a string or null`)
+  if (value == null && source !== JURISDICTION_SOURCE.UNKNOWN) {
+    problems.push(`${where}${valueKey} is null, so ${sourceKey} must be unknown`)
+  }
+  if (value != null && source === JURISDICTION_SOURCE.UNKNOWN) {
+    problems.push(`${where}${valueKey} has a value, so ${sourceKey} cannot be unknown`)
+  }
+}
+
+function requireKeys(obj, keys, nonNull, where, problems) {
+  for (const key of keys) {
+    if (obj[key] === undefined) problems.push(`${where}missing ${key}`)
+    else if (obj[key] === null && nonNull.includes(key)) problems.push(`${where}${key} must not be null`)
+  }
+}
+
+function checkRequirements(req, problems) {
+  if (!isObject(req)) return problems.push('requirements must be an object')
+  requireKeys(req, EXECUTION_REQUIREMENT_KEYS, [], 'requirements: ', problems)
+  for (const key of EXECUTION_REQUIREMENT_KEYS) {
+    if (req[key] != null && typeof req[key] !== 'string') problems.push(`requirements: ${key} must be a string or null`)
+  }
+  if (req.diarisation != null && !isValidDiarisation(req.diarisation)) {
+    problems.push('requirements: diarisation is not off, auto or speakers:<n>')
+  }
+}
+
+function checkAttempts(attempts, problems) {
+  if (!Array.isArray(attempts)) return problems.push('attempts must be an array')
+  attempts.forEach((a, i) => {
+    const at = `attempts[${i}]: `
+    if (!isObject(a)) return problems.push(`${at}not an object`)
+    requireKeys(a, EXECUTION_ATTEMPT_KEYS, ['provider', 'platform', 'started_at', 'outcome', 'jurisdiction_source', 'placement'], at, problems)
+    checkSourced(a, 'jurisdiction', 'jurisdiction_source', at, problems)
+    // The route and the platform are always known: AIOG chose the one and the
+    // one it chose names the other. The model and its versions may honestly
+    // not be.
+    for (const key of ['provider', 'platform']) {
+      if (a[key] != null && !isText(a[key])) problems.push(`${at}${key} must be a non-empty string`)
+    }
+    for (const key of ['model_id', 'model_version', 'runtime_version']) {
+      if (a[key] != null && !isText(a[key])) problems.push(`${at}${key} must be a non-empty string or null`)
+    }
+    if (a.started_at != null && !isInstant(a.started_at)) problems.push(`${at}started_at must be an ISO 8601 instant`)
+    if (a.latency_ms != null && !isQuantity(a.latency_ms)) problems.push(`${at}latency_ms must be a non-negative number or null`)
+    if (a.outcome != null && !Object.values(ATTEMPT_OUTCOME).includes(a.outcome)) problems.push(`${at}unknown outcome ${a.outcome}`)
+    // A failure with no code cannot be audited; a success with one is a contradiction.
+    if (a.outcome === ATTEMPT_OUTCOME.FAILED && !isText(a.error_code)) problems.push(`${at}a failed attempt needs an error_code`)
+    if (a.outcome === ATTEMPT_OUTCOME.SUCCEEDED && a.error_code != null) problems.push(`${at}a succeeded attempt carries no error_code`)
+    if (a.placement != null) {
+      if (!isObject(a.placement)) problems.push(`${at}placement must be an object`)
+      else {
+        requireKeys(a.placement, EXECUTION_PLACEMENT_KEYS, ['region_source'], `${at}placement: `, problems)
+        checkSourced(a.placement, 'region', 'region_source', `${at}placement: `, problems)
+      }
+    }
+  })
+}
+
+/**
+ * The widest identity that differs between the two ends of an event, or null
+ * when none does. Platform outranks route outranks model.
+ */
+export function fallbackScopeOf(e) {
+  if (e?.from_platform !== e?.to_platform) return FALLBACK_SCOPE.PLATFORM
+  if (e?.from_provider !== e?.to_provider) return FALLBACK_SCOPE.ROUTE
+  if ((e?.from_model_id ?? null) !== (e?.to_model_id ?? null)) return FALLBACK_SCOPE.MODEL
+  return null
+}
+
+function checkEvents(events, problems) {
+  if (!Array.isArray(events)) return problems.push('events must be an array')
+  events.forEach((e, i) => {
+    const at = `events[${i}]: `
+    if (!isObject(e)) return problems.push(`${at}not an object`)
+    requireKeys(e, EXECUTION_EVENT_KEYS, ['type', 'at', 'from_provider', 'from_platform', 'reason'], at, problems)
+    if (e.type != null && !Object.values(EXECUTION_EVENT_TYPE).includes(e.type)) problems.push(`${at}unknown type ${e.type}`)
+    if (e.at != null && !isInstant(e.at)) problems.push(`${at}at must be an ISO 8601 instant`)
+
+    // BOTH ENDS NAMED IN FULL. An event that says where it came from and not
+    // where it went is half a route; the audit needs both halves to explain it.
+    for (const end of ['from', 'to']) {
+      for (const key of ['provider', 'platform']) {
+        if (!isText(e[`${end}_${key}`])) problems.push(`${at}${end}_${key} must be a non-empty string`)
+      }
+      const model = e[`${end}_model_id`]
+      if (model != null && !isText(model)) problems.push(`${at}${end}_model_id must be a non-empty string or null`)
+    }
+
+    const scope = fallbackScopeOf(e)
+    if (e.type === EXECUTION_EVENT_TYPE.RETRY) {
+      if (scope !== null) problems.push(`${at}a retry repeats the same route, platform and model; this one changed ${scope}`)
+      if (e.fallback_scope != null) problems.push(`${at}a retry carries no fallback_scope`)
+    }
+    if (e.type === EXECUTION_EVENT_TYPE.FALLBACK) {
+      if (scope === null) problems.push(`${at}a fallback that changes no route, platform or model is a retry`)
+      else if (e.fallback_scope !== scope) {
+        problems.push(`${at}fallback_scope must be ${scope}, the widest identity that changed`)
+      }
+    }
+  })
+}
+
+function checkCandidates(list, keys, name, problems) {
+  if (!Array.isArray(list)) return problems.push(`${name} must be an array`)
+  // `reason` for an eligible candidate, `rule` for a blocked one.
+  const because = keys.find((k) => k === 'reason' || k === 'rule')
+  list.forEach((c, i) => {
+    const at = `${name}[${i}]: `
+    if (!isObject(c)) return problems.push(`${at}not an object`)
+    requireKeys(c, keys, ['jurisdiction_source'], at, problems)
+    for (const key of ['provider', 'platform', because]) {
+      if (!isText(c[key])) problems.push(`${at}${key} must be a non-empty string`)
+    }
+    if (c.model_id != null && !isText(c.model_id)) problems.push(`${at}model_id must be a non-empty string or null`)
+    checkSourced(c, 'jurisdiction', 'jurisdiction_source', at, problems)
+  })
+}
+
+/** Checks both shapes share: capability, outcome and its code, usage, the served provider. */
+function checkEnding(doc, problems) {
+  checkSourced(doc, 'final_jurisdiction', 'final_jurisdiction_source', '', problems)
+  if (doc.capability != null && !ALL_CAPABILITIES.includes(doc.capability)) problems.push(`unknown capability ${doc.capability}`)
+  if (doc.outcome != null && !TERMINAL_STATUSES.includes(doc.outcome)) {
+    problems.push(`outcome must be one of ${TERMINAL_STATUSES.join(', ')}`)
+  }
+  if (doc.outcome === JOB_STATUS.FAILED && !isText(doc.error_code)) problems.push('a failed execution needs an error_code')
+  if (doc.usage != null && (!isObject(doc.usage) || !isText(doc.usage.unit) || !isQuantity(doc.usage.amount))) {
+    problems.push('usage must be null or { unit, amount } with a non-negative amount')
+  }
+  // WHAT SERVED MUST BE AN ATTEMPT THAT SUCCEEDED, at every identity layer. A
+  // record naming a final provider, platform or model that nothing in its own
+  // attempt list succeeded with is describing a route that did not happen - and
+  // "succeeded on Pendra" is not "succeeded with THIS model on Pendra".
+  const served = Array.isArray(doc.attempts)
+    ? doc.attempts.filter((a) => a?.outcome === ATTEMPT_OUTCOME.SUCCEEDED)
+    : []
+  const resultBearing = doc.outcome === JOB_STATUS.COMPLETED || doc.outcome === JOB_STATUS.PARTIALLY_COMPLETED
+  if (resultBearing && served.length === 0) problems.push(`a ${doc.outcome} execution needs a succeeded attempt`)
+  if (doc.final_provider != null) {
+    const byProvider = served.filter((a) => a.provider === doc.final_provider)
+    if (byProvider.length === 0) problems.push('final_provider is not the provider of any succeeded attempt')
+    else {
+      const byPlatform = byProvider.filter((a) => a.platform === doc.final_platform)
+      if (byPlatform.length === 0) problems.push('final_platform is not the platform of the succeeded attempt it names')
+      else if (doc.final_model_id != null && !byPlatform.some((a) => a.model_id === doc.final_model_id)) {
+        problems.push('final_model_id is not the model of the succeeded attempt it names')
+      }
+    }
+  }
+  if (resultBearing && doc.final_provider == null) problems.push(`a ${doc.outcome} execution names its final_provider`)
+  if (resultBearing && doc.final_platform == null) problems.push(`a ${doc.outcome} execution names its final_platform`)
+  for (const key of ['final_platform', 'final_model_id', 'final_model_version']) {
+    if (doc[key] != null && !isText(doc[key])) problems.push(`${key} must be a non-empty string or null`)
+  }
+}
+
+function checkVersion(value, name, problems) {
+  if (value != null && !(Number.isInteger(value) && value >= 1)) problems.push(`${name} must be a positive integer`)
+}
+
+// ── Validators ──────────────────────────────────────────────────────────────
+
+/**
+ * Structural check on an execution record.
+ *
+ * Every key is PRESENT, with null where the value is honestly unknown: a
+ * record that omits a field looks complete, and one that says null is
+ * honestly incomplete. Unknown extra keys are accepted, so a record of a later
+ * version still validates here.
+ *
+ * @param {unknown} record
+ * @returns {{ valid: boolean, problems: string[] }}
+ */
+export function validateExecutionRecord(record) {
+  if (!isObject(record)) return { valid: false, problems: ['execution record is not an object'] }
+  const problems = []
+  requireKeys(record, EXECUTION_RECORD_KEYS, RECORD_NON_NULL, '', problems)
+  checkVersion(record.record_version, 'record_version', problems)
+  for (const key of ['execution_record_id', 'client_id', 'tenant_reference', 'route_reason']) {
+    if (record[key] != null && !isText(record[key])) problems.push(`${key} must be a non-empty string`)
+  }
+  if (record.created_at != null && !isInstant(record.created_at)) problems.push('created_at must be an ISO 8601 instant')
+  if (record.requirements != null) checkRequirements(record.requirements, problems)
+  if (record.effective_policy != null) {
+    if (!isObject(record.effective_policy)) problems.push('effective_policy must be an object or null')
+    else {
+      requireKeys(record.effective_policy, EXECUTION_POLICY_KEYS, ['enforced'], 'effective_policy: ', problems)
+      if (typeof record.effective_policy.enforced !== 'boolean') problems.push('effective_policy: enforced must be a boolean')
+    }
+  }
+  if (record.eligible_candidates != null) checkCandidates(record.eligible_candidates, ELIGIBLE_CANDIDATE_KEYS, 'eligible_candidates', problems)
+  if (record.blocked_candidates != null) checkCandidates(record.blocked_candidates, BLOCKED_CANDIDATE_KEYS, 'blocked_candidates', problems)
+  if (record.attempts != null) checkAttempts(record.attempts, problems)
+  if (record.events != null) checkEvents(record.events, problems)
+  for (const key of ['provider_cost_internal', 'queue_ms', 'provider_ms', 'total_ms']) {
+    if (record[key] != null && !isQuantity(record[key])) problems.push(`${key} must be a non-negative number or null`)
+  }
+  checkEnding(record, problems)
+  return { valid: problems.length === 0, problems }
+}
+
+/**
+ * Structural check on an external execution report.
+ *
+ * A report exists to describe a product-side FALLBACK, so one without a
+ * fallback event is refused: it would add a record to the canary evidence
+ * that says nothing the evidence needs.
+ *
+ * @param {unknown} report
+ * @returns {{ valid: boolean, problems: string[] }}
+ */
+export function validateExternalExecutionReport(report) {
+  if (!isObject(report)) return { valid: false, problems: ['external execution report is not an object'] }
+  const problems = []
+  requireKeys(report, EXTERNAL_EXECUTION_REPORT_KEYS, REPORT_NON_NULL, '', problems)
+  checkVersion(report.report_version, 'report_version', problems)
+  for (const key of ['report_id', 'tenant_reference', 'product_reference']) {
+    if (report[key] != null && !isText(report[key])) problems.push(`${key} must be a non-empty string`)
+  }
+  if (report.occurred_at != null && !isInstant(report.occurred_at)) problems.push('occurred_at must be an ISO 8601 instant')
+  if (report.requirements != null) checkRequirements(report.requirements, problems)
+  if (report.attempts != null) checkAttempts(report.attempts, problems)
+  if (report.events != null) {
+    checkEvents(report.events, problems)
+    if (Array.isArray(report.events) && !report.events.some((e) => e?.type === EXECUTION_EVENT_TYPE.FALLBACK)) {
+      problems.push('a report describes at least one fallback event')
+    }
+  }
+  checkEnding(report, problems)
+  return { valid: problems.length === 0, problems }
+}
+
+export default {
+  EXECUTION_RECORD_VERSION,
+  EXTERNAL_EXECUTION_REPORT_VERSION,
+  ATTEMPT_OUTCOME,
+  EXECUTION_EVENT_TYPE,
+  FALLBACK_SCOPE,
+  JURISDICTION_SOURCE,
+  EXECUTION_REQUIREMENT_KEYS,
+  EXECUTION_POLICY_KEYS,
+  ELIGIBLE_CANDIDATE_KEYS,
+  BLOCKED_CANDIDATE_KEYS,
+  EXECUTION_PLACEMENT_KEYS,
+  EXECUTION_ATTEMPT_KEYS,
+  EXECUTION_EVENT_KEYS,
+  EXECUTION_RECORD_KEYS,
+  EXTERNAL_EXECUTION_REPORT_KEYS,
+  EXECUTION_RECORD_FIELDS,
+  EXTERNAL_EXECUTION_REPORT_FIELDS,
+  fallbackScopeOf,
+  validateExecutionRecord,
+  validateExternalExecutionReport,
+}

package/src/index.js

@@ -18,3 +18,4 @@ export * from './errors.js'
 export * from './capabilities.js'
 export * from './segments.js'
 export * from './events.js'
+export * from './execution.js'

package/types/index.d.ts

@@ -93,3 +93,196 @@ export declare const REQUIRED_REVIEW_EVENT_KEYS: readonly string[]
 /** The family an event type belongs to ("job", "review"), from its own prefix. */
 export declare function eventFamily(type: unknown): string | null
 export declare function validateEvent(event: unknown): ValidationResult
+
+// ── Execution record and external execution report (stage 0.5, 18.09.2026) ──
+// Audit shapes, not job results. Every key is present; null means "not known",
+// never "not recorded". See SCHEMA.md.
+
+export type AttemptOutcome = 'succeeded' | 'failed'
+export type ExecutionEventType = 'retry' | 'fallback'
+/** The widest identity a fallback changed: platform > route > model. */
+export type FallbackScope = 'model' | 'route' | 'platform'
+/** Where a jurisdiction or region came from. 'unknown' pairs with null, only. */
+export type JurisdictionSource = 'unknown' | 'declared-config' | 'provider-attested'
+
+export interface ExecutionPlacement {
+  node_id: string | null
+  node_name: string | null
+  region: string | null
+  region_source: JurisdictionSource
+}
+
+export interface ExecutionRequirements {
+  language: string | null
+  residency: string | null
+  quality_profile: string | null
+  diarisation: string | null
+  data_class: string | null
+}
+
+export interface EffectivePolicy {
+  /** Whether anything gated on the policy. Observe-only records false. */
+  enforced: boolean
+  residency: string | null
+  external_providers: string | null
+  training_use: string | null
+  data_class: string | null
+  on_unsatisfiable: string | null
+  provider_allowlist: string[] | null
+  provider_denylist: string[] | null
+}
+
+/**
+ * Four identities, kept apart (SCHEMA.md):
+ *   provider        AIOG's route/adapter - never the company that ran the work
+ *   platform        the execution platform, e.g. 'pendra'
+ *   model_id        the model the platform ran
+ *   runtime_version the serving runtime/worker BUILD, not the model's version
+ * A platform is neither a language nor a jurisdiction.
+ */
+export interface ExecutionAttempt {
+  /** AIOG's route: the adapter that made the call. */
+  provider: string
+  /** The execution platform the route called. */
+  platform: string
+  /** The model the platform ran, as it reported executing. */
+  model_id: string | null
+  /**
+   * The model's own identity or version: a weights digest or a model version
+   * label the platform publishes. Never the worker/runtime build, which is
+   * `runtime_version`. Null when the platform gives no model identity.
+   */
+  model_version: string | null
+  /** The serving runtime or worker build. Not the model's version. */
+  runtime_version: string | null
+  started_at: string
+  latency_ms: number | null
+  outcome: AttemptOutcome
+  /** Required when the attempt failed, null when it succeeded. */
+  error_code: string | null
+  /** The provider's own id for the request, e.g. Pendra's x-request-id. */
+  provider_execution_id: string | null
+  jurisdiction: string | null
+  jurisdiction_source: JurisdictionSource
+  placement: ExecutionPlacement
+}
+
+/**
+ * A retry repeats the same route, platform and model (`to_*` equals `from_*`,
+ * `fallback_scope` null). A fallback changes at least one, and
+ * `fallback_scope` names the widest that changed.
+ */
+export interface ExecutionEvent {
+  type: ExecutionEventType
+  fallback_scope: FallbackScope | null
+  at: string
+  from_provider: string
+  from_platform: string
+  from_model_id: string | null
+  to_provider: string
+  to_platform: string
+  to_model_id: string | null
+  reason: string
+}
+
+/** A route, a platform and a model: one platform can offer several models. */
+export interface ExecutionCandidateIdentity {
+  provider: string
+  platform: string
+  model_id: string | null
+}
+
+export interface ExecutionUsage { unit: string; amount: number; [extra: string]: unknown }
+
+export interface ExecutionRecord {
+  record_version: number
+  execution_record_id: string
+  request_id: string | null
+  job_id: string | null
+  client_id: string
+  tenant_reference: string
+  user_reference: string | null
+  capability: Capability
+  task_class: string | null
+  requirements: ExecutionRequirements
+  policy_id: string | null
+  policy_version: string | null
+  effective_policy: EffectivePolicy | null
+  eligible_candidates: Array<ExecutionCandidateIdentity & { reason: string; jurisdiction: string | null; jurisdiction_source: JurisdictionSource }>
+  blocked_candidates: Array<ExecutionCandidateIdentity & { rule: string; jurisdiction: string | null; jurisdiction_source: JurisdictionSource }>
+  selected_provider: string | null
+  selected_platform: string | null
+  selected_model_id: string | null
+  route_reason: string
+  attempts: ExecutionAttempt[]
+  events: ExecutionEvent[]
+  final_provider: string | null
+  final_platform: string | null
+  final_model_id: string | null
+  final_model_version: string | null
+  final_runtime_version: string | null
+  final_jurisdiction: string | null
+  final_jurisdiction_source: JurisdictionSource
+  provider_execution_id: string | null
+  prompt_version: string | null
+  usage: ExecutionUsage | null
+  provider_cost_internal: number | null
+  queue_ms: number | null
+  provider_ms: number | null
+  total_ms: number | null
+  outcome: JobStatus
+  error_code: string | null
+  created_at: string
+}
+
+/** A product-side fallback, reported to AIOG. The client is the credential's. */
+export interface ExternalExecutionReport {
+  report_version: number
+  report_id: string
+  tenant_reference: string
+  capability: Capability
+  product_reference: string
+  job_id: string | null
+  request_id: string | null
+  occurred_at: string
+  requirements: ExecutionRequirements
+  attempts: ExecutionAttempt[]
+  /** At least one event of type 'fallback'. */
+  events: ExecutionEvent[]
+  final_provider: string | null
+  final_platform: string | null
+  final_model_id: string | null
+  final_model_version: string | null
+  final_jurisdiction: string | null
+  final_jurisdiction_source: JurisdictionSource
+  provider_execution_id: string | null
+  usage: ExecutionUsage | null
+  outcome: JobStatus
+  error_code: string | null
+}
+
+export declare const EXECUTION_RECORD_VERSION: number
+export declare const EXTERNAL_EXECUTION_REPORT_VERSION: number
+export declare const ATTEMPT_OUTCOME: Readonly<{ SUCCEEDED: 'succeeded'; FAILED: 'failed' }>
+export declare const EXECUTION_EVENT_TYPE: Readonly<{ RETRY: 'retry'; FALLBACK: 'fallback' }>
+export declare const FALLBACK_SCOPE: Readonly<{ MODEL: 'model'; ROUTE: 'route'; PLATFORM: 'platform' }>
+export declare const JURISDICTION_SOURCE: Readonly<{
+  UNKNOWN: 'unknown'; DECLARED_CONFIG: 'declared-config'; PROVIDER_ATTESTED: 'provider-attested'
+}>
+export declare const EXECUTION_PLACEMENT_KEYS: readonly string[]
+export declare const EXECUTION_REQUIREMENT_KEYS: readonly string[]
+export declare const EXECUTION_POLICY_KEYS: readonly string[]
+export declare const ELIGIBLE_CANDIDATE_KEYS: readonly string[]
+export declare const BLOCKED_CANDIDATE_KEYS: readonly string[]
+export declare const EXECUTION_ATTEMPT_KEYS: readonly string[]
+export declare const EXECUTION_EVENT_KEYS: readonly string[]
+export declare const EXECUTION_RECORD_KEYS: readonly string[]
+export declare const EXTERNAL_EXECUTION_REPORT_KEYS: readonly string[]
+/** Sorted field paths, nested ones as `attempts[].provider`. Guarded additive. */
+export declare const EXECUTION_RECORD_FIELDS: readonly string[]
+export declare const EXTERNAL_EXECUTION_REPORT_FIELDS: readonly string[]
+/** The widest identity that differs between an event's two ends, or null. */
+export declare function fallbackScopeOf(event: Pick<ExecutionEvent,
+  'from_provider' | 'from_platform' | 'from_model_id' | 'to_provider' | 'to_platform' | 'to_model_id'>): FallbackScope | null
+export declare function validateExecutionRecord(record: unknown): ValidationResult
+export declare function validateExternalExecutionReport(report: unknown): ValidationResult