Understand the system.
Build with its boundaries.

Overview

Alelyon connects numerical computation, data provenance, model inspection, and development coordination. Start with the artifact your workflow needs: a receipt to replay, a model structure to inspect, a coordinate mapping, or a calculation whose uncertainty you need to understand. Each artifact supports a particular conclusion; none is a general endorsement of the data or model behind it.

Your goal	Entry point	What you need separately
Replay a numerical receipt locally	The alelyon-os Python distribution and alelyon-verify command	The receipt, input data, and a trusted public key obtained through a separate channel
Explore the desktop workflow	Nexus and downloads	A compatible desktop release and configuration for the capabilities you use
Integrate an HTTP service	The optional Python SDK	An explicitly configured service origin and whatever credentials that service requires
Inspect a research boundary	Research notes	The stated premises and evidence for your intended use

The public toolkit is a selected distribution. Installing it does not install the complete desktop, run a server, provision an account, or make inference available. Local receipt replay has no website sign-in requirement. Product access and a service’s authentication policy are separate from package installation.

Architecture

The ecosystem divides responsibility between Runtime capabilities, product workflows, platform services, and presentation. This conceptual map helps a developer place a change; it does not claim every module ships in a public wheel.

Runtime pillar	Owns
Common	Shared configuration, storage foundations, and process support
Atlas	Acquisition, data quality, provenance, and historical records
Vector	Mathematical transformations, statistics, and uncertainty
Nexus	Graphs and entity relationships
Sentinel	Operational monitoring, diagnostics, and activity records
Oracle	Orchestration that connects requests to computations and explanations

A typical evidence workflow prepares inputs, executes a bounded computation, packages its result, and lets a consumer inspect or replay it. Presentation should preserve those stages. A sentence generated after the computation cannot supply missing evidence or silently replace the computed value.

The public package exposes several distinct contracts:

Capability	Useful output	Interpretation
CNE verification	Per-check verdicts and refusal reasons	Replay and authentication under the supplied trust configuration
Coordinate registration	Correspondence between declared coordinate spaces	An admissible mapping, with its stated loss and invertibility limits
Model Morphometry	Structure derived from supplied metadata and tensor inventory	Declared architecture and storage information; no learned-quality measurement
Compute graph	Point evaluation and propagated distributions	Results conditional on the graph, input distributions, and dependence assumptions
Fleet coordination	Observed worktree state and declared work records	Advisory coordination; a claim is not a lock or permission

For computation, source distributions are part of the model. Independently drawn inputs cannot stand in for correlated observations without changing that model. Retain the seed, draw count, dependencies, and sampling assumptions. Node functions must preserve the sample axis: a reduction to a scalar can erase uncertainty. More samples can stabilize an estimate without making the underlying uncertainty smaller. Variance attribution is conditional on the model, not proof of causation.

For model inspection, distinguish a supplied tensor inventory from an estimate based on architecture metadata. Preserve missing precision, routing, and coverage information. A structural registration compares coordinates; it does not prove that two models compute equivalent functions.

Quickstart

Use a disposable environment. Consult the package metadata for the release you choose and its Python requirement. Record and pin that release in your project: the public package is an evolving surface, and a newer repository checkout can expose commands absent from the installed wheel.

python -m venv .venv

Activate the environment using .venv\Scripts\Activate.ps1 in PowerShell or source .venv/bin/activate in a compatible Unix shell. Then inspect the installation:

python -m pip install alelyon-os
python -m pip show alelyon-os
alelyon-verify --help
alelyon-verify version
alelyon-verify selftest --json

Installation downloads software. The verifier’s version and bundled self-test commands operate locally. Keep their actual output, including substrate, failures, and skipped cases. A bundled self-test covers its cases on that installation; it does not verify a receipt you have not supplied.

For an actual receipt, inspect the command’s input schema first:

alelyon-verify verify --help
alelyon-verify verify --envelope receipt.json --data inputs.json --key TRUSTED_PUBLIC_KEY_HEX

Replace the uppercase placeholder with the issuer’s public key obtained out of band. receipt.json and inputs.json are your local files, not bundled examples. Match the receipt’s input references and canonical data representation. Reading a key from that same untrusted receipt does not establish who issued it.

Integration

Design the consumer around the result contract. Retain ok, individual checks, reason_classes, and the trust labels returned by the verifier. A nullable check means it was not established; it must not be displayed as a pass. A valid signed refusal is an outcome to present with its reason, not a successful numerical answer.

