Metadata-Version: 2.5
Name: vyral
Version: 0.1.1
Summary: Python-first local runtime for the portable Vyral contract
Project-URL: Homepage, https://github.com/univeracity/vyral
Project-URL: Repository, https://github.com/univeracity/vyral
Project-URL: Issues, https://github.com/univeracity/vyral/issues
Author: Jeremy Dixon
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction, and
        distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by the copyright
        owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other entities
        that control, are controlled by, or are under common control with that entity.
        For the purposes of this definition, "control" means (i) the power, direct or
        indirect, to cause the direction or management of such entity, whether by
        contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
        outstanding shares, or (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, including
        but not limited to software source code, documentation source, and configuration
        files.
        
        "Object" form shall mean any form resulting from mechanical transformation or
        translation of a Source form, including but not limited to compiled object code,
        generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form,
        made available under the License, as indicated by a copyright notice that is
        included in or attached to the work (an example is provided in the Appendix
        below).
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that
        is based on (or derived from) the Work and for which the editorial revisions,
        annotations, elaborations, or other modifications represent, as a whole, an
        original work of authorship. For the purposes of this License, Derivative Works
        shall not include works that remain separable from, or merely link (or bind by
        name) to the interfaces of, the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including the original
        version of the Work and any modifications or additions to that Work or
        Derivative Works thereof, that is intentionally submitted to Licensor for
        inclusion in the Work by the copyright owner or by an individual or Legal Entity
        authorized to submit on behalf of the copyright owner. For the purposes of this
        definition, "submitted" means any form of electronic, verbal, or written
        communication sent to the Licensor or its representatives, including but not
        limited to communication on electronic mailing lists, source code control
        systems, and issue tracking systems that are managed by, or on behalf of, the
        Licensor for the purpose of discussing and improving the Work, but excluding
        communication that is conspicuously marked or otherwise designated in writing by
        the copyright owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
        of whom a Contribution has been received by Licensor and subsequently
        incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable copyright license to
        reproduce, prepare Derivative Works of, publicly display, publicly perform,
        sublicense, and distribute the Work and such Derivative Works in Source or
        Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of this License,
        each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
        no-charge, royalty-free, irrevocable (except as stated in this section) patent
        license to make, have made, use, offer to sell, sell, import, and otherwise
        transfer the Work, where such license applies only to those patent claims
        licensable by such Contributor that are necessarily infringed by their
        Contribution(s) alone or by combination of their Contribution(s) with the Work
        to which such Contribution(s) was submitted. If You institute patent litigation
        against any entity (including a cross-claim or counterclaim in a lawsuit)
        alleging that the Work or a Contribution incorporated within the Work
        constitutes direct or contributory patent infringement, then any patent licenses
        granted to You under this License for that Work shall terminate as of the date
        such litigation is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the Work or
        Derivative Works thereof in any medium, with or without modifications, and in
        Source or Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works a copy of
        this License; and
        
        (b) You must cause any modified files to carry prominent notices stating that
        You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that You
        distribute, all copyright, patent, trademark, and attribution notices from the
        Source form of the Work, excluding those notices that do not pertain to any part
        of the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its distribution, then
        any Derivative Works that You distribute must include a readable copy of the
        attribution notices contained within such NOTICE file, excluding those notices
        that do not pertain to any part of the Derivative Works, in at least one of the
        following places: within a NOTICE text file distributed as part of the
        Derivative Works; within the Source form or documentation, if provided along
        with the Derivative Works; or, within a display generated by the Derivative
        Works, if and wherever such third-party notices normally appear. The contents of
        the NOTICE file are for informational purposes only and do not modify the
        License. You may add Your own attribution notices within Derivative Works, alongside or as an
        addendum to the NOTICE text from the Work, provided that such additional
        attribution notices cannot be construed as modifying the License.
        
        You may add Your own copyright statement to Your modifications and may provide
        additional or different license terms and conditions for use, reproduction, or
        distribution of Your modifications, or for any such Derivative Works as a whole,
        provided Your use, reproduction, and distribution of the Work otherwise complies
        with the conditions stated in this License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise, any
        Contribution intentionally submitted for inclusion in the Work by You to the
        Licensor shall be under the terms and conditions of this License, without any
        additional terms or conditions. Notwithstanding the above, nothing herein shall
        supersede or modify the terms of any separate license agreement you may have
        executed with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade names,
        trademarks, service marks, or product names of the Licensor, except as required
        for reasonable and customary use in describing the origin of the Work and
        reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
        writing, Licensor provides the Work (and each Contributor provides its
        Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
        KIND, either express or implied, including, without limitation, any warranties or
        conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
        PARTICULAR PURPOSE. You are solely responsible for determining the
        appropriateness of using or redistributing the Work and assume any risks
        associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability. In no event and under no legal theory, whether in
        tort (including negligence), contract, or otherwise, unless required by
        applicable law (such as deliberate and grossly negligent acts) or agreed to in
        writing, shall any Contributor be liable to You for damages, including any
        direct, indirect, special, incidental, or consequential damages of any character
        arising as a result of this License or out of the use or inability to use the
        Work (including but not limited to damages for loss of goodwill, work stoppage,
        computer failure or malfunction, or any and all other commercial damages or
        losses), even if such Contributor has been advised of the possibility of such
        damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing the Work or
        Derivative Works thereof, You may choose to offer, and charge a fee for,
        acceptance of support, warranty, indemnity, or other liability obligations
        and/or rights consistent with this License. However, in accepting such
        obligations, You may act only on Your own behalf and on Your sole
        responsibility, not on behalf of any other Contributor, and only if You agree to
        indemnify, defend, and hold each Contributor harmless for any liability incurred
        by, or claims asserted against, such Contributor by reason of your accepting any
        such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        Copyright 2026 Jeremy Dixon
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
License-File: LICENSE
Keywords: local-development,rag,retrieval,runtime,vyral
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: coverage==7.15.4; extra == 'dev'
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: mypy<3,>=1.18; extra == 'dev'
Provides-Extra: extropic
Requires-Dist: extro-sim<0.6,>=0.5; extra == 'extropic'
Provides-Extra: extropic-torx
Requires-Dist: extro-sim<0.6,>=0.5; extra == 'extropic-torx'
Requires-Dist: extro-torx==0.0.1; extra == 'extropic-torx'
Requires-Dist: jax<0.12,>=0.11; extra == 'extropic-torx'
Provides-Extra: server
Requires-Dist: uvicorn<1,>=0.30; extra == 'server'
Description-Content-Type: text/markdown

# vyral

Python-first implementation of Vyral's portable local runtime.

Current version: `0.1.1`

Current maturity: `prototype`

Supported Vyral contract: `0.3.0`

This package is implementing the sequence in
[`design/python-runtime.md`](../../design/python-runtime.md). The current
prototype includes:

- the canonical OpenAPI, JSON Schema, and public operation catalog;
- shared Python/.NET conformance fixtures for primitives, snapshots,
  deterministic embeddings, record CRUD, compound filters, ordering,
  continuation, RAG plan/manifest hashes, graph record mapping, and durable
  execution failure/cancellation semantics;
- SQLite collections and records, filtering, lexical and exact-vector search,
  snapshots, filesystem objects, and persisted traces;
- deterministic embedding providers, retrieval profiles and fusion, reranking
  seams, ingestion, context and prompt assembly, citations, and evaluation;
- graph import/export, traversal, inspection, doctor, and bounded GraphRAG
  context expansion;
- the strong transactional SQLite CanonicalStore profile with fences,
  revisions, idempotency, outbox leasing, migrations, preflight, and
  hash-verified archives;
- native durable execution with retries, cancellation, events, timers, waits,
  leases, checkpoints, artifacts, restart recovery, maintenance, policy, and
  thirteen built-in domain job adapters, including staged cross-store artifact ingestion and
  receipt-bound collection lifecycle;
- an OpenAPI-derived ASGI host covering all 133 REST operation IDs;
- parity with the shared `vyral.admission.v1` contract: aggregate mutations return durable,
  idempotent jobs with `Location`, while non-mutating RAG dry-runs remain synchronous;
- a stateless MCP `2026-07-28` endpoint with self-describing routing headers,
  authorization, bounded resources/tools, and durable Tasks;
- synchronous APIs plus bounded-executor asynchronous facades; and
- Python-native handler descriptors, an async run context, a replayable local
  handler harness, and a dependency-free token-safe HTTP external-worker
  transport covering leases, heartbeats, progress, events, artifacts,
  checkpoints, waits, completion, and cancellation.

Every required portable-local profile is implemented and reports
`available: true`. All remain `prototype`, and `fullLocalReady` deliberately
remains false pending independent security review and an explicit promotion
decision. The manual Python 3.10–3.12 Linux/macOS/Windows matrix now passes:
every cell builds and installs clean wheel and source artifacts, completes the
cited restart/replay quickstart, verifies the server extra, and contributes to
one consistent aggregate receipt. The combined `0.1.0` → `0.1.1`
upgrade/restart rehearsal and the executable adversarial security gate also
pass locally; automated evidence does not substitute for independent review.
Unsupported optional providers are disclosed explicitly; the runtime does not
silently delegate embedded behavior to .NET or to the existing HTTP client.

## Local single-player experience

From the repository root, the shortest path runs directly from source:

```bash
./scripts/vyral
```

It performs the connected retrieval-and-execution proof described below. No
installation or third-party service is required. Use `python scripts/vyral` on
Windows.

To install the command into an isolated environment instead:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --editable runtimes/python
```

The installed command is `vyral`, and running it without arguments performs the
same proof:

```bash
vyral
```

The quickstart creates a three-document, source-backed record corpus without
vectors, returns cited lexical context, admits a decorated handler with a
stable idempotency key,
closes the runtime before dispatch, reopens the same SQLite/filesystem state,
and completes the preserved run identity. It reports the queued receipt before
the close/reopen boundary so acceptance is not confused with completion.

The quickstart does not invoke an embedding provider. The runtime's available
default `local-token-hash` provider remains CPU-only, model-free, and requires
no network or downloaded assets; when explicitly selected for vector mechanics,
its lexical-overlap ranking is not a semantic-model quality claim.

Inspect the state and its material limitations independently:

```bash
vyral inspect
```

The quickstart records an ownership marker and will reset only a dedicated
directory bearing that marker:

```bash
vyral quickstart --reset
```

Generate one editable application when you are ready to own the code:

```bash
vyral init
python ./vyral_app.py
```

The generated file uses `@vyral(...)`, admits work with a stable idempotency
key, prints the durable receipt, closes the first runtime before dispatch,
reopens its own `.vyral/vyral_app` directory, and completes the preserved run.
Running it again reports `replayed=true` and dispatches no duplicate work. The
generator refuses to overwrite an existing path; the result is ordinary Python
source intended to be edited or absorbed into an application. Leave the visible
`RUN_VERSION` unchanged to prove replay, then increment it after changing the
work to admit a new run. Use `--path` or `--root` when you need non-default code
or state locations.

Use `--json` with `init`, `quickstart`, or `inspect` for machine-readable
output. `vyral-runtime` remains a compatibility command alias. No wheel has
yet been published, so direct source use or the editable install is the public
pre-release path. Once the authorized wheel is available, install it with
`python -m pip install vyral` without changing the local commands.

From a source checkout, run the generated application through the same launcher
that created it so no editable installation is required:

```bash
./scripts/vyral init
./scripts/vyral run ./vyral_app.py
```

After installation, the equivalent commands are `vyral init` and
`vyral run ./vyral_app.py`.

The quickstart JSON includes measured `firstCitationMs`, `durableReceiptMs`,
`restartRecoveryMs`, and `completedMs` milestones. Artifact qualification runs
the installed wheel and sdist through the generated editable application, its
idempotent rerun, the connected quickstart, a second-process quickstart replay,
independent inspection, and marker-bounded reset. Each supported platform cell
rejects either installed path if package installation through its first useful
result takes more than five minutes.

```python
from vyral_runtime import VyralRuntime

runtime = VyralRuntime()
status = runtime.readiness().to_dict()

print(status["runtimeVersion"])
print(status["contract"]["operationCount"])
print(status["fullLocalReady"])
```

```python
from vyral_runtime import VyralRuntime

with VyralRuntime.open_local("./.vyral") as runtime:
    runtime.records.create_collection({"name": "notes"})
    runtime.records.upsert_record(
        "notes",
        {
            "id": "hello",
            "partitionKey": "local",
            "content": {"text": "Hello from the Python runtime"},
        },
    )
```

Python handlers use the same authoring surface in the local harness and over
the remote external-worker protocol. The decorator is deliberately thin: it
builds the existing portable descriptor and handler objects without adding a
workflow graph, scheduler, or alternate retry model.

```python
from vyral_runtime import (
    ExecutionRunContext,
    ExecutionRunResult,
    execution_plugin,
    vyral,
)

@vyral(
    "example.echo",
    plugin="example.plugin",
    max_attempts=3,
)
async def echo(context: ExecutionRunContext) -> ExecutionRunResult:
    await context.record_event("log", message="handler started")
    return ExecutionRunResult.succeeded_result({"received": context.run.payload})

plugin = execution_plugin(
    "example.plugin",
    name="Example",
    version="1.0.0",
    handlers=(echo,),
)
```

The decorated handler remains directly awaitable for focused tests. Explicit
`execution_handler(...)`, `DelegateExecutionHandler`, and
`StaticExecutionPlugin` construction remains available when descriptor-oriented
naming or dynamic registration is clearer. Handler and plugin IDs remain
explicit because they are durable contract identities; renaming or moving a
Python function must not silently create a different operation.

### Experimental source-native retrieval

`vyral_runtime.integrations.ripgrep` provides a bounded, read-only experiment
for code, Markdown, and other safely accessible text sources. It uses a static
root and glob allowlist, fixed-string queries over standard input, source
revision citations, and strict resource limits. It is not part of the stable
wire contract and is not automatically exposed through REST or MCP. Retained
comparison evidence supports it for exact identifiers and phrases in current
local sources when maintaining a duplicate index is not worthwhile. Use Vyral
lexical retrieval for reordered terms, prefixes, record filters, tenant
boundaries, snapshots, and lower post-index query latency. See the
[source-native retrieval guide](../../docs/guides/source-native-retrieval.md)
and [comparison receipt](../../benchmarks/retrieval/README.md).

### Experimental Extropic execution

Install the optional `extropic` extra to place a registered Python workload
behind the same Vyral execution lifecycle:

```bash
python -m pip install --editable "runtimes/python[extropic]"
```

```python
from vyral_runtime import ExecutionRunContext, ExecutionRunResult, vyral
from vyral_runtime.integrations.extropic import (
    ExtropicAdapterOptions,
    ExtropicExecutionAdapter,
)


def simulate(payload):
    return {"seed": payload["seed"], "samples": payload["samples"]}


extropic = ExtropicExecutionAdapter(
    "example.simulation.v1",
    simulate,
    options=ExtropicAdapterOptions(tier="l4", require_seed=True),
)


@vyral("example.simulate", plugin="example.extropic", max_attempts=3)
async def run_simulation(
    context: ExecutionRunContext,
) -> ExecutionRunResult:
    return await extropic.execute(context)
```

Vyral retains the provider job id, safe status, bounded logs, and replay state;
it never persists Extropic credentials or upload grants. Because Extropic 0.5
does not accept an idempotency key during job creation, a lost create response
fails closed and is not resubmitted automatically. Known provider jobs are
reconnected and retried by id. The integration is a prototype, remains outside
the adapter qualification matrix, and makes no Z1 support claim. Registered
workloads should be self-contained plain Python functions; Vyral serializes
those functions by value, while third-party imports must exist in Extropic's
sandbox. A pinned `extropic-torx` extra and
[`examples/python/extropic_torx_workload.py`](../../examples/python/extropic_torx_workload.py)
provide a real, credit-free Torx packaging proof on Python 3.11 or newer. See the
[Extropic execution guide](../../docs/guides/extropic-execution.md) for the
complete lifecycle and current boundaries.

## Choosing a Python package

| Goal | Install |
| --- | --- |
| Talk to a running .NET or Python Vyral host | `vyral-client` |
| Run Vyral in-process without a server or .NET | `vyral` |
| Run a Python-hosted REST and MCP endpoint | `vyral[server]` |
| Rehearse the current Extropic/Torx proof locally | `vyral[extropic-torx]` (Python 3.11+) |

The existing `vyral-client` distribution remains the supported lightweight
client for a running Vyral server. `vyral` is a separate runtime distribution
and does not depend on or route its embedded behavior through that client.

## Embedded models and wire JSON

The embedded runtime accepts schema-shaped mappings where convenient, then
returns rich Python models such as `VyralRecord`, readiness receipts, plans,
and execution state. Use their `to_dict()` methods when serializing to JSON or
crossing an HTTP, MCP, queue, or persistence boundary. The REST host and
`vyral-client` expose the canonical JSON wire representation instead; callers
must not depend on Python class names or private object layout as portable
contract.

OpenAPI operation IDs remain the semantic naming authority. Embedded methods
use idiomatic `snake_case` names and mirror those operation IDs where practical;
a convenience name may improve Python composition but cannot add alternate
wire semantics, defaults, validation, or failure behavior. When exact
cross-runtime correspondence matters, start from the operation ID and its
shared schema or conformance fixture.

## Storage portability

The Python runtime's SQLite tables, migration ledger, filesystem layout, and
the corresponding .NET layouts are implementation-private. They are not a
binary compatibility surface, even when the filenames look alike. Do not copy
`vyral.sqlite`, a CanonicalStore database, or an execution database from one
runtime into the other.

Cross-runtime movement uses documented public envelopes: collection and graph
exports, CanonicalStore tenant archives, objects, and execution-owned outputs
where supported. Those envelopes and their shared conformance fixtures—not raw
SQLite bytes—are the portability contract.

## Contract and fixture verification

Every runtime construction validates the bundled OpenAPI, JSON Schema, and SDK
catalog. Embedded `VyralRuntime()` construction does not execute the complete
golden corpus by default, keeping notebook and test composition proportional as
the fixture set grows. Use `VyralRuntime(verify_assets=True)` when construction
itself must fail closed on both the contract bundle and goldens.

Readiness always executes the bundled goldens. The optional REST/MCP host also
constructs its owned runtime with `verify_assets=True`, and release
qualification runs the canonical fixture suite separately. This keeps
construction fast without weakening host startup or qualification evidence.

## Optional server

Install the server extra and choose an explicit durable directory:

```bash
python -m pip install "vyral[server]"
export VYRAL_API_KEY="replace-with-a-secret"
vyral serve --root ./.vyral --host 127.0.0.1 --port 5220
```

REST is available at the public OpenAPI paths and stateless MCP at `/mcp`.
API-key hosts accept `X-Vyral-Api-Key` or a bearer token. Localhost Host/Origin
validation is enabled by default. A non-loopback CLI bind is rejected unless
`VYRAL_API_KEY` is set; wildcard binds also require one or more explicit
`--allowed-host` values. Browser deployments opt into exact origins with
`--allowed-origin`; add `--require-explicit-origin` to disable MCP's
same-host browser fallback. Add `--require-api-key` when a loopback host must
also fail closed without credentials. Request access logs are disabled by
default. The SQLite/filesystem composition is a single-node topology even
though each MCP request can be parsed and authorized without session affinity.
See the [Python host security guide](../../docs/guides/python-host-security.md)
before exposing a host beyond a single trusted user or process boundary.

The baseline qualification corpus is 2,000 records with 384-dimensional exact
vectors, a roughly 200-chunk RAG document, and 20 durable jobs. This is a
bounded evidence run for notebook and small local-service use, not an SLA or a
maximum supported corpus. Hosted wall-clock time is recorded rather than used
as a release gate; controlled runners can opt into a limit with
`--max-seconds`.

## Development checks

From the repository root:

```bash
scripts/verify-python-runtime.sh
python3 scripts/verify-python-external-worker-integration.py
scripts/verify-python-runtime-external-worker.sh path/to/vyral.whl
scripts/verify-python-runtime-mcp-conformance.sh path/to/vyral.whl
python3 scripts/verify-python-runtime-security.py path/to/vyral.whl
python3 scripts/verify-python-runtime-upgrade.py \
  path/to/vyral-0.1.0.whl path/to/vyral-0.1.1.whl
python3 scripts/benchmark-python-runtime.py
dotnet test tests/Vyral.Tests.Conformance/Vyral.Tests.Conformance.csproj \
  --filter 'PortableRuntimeGoldenFixtureTests|PortableExternalWorkerLifecycleFixtureTests'
```

The main verification command runs the full unit suite with branch
instrumentation using pinned Coverage.py 7.15.4 and enforces a 77.5% combined
line/branch regression floor. The floor is a regression guard, not a claim
that every dispatch or error branch is exhaustively tested.

The cross-platform qualification workflow is manual-only:
`.github/workflows/python-runtime-qualification.yml`. This preserves the
repository's current GitHub-run gate while keeping the promotion matrix
reproducible. Every cell builds both artifacts, installs each into a clean
environment, completes the real cited/restart quickstart, replays it from a
second process, inspects its limitations, and safely resets its owned state.
The HTTPS URL and SHA-256 of a previously qualified `0.1.x` wheel are optional
paired inputs: when supplied, the workflow also runs the installed upgrade
gate, which cannot silently self-compare the candidate. The aggregate job then runs
`scripts/verify-python-runtime-platform-matrix.py`; all nine cells must be
clean, refer to one commit, agree on runtime and contract identity, and carry
passing measured local-experience evidence before the matrix is valid. A run
without a baseline proves the platform matrix but is not upgrade evidence and
does not by itself authorize maturity promotion.
