qleisli 0.2.1

Experimental quantum language with linear ownership, exact contracts and independent finite IR verification
Documentation
# Documentation authority and English consolidation

Status: **English documentation policy and translation inventory** (2026-09-27).
This map identifies the status of the current documents; it does not extend the
language, adopt imaginary syntax, or prove implementation correctness.

## How to read the documents

For first use, start with the [repository quickstart](../README.md#try-it) or
the concise [registry README](../README.crates.md). They describe the current
Rust CLI/library and distinguish optional Python/Lean work. The
[crates.io procedure](crates-io-release.md) records preparation, distribution
contents and the explicit publication hold; it does not change language rules.

English is the authoritative language for production language specifications
and public standard-library names, contracts, references, source comments,
and example explanations. Authority is tied to a document's subject and status:

| Document class | Authority and limits |
| --- | --- |
| Authoring entry point and observations | [Quick reference](qli-quick-reference.md) gives CI-compiled current examples and links to authoritative norms. [Authoring feedback](qli-authoring-feedback.md) records executable reproductions, delivered fixes and future candidates; the [session records](../tests/fixtures/authoring_sessions/README.md) preserve informed first attempts and curated repairs with integrity checks. They are not a comparative LLM benchmark. |
| Current language and API specifications | [Language v0](language-spec.md), [consolidated type contract](type-system.md), [grammar](syntax-v0.md), [modules/sealed APIs](standard-library.md), [static operations](static-operations.md), [SC](semantic-contracts-v0.1.md), [FC](function-contracts-v0.1.md), and the [ordinary-library ledger](stdlib-contracts.md) govern current specified acceptance and public contracts within their declared scope. |
| Formal rules and proof accounts | [Formal core](formal-core.md), [resource rules](source-resource-rules.md), [typing rules](source-typing-rules.md), [source semantics](source-semantics.md), [static semantics](static-semantics.md), [source soundness](source-soundness.md), [IR correspondence](source-ir-correspondence.md), and [state refinement](lowering-state-refinement.md) state their models, assumptions, and proved/open obligations. A paper proof is not a claim that Rust implements every derivation correctly. |
| Implementation and evidence records | [Frontend profile](frontend-v0.md), [IR prototype](ir-prototype.md), [architecture](implementation-architecture.md), [Lean ledger](lean-resource-proof.md), [Physlib environment](physlib-environment.md), and [conformance history](specification-status.md) describe implementation/dependency coverage and dated evidence. Finite tests and local Lean lemmas do not establish general compiler soundness. |
| Adopted design direction and development plans | The translated documents below are the English editions for their own principles, requirements, plans, and arguments. The [Lean kernel migration](lean-kernel-migration.md) governs the adopted runtime/proof split and staged authority transfer; its [first word slice](lean-kernel-migration.md#first-executable-slice) and [initial shared-DAG slice](lean-hierarchy-slice.md) specify separate experimental boundaries. An accepted design principle may constrain future work without being implemented. Proposed facilities remain proposed. These documents do not override current language/API rules. |
| Release criteria and compatibility | [Release milestones](release-milestones.md), [versioning](versioning.md), the [v0.x plan and v0.1.9 boundary](v0x-roadmap.md), and version-specific [release records](releases/v0.1.9.md) determine acceptance, compatibility, and preparation/publication status. Roadmap themes do not adopt syntax or establish implementation. Product versions, development stages, specification v0, and ledger format v1 are distinct. |
| Future design material | The [v0.2.0 backlog](v0.2.0-backlog.md) is the living authoring-issue intake, with evidence and acceptance experiments; it is not an adopted release scope. The [language-evolution framework](language-evolution.md) and [imaginary-v1 corpus](imaginary-v1/README.md) organize future requirements. All six algorithm drafts remain imaginary and uncompiled; their existence does not adopt their notation or APIs. |
| Extension specifications and future profiles | [M1 language extension](next-minor-spec.md) is the normative fixed-width supplement implemented at the 0.1.8 checkpoint. The [0.1.8 grammar supplement](syntax-v0.md#authoring-forms-added-in-product-018) introduced basis parameter patterns and tuple sugar; the [0.2.0 tuple correction](tuple-shapes.md) supersedes its left-folding rule with exact arity and nesting. [Machine interfaces](machine-interface-spec.md) have X1–X6 implementations in the 0.2.0 finite profile. The [bounded M2 IR/checker profile](hierarchical-ir-spec.md) remains a future specification whose new checker is to be implemented in Lean. The experimental phase-word, shared-DAG, [typed layout](lean-layout-slice.md) [typed-call](lean-layout-dag-slice.md) and [combined phase/layout](lean-phase-layout-slice.md) slices the [interference/complex bridge](lean-interference-slice.md) and [QFT circuit proof](lean-qft-proof-packet.md), including [typed graph binding](lean-qft-graph-packet.md), and [QPE instrument/conditional completeness](lean-qpe-instrument-packet.md) do not complete it. Release records identify executed tests; selection alone does not establish implementation. |
| Independent semantic research | The [system design](symbolic-contract-architecture.md) specifies the intended meaning/implementation boundary; the [prototype record](../research/semantic-kernel/README.md) records the separately implemented and tested subset. The [quantum-library investigation](../research/quantum-libraries/README.md) records isolated mathematical interface experiments that did not adopt a dependency at that investigation step; the later [Physlib record](physlib-environment.md) preserves the compatible addition and its subsequent deferral to a future concrete bridge. None changes production source acceptance or proves Rust/source correspondence. |

Use the [terminology conventions](terminology.md) across these classes. If a
proposed design conflicts with a current contract, record the conflict and a
future specification decision explicitly; do not silently reinterpret accepted
programs. Selecting a feature, specifying it, implementing it, testing it, and
proving it are separate events.

[QLT design](qlt-design.md) is an adopted future test-language direction,
with [preserved desired sources and semantic faults](../tests/fixtures/qlt_design/README.md).
Its proposed syntax, `denote`, cost interface, doctests and test command are
unimplemented. It neither extends accepted `.qli` grammar nor supplies quantum
evidence; the Rust experiment and later Lean evaluation proofs have their own
TQL-0–TQL-3 milestones.

[Lean-assisted mathematical debugging](lean-debugger-plan.md) is an adopted
future 0.x.0 tooling direction: obligation reports, independently checked
mismatch witnesses and IR/source/backend tracing. No debugger API, command,
implementation or diagnostic theorem is supplied by this plan. It preserves
the fixed trust boundary and the existing release/theorem gates.

## Current state and historical records

The 2026-09-30 [Resource Safety adoption](resource-semantics.md) is a future
third v1 theorem pillar, with [RS-C1–C5](release-milestones.md#resource-safety-theorem-v1)
and an explicitly dated **to prove** amendment to the trust boundary. It
specifies intended resource semantics and proof duties, not a current language
form, checked bound API or completed ownership/quantitative theorem.

The 2026-09-30 [0.2.1 boundary](v0.2.1-plan.md) retains completed experiments,
review fixes and [bounded connections](connections-v021.md). Remaining heavy
implementation/integration/proofs move to [0.2.2](v0.2.2-plan.md), superseding
the earlier release assignment while retaining its history and unmet gates.

The [linear-size and explicit register-reshape design](size-expressions.md)
is an adopted 0.2.1 direction for the still-pending G020-1 source extension.
It selects arithmetic/equality, ordered segment conversion, proof and CI
obligations without claiming a production solver, array API or executable
sized source. The [earlier reshape helper](reshape-plan.md) retains its
intact-atom contract and separately recorded implementation status.

[project-status.json](project-status.json) is the single editable record for
active milestone states and the initial rule/implementation/test/proof
inventory. [current-status.md](current-status.md) is generated from it and the
Rust/Lean manifests; the document checker rejects version/view drift and
missing source/test links. It is not an automatic proof or exhaustive audit.
The [initial B019 boundary check](reviews/b019-2026-09-28.md) preserves its
then-unresolved defect and executed checks. The later
[completion record](reviews/b019-completion.md) collects actual review
dispositions, repairs and candidate validation without rewriting that history.
The [code-driven procedure](code-driven-development.md) fixes the user's
post-foundation direction, sources, obstacles and acceptance experiments; it
does not adopt future syntax or mark remaining M1–M5 work complete.
Detailed norms remain in their existing specifications; historical validation
entries remain dated. [M0–M5 and the legacy-ID map](v0x-roadmap.md#legacy-id-mapping)
replace version-assigned scheduling without renumbering theorem statements.
The [Qleisli Soundness Theorem and S05-C1–C5](release-milestones.md#qleisli-soundness-theorem-v050)
are the adopted v0.5.0 target, still unproved. The
[community roadmap](v0x-roadmap.md#community-development-from-v05) prepares
contribution and review processes during 0.4.x and expands development from
v0.5 onward; existing Apache-2.0 licensing continues.

The [K0–K4 migration axis](lean-kernel-migration.md#staged-migration) runs alongside
M0–M5, with intended 0.2.0-to-0.x.0 compatibility boundaries and separate proof,
implementation and authority-transfer gates. It does not replace H1–H5 or claim
that current `check`/`run` already rely on Lean.
AGENTS.md links durable rules to [the decision dossier](decisions/2026-09-27-v1-path.md)
instead of repeating changing adoption paragraphs.

## Translation inventory

The following current Japanese documents were translated in place for the
English consolidation requested after the initial v0.1.2 corpus review. Their
paths remain stable. Old heading targets are retained as explicit anchors so
existing links, including links in historical records, continue to resolve.

| English edition | Scope retained | Status of its content |
| --- | --- | --- |
| [Project overview](../README.md) | North star, current implementation/proof limits, development goals, references, development commands, and licensing | Project summary; linked specifications and release records govern details. |
| [M1.1 connection contract](interop-m1.1.md) | Bounded OpenQASM 3 input/output and QIR 2.0 Base output, exact gates, initialization, ownership, bounds, diagnostics and validation | English normative host-adapter contract for the implemented terminal subset; no complete-format, device-execution or general translation-proof claim. |
| [Interoperability direction](interoperability-roadmap.md) | Python, OpenQASM 3 and QIR entry points, compiler layers, translation obligations, IR emitter/debt inventory and reduction gates | Selected direction; bounded M1.1-A implemented under its separate contract. Python, QIR import and adaptive work pending. Internal qif execution consolidation removes no trusted rules. |
| [Terminology](terminology.md#desugaring-layer) | Shared definition of desugaring, its producer/checker boundary and distinction from parsing, source checking, runtime adaptation and approximation | Authoritative terminology; no new language/API acceptance rules. Relevant documents restate the definition locally. |
| [Coefficient domains](coefficient-domains.md) | Future gate-architecture risk, coefficient-domain type parameterization and distinct exact/approximate/device contracts | Recorded architectural recommendation with primary sources and mathematical rationale; generic scalar APIs, arbitrary-angle checking and STAR support remain unimplemented. Existing M1/M2 formats/profiles are unchanged. |
| [Source documentation](documentation-comments.md) | Rust-style ordinary/doc comments, attachment, sidecar APIs, Markdown command, trust boundary and source migration | Implemented bounded extension in 0.1.6, with historical version/migration records preserved; doc text is not checked semantic evidence or full rustdoc support. |
| [Development roadmap](../ROADMAP.md) | P012/G020, SPEC, A/L work areas, stages 0–5, historical milestones and check counts | Accepted ordering and stated completion criteria; pending work remains pending. |
| [Design philosophy](design-philosophy.md) | Effectful composition, linear ownership, global-state reasoning, phase, cleanup, and implementation boundaries | Fixed design principles; future syntax and open semantic/composition work remain explicit. |
| [AI-era goal](ai-era-goal.md) | Assurance levels, resource/ideal-semantic proof targets, AI verification boundary, and exclusions | Adopted development goal, with bounded achieved results and open general proofs distinguished. |
| [Algorithm-structure goal](algorithm-structure-goal.md) | Common structures S1–S8, design contracts, A0–A4, corpus and future composition | Adopted goal and plan; higher-order/generalized facilities are not current APIs. |
| [Algorithm corpus](algorithm-corpus.md) | Twenty entries C01–C20, primary-source links, input models, promises, evidence needs, and unsupported parts | Research/design inventory, not twenty implemented algorithms. |
| [Input corpus](../corpus/README.md) and [source/license policy](../corpus/POLICY.md) | 24 finite QLI translations, original files, pinned commits, notices, authoring records and independent semantic tests | Closed three-source intake adopted by the user; finite validation, not whole upstream algorithm ports or general proofs. |
| [Quantum-language requirements](quantum-language-requirements.md) | Resource/effect/phase/reference conditions and specification obligations | Adopted requirements with implementation/proof scope stated separately. |
| [Standard-library roadmap](stdlib-roadmap.md) | Adopted BLAS/LAPACK + textbook + formal-specification goal; seven concept areas, contracts, proposed skeletons, adoption criteria and L0–L5 | Authoritative library goal and design plan; comprehensive organization remains open and proposed generalized APIs remain unimplemented. |
| [Quantum bookkeeping](quantum-bookkeeping.md) | Language responsibility, semantic composition, phase-sensitive QPE, and proposed evaluation order | Supporting design argument and proposal, subordinate to release acceptance criteria. |
| [Finite-IR paper proof](finite-core-proof.md) | Constructor equations, theorem premises, reference extension, resource invariants, and implementation obligations | English edition of a conditional mathematical argument for the stated finite IR; neither whole-compiler verification nor a new Lean result. |

The existing English current specifications, finite routine/static/arithmetic
contracts, language framework, and six imaginary algorithm drafts were used
as cross-references. Translation preserves mathematical premises and the
distinctions between proposal, adoption, implementation, finite testing, paper
proof, and machine checking. Stale summary wording is clarified against those
records without changing source acceptance or claiming new proof coverage.

## What remains in Japanese

- [AGENTS.md](../AGENTS.md) was translated into English on 2026-09-28 at the
  user's request, preserving its operational, licensing and verification rules.
  CONTRIBUTING and the current development guides are also English.
- Dated Japanese entries in the [conformance ledger](specification-status.md)
  are retained as historical evidence in their original language. The English
  introduction and new entries identify current state and superseded status
  claims. A historical “not implemented” or “not rerun” describes that step,
  not necessarily the current tree. Historical test totals and publication
  actions are not rewritten as new results.
- Japanese legacy anchors and the bilingual glossary remain intentionally.
  They preserve references and terminology; they are not untranslated current
  specification prose.

Current design/planning prose in the ten inventory documents is English.
Historical records may later receive labeled English translations, with the
original date, scope, and evidence preserved. No duplicate Japanese normative
edition is maintained by this consolidation.

## Decisions this consolidation does and does not settle

The fixed foundation is linear quantum ownership, explicit effects, global
reasoning with arbitrary references, phase-sensitive composition/control,
exact evidence for pure auxiliary cleanup, and independent checking of finite
semantic contracts through final IR. The north star and executable V1-C1–C5
criteria remain in force.

The initial six-code prerequisite before v0.2.0 is complete as design material.
Sized source syntax, general instrument/accuracy evidence, and full arithmetic
APIs still require extension decisions. The subsequent
[0.1.5 dossier](decisions/2026-09-27-v1-path.md) and its linked specifications
settle fixed-width operation/access/meaning rules, machine interfaces and the
bounded M2 checker/QPE profile. Subsequent [0.1.7](releases/v0.1.7.md) and
[0.1.8](releases/v0.1.8.md) records implement and validate X1, M1.1-A and
fixed-width operations/meanings. Finite X2–X6 implementation is now recorded in
[0.2.0](releases/v0.2.0.md). The [revised foundation plan](v0.2.0-plan.md)
retains migration and release checks; the [0.2.1 plan](v0.2.1-plan.md) carries
remaining production hierarchy, sized QPE and execution/H1–H5 work without
weakening its gates. The current [0.2.1 development record](releases/v0.2.1.md)
separates version selection from validation and publication. Full M2 and Lean
migration remain pending. The
[requirements index](imaginary-v1/requirements.md) records candidate facilities
and open questions; translation is not their adoption. General source-to-IR
adequacy, verifier correctness, and compiler soundness remain open.

## Review and validation record

The completed consolidation review compared each translated document with its Japanese
baseline for retained premises, formulas, code, links, historical counts, and
status. Review also checked alignment with current English specifications and
the imaginary corpus. Document-reference checks cannot by themselves establish
translation fidelity or mathematical correctness.

The commands and completed review results are recorded in the
[conformance ledger](specification-status.md#english-documentation-consolidation)
and [0.1.2 release record](releases/v0.1.2.md#english-documentation-consolidation).
All ten editions passed review; all 102 original heading/explicit-anchor targets
and original link destinations are retained. Document-checker tests (14),
mathematical fixtures (39 exact and 52 finite convention checks), reference and
whitespace checks, and updated 156-file packaging/rebuild passed. All 55 current
documentation/license/notice files were compared with the archive. The earlier
155-file candidate and its Rust/Lean suites precede this translation; those
suites were not rerun for it. The subsequent checks are recorded separately. This work does
not include committing, tagging, pushing, or publication.