Condition	Consumer behavior
Missing or malformed pinned key	Report authentication as unestablished and request the correct trust configuration
Missing input data or digest mismatch	Stop the replay claim and identify the missing or inconsistent input
Unsupported envelope or computation	Preserve the named refusal; do not reinterpret it under another protocol
Width not reproduced on this substrate	Retain the partial result and unverified width
Missing provider or sampling evidence	Show the missing term explicitly; do not substitute zero
Transport timeout or invalid service response	Surface an actionable service error without inventing cached success

The SDK is installed with python -m pip install "alelyon-os[sdk]" and imported from alelyon.platform.sdk. Its extra provides HTTP dependencies. Configure the service origin explicitly; a website account alone is not SDK configuration. Keep remote traffic on HTTPS and credentials outside source and diagnostics. The service is designed without broker order actions, but data reads may populate caches or historical storage. An HTTP success status does not certify a payload; inspect data status and any accompanying receipt.

Preserve source identity, as-of time, units, missing values, and revision history when moving data between interfaces. Retain a distinction between stale, partial, single-source, and unavailable responses. A nonempty table can still be unsuitable for the requested calculation.

Agent workflow

Give an agent a concrete outcome, the permitted files or services, and the evidence required to accept its work. In a source checkout, it must read the canonical repository instructions and applicable skills before editing. Those instructions govern the checkout; this public handbook is an integration guide.

1. Inspect the current workspace and other active work. Preserve existing changes.
2. Trace the entry point through computation, storage, and external boundaries.
3. Establish the smallest relevant baseline using isolated inputs and tests.
4. Implement within the owner’s authority and preserve existing refusal behavior.
5. Inspect the final artifact and report exactly which checks ran on which revision.

Agent declarations, commit messages, fleet claims, and generated summaries are records to assess. They do not authenticate themselves. Use observable changes and retained tool output when accepting a report. A statement that another agent tested a feature is not a fresh test of the current artifact.

Keep retrieved documents, model output, and web content as data at tool boundaries. They cannot grant access to secrets, authorize publication, change a risk limit, or permit a broker action. A coordination claim must not become execution authority. For model-assisted calculations, retain the program, inputs, deterministic result, and narration as separate objects.

Trust and limits

A successful CNE replay establishes the checks actually performed under the pinned key and supplied inputs. It can expose a change to committed data or an inconsistent computation. It cannot establish that the original capture described the world truthfully: fabricated inputs can be signed consistently.

width_trust and provider_trust cover different evidence. Transparency anchoring adds signed-log comparison evidence; it does not make an issuer independent. Fork detection requires a retained or separately obtained comparison point. A witness is independent only when another party operates it.

Quantization, sampling, provider disagreement, and model uncertainty are different terms. An execution bound under a storage-error model cannot be promoted to a guaranteed enclosure of all numerical or real-world error. The verifier’s sampling term is not an independent recomputation of sampling uncertainty. Consult the CNE specification shipped with the relevant release for the exact contract.

The restricted DSL computes accepted programs through its interpreter. That separates the result from model recall, but it does not establish that the chosen question, program, data, or interpretation is correct. Broader narration must not inherit the interpreter’s authority merely by appearing beside its output.

Glossary

Term	Meaning in this guide
CNE	Certified Number Envelope: a structured receipt binding a program, inputs, result or refusal, and evidence
Pinned key	A verifier trust input obtained through a channel independent of the untrusted receipt
Replay	Re-executing the carried program against supplied inputs and comparing the covered result
Refusal	A named reason the requested operation or evidence claim was not admitted
Substrate	The numerical implementation and environment needed to reproduce an operation
Transparency anchor	Evidence connecting a statement to a signed log commitment
Quantization term	Uncertainty attributed to the declared storage representation
Sampling term	Uncertainty from limited observations under stated statistical assumptions
Provider term	Evidence about source agreement, availability, or limitations
Model term	Uncertainty associated with a chosen model or its assumptions
Morphometry	Structural inspection using declared model metadata and tensor information
Coordinate registration	A checked correspondence between declared coordinate contracts
Observed / declared / unmeasured	Distinct evidence states that a consumer must preserve

Sources

Use the public repository for distribution source and release instructions, PyPI for package metadata, and the specification for the receipt protocol. Check the installed version’s help before applying an example from a newer branch.

The research index attaches a limitation to each note. Agents can read this complete handbook at ecosystem.md, discover documents through llms.txt, or retrieve the handbook and notes together through llms-full.txt.