commit 94b8b0768619568af475938af47f6b9a0e9a93b3 parent 9c533a96c7b41786eb5ebd6834799d3a38012e29 Author: James Eversole <james@eversole.co> Date: Mon, 12 Oct 2026 07:32:54 -0500 Fix local Markdown links for stagit HTML pages Diffstat:
24 files changed, 111 insertions(+), 285 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md @@ -24,7 +24,7 @@ executable rollback. Neither replaces testing. ## Build & Test For tricu compiler build/run commands and focused checks, use -[`docs/build-and-run.md`](docs/build-and-run.md). Keep usage in the guides linked +[`docs/build-and-run.md`](docs/build-and-run.md.html). Keep usage in the guides linked there, semantics in the language contract, and implementation details beside source/tests. Do not add parallel status/roadmap/runbook documents for each implementation slice. @@ -37,62 +37,6 @@ nix flake check nix build .# ``` -### Current-work handoff - -Read [`STATUS.md`](STATUS.md) at task start and verify inherited notes against -this checkout and the assigned task. Keep it short and limited to current work: -replace stale content at task start, update it at meaningful checkpoints and -before handoff, and mark completion with actual validation and remaining limits. -Each worktree has its own snapshot from its starting commit, not live knowledge -of sibling agents. When integrating branches, reconcile or reset `STATUS.md` -for the receiving worktree rather than concatenating task histories. Keep -lasting knowledge in existing canonical docs; do not create per-task logs. - -### Worktree workflow and retained artifacts - -Work in the assigned worktree, including building new compiler generations there. -Git metadata lives under the parent checkout's `.git/worktrees`; the harness -must grant write access there separately for staging and commits. -Bootstrap artifacts may be absent from a new worktree. Select supplied read-only -artifacts or a verified recovery transfer explicitly; obtain their locations from -the current environment, not from committed machine-specific paths. Keep new -outputs and writable stores in the assigned worktree or fresh temporary locations; -do not modify another checkout's retained artifacts. - -Committed documentation must use repository paths, portable artifact names and -verified identities, or caller-selected input/output variables. Do not record -private worktree/store locations or machine-specific CPU numbers as instructions. - -### Compiler lowering direction - -Stable lowering, including direct self-recursion, is the primary development path -and the future of the language. Select `--backend stable` explicitly for compiler -generations and use `build-stable.arboricx` for applications. Runner backend -defaults are stable; explicit selection still makes evidence unambiguous. -Optimized-backend removal is separate work; retain honest backend labels in -historical evidence. - -Develop in substantial, coherent batches. Compiler-affecting changes require the -strict fresh-store stable generation and self-rebuild gate in -[docs/compiler-rebuilding.md](docs/compiler-rebuilding.md) at explicit batch -acceptance checkpoints, **not after each rewrite, review draft or commit**. -During the batch, use the retained accepted stable compiler to compile changed -modules and affected consumers, and run bounded candidate checks. Commits may -contain tested, unpublished candidates; keep that status and pending acceptance -scope explicit in STATUS.md. An explicitly agreed verified compiler checkpoint -may promote an audited fresh pair plus generation-two smoke checks while deferring -fixture publication and the broad downstream sweep; record that distinction and -retain rollback. See the rebuilding guide. Do not refresh fixtures between drafts. -Agree on the batch scope and focused-check budget before implementation; do not -automatically launch generations, full downstream matrices or repeated benchmarks. - -Verification failures block acceptance and subsequent feature work; only diagnosis -and repair continue. Test repairs with the relevant bounded checks; testing a -repair does not itself require a full generation. Failed generation verification -remains unaccepted until a fresh pair passes at the acceptance checkpoint. Fast -tests, cached equality and fixture refresh are not substitutes for final acceptance. -Full jobs may use at most 64 GiB and two hours; prefer lower bounds for focused work. - ### Host scope: Haskell only Use the Haskell host for implementation, debugging, profiling, benchmarking, @@ -104,40 +48,6 @@ observations as historical evidence. > **Rule of thumb:** if it builds, links, or tests, it goes through `nix`. -### Write and test, don't mentally trace - -Keep `nix flake check` a fast host/unit gate. **Do not add repeated SCP source -compilation, fresh-store module builds, benchmarks, or demo matrices to the -default checks.** Run focused probes for the changed area using an existing -`result/bin/tricu` and a fresh temporary `--store`. SCP is an archived, separate -language experiment under `archive/scp/`, excluded from active build/test inputs. -Its historical commands and removed Nix targets are not current validation paths -or tricu compiler acceptance/recovery prerequisites. -Run the fast gate before committing; report focused integration coverage -separately rather than claiming the default gate ran it. -The fast gate tests authenticated reference artifacts and their recorded source -snapshots, not edited compiler implementations. Run explicit candidate checks -between development slices; require `python3 test/fixture_sources.py current` -and genuinely refreshed fixtures at final batch acceptance. See -[`docs/validation.md`](docs/validation.md#three-distinct-checks). Never relabel -old executable artifacts by changing source fingerprints. - -tricu's minimalism makes it easy to build a confident-sounding but wrong -mental model of evaluation order, branch selection (`matchBool` arg order), -or number encoding. A quick test replaces many minutes of uncertain reasoning. - -Prefer: - -1. Write a candidate implementation. -2. Run the tests or a probe. -3. Fix what's wrong. - -Over: - -1. Reason about semantics across multiple files. -2. Build up a chain of inference. -3. Write code that assumes the chain was correct. - ## Project Overview **tricu** (pronounced "tree-shoe") is a programming-language experiment written primarily in Haskell. @@ -161,7 +71,7 @@ nix flake check ## tricu Language Quick Reference -Before authoring or rewriting `.tri`, read [the language-feature inventory](docs/language-features.md). +Before authoring or rewriting `.tri`, read [the language-feature inventory](docs/language-features.md.html). Check available syntax and library protocols before proposing new machinery or claiming a language gap; verify uncertain behavior with the selected stable compiler. @@ -178,39 +88,3 @@ head (map f xs) → From lib/base.tri -- line comment ``` - -### SCP source style - -Use `archive/scp/lib/consumer/add.scp` as a readable alignment example, not a rigid -format. Within related rule groups, align input patterns, `@`, state patterns, -and `=>` where useful; align parallel output fragments when that exposes their -structure. Prefer spaces and two-space rule indentation. Split long outputs -and indent nested `call`/`match` bodies rather than stretching columns across -an entire file. Clarity beats uniform alignment; avoid unrelated formatting -churn. SCP whitespace between tokens is insignificant (unlike `.tri` below). - -### `.tri` newlines and application grouping - -A newline can end an application even when the preceding line looks like a -partial call. Copy the layout of nearby working `.tri` code. If an application -spans lines, keep the whole application inside parentheses, including its last -argument. In particular, do **not** write `f x = lazyBool` followed by branches -on later lines, or `f x = matchResult` followed by handlers: the subsequent -lines may be parsed outside the definition, causing misleading “Missing -dependencies detected” errors for parameter names. - -```tricu --- Safe: the entire multiline application is explicitly grouped. -probe value = (lazyBool - (_ : ok value t) - (_ : err "bad" t) - (equal? value t)) - --- Also safe: complete application on one line. -probe value = lazyBool (_ : ok value t) (_ : err "bad" t) (equal? value t) -``` - -Inside list literals, parenthesize each non-atomic item: `[(makeRule a b c)]`, -not `[makeRule a b c]`. If a new module reports missing dependencies, isolate -its first failing definition in a tiny focused `eval` probe before changing -semantics or guessing about parentheses. diff --git a/STATUS.md b/STATUS.md @@ -1,48 +0,0 @@ -# Main integration - -James authorized merging the completed modernization into `main` as one squashed -commit, while retaining the development history. Deployment remains separate. - -## History and merge provenance - -- Previous main: `357928f0ceefb2639500ddbe217dfa39f46662ed`. -- Squashed development tip: `1ec8c308918ed611504e1690878b6086000b9352` (213 commits). -- Full history retained on `feat/self-hosted-source-compiler` and annotated tag - `archive/self-hosted-source-compiler-1ec8c30`; neither should be deleted as routine - post-merge cleanup. -- Additional verified complete-history bundle: - `.bootstrap-run/main-squash/development-history.bundle`, with `SHA256SUMS` and - `bundle-verification.log`. This new bundle is local; no off-site copy is claimed. -- Squash index initially matched the development tip's complete Git tree exactly. - Only this receiving-worktree handoff is reconciled afterward. -- Remote refresh failed on an SSH system-configuration ownership error. Local - main matched cached `origin/main`, but the live remote tip was not rechecked. - No push or deployment was performed. - -## Accepted inputs and validation - -Compiler source `e986f18f4239ac0d18fb84e995806761a073fb52` passed the fresh stable -pair: 28 complete manifests, 867 complete indexed trees, exact three-bundle -reproduction, and 12 generation-two smokes. Publication `62bc300` rebuilt all -38 support modules, included the separately tested support-only UTF-8 export-cache -repair, and shipped the compiler plus `bootstrap/rebuild/` kit. The archival -branch's STATUS records detailed focused checks and their limits. - -The recovery transfer under `.bootstrap-run/native-integration/recovery/` passed -3806 checksum checks, relocated pair audits, Git/Nix restoration, and native import -and recursion smokes. James confirmed it is backed up off-machine and off-site. -Retain it, both accepted generations, protected runtimes, support evidence, and -older accepted/rollback closures. No retained artifacts were pruned. - -Final merge validation passed: fast Nix gate (cached checks), fixture freshness, -shipped compiler/kit identity, and exact development-tree equality except this -handoff. Existing source/fixture whitespace is preserved, not reformatted during -integration. No source or compiler implementation changed; no new generation -is required. - -## Next - -Recheck the remote after resolving its SSH configuration issue before pushing. -Deployment requires its own step. Performance, cache granularity, reader-profile -convergence, optimized-path removal, and incremental HTTP receive remain deferred. -Untracked sandbox safety mounts and existing caches are unrelated. diff --git a/archive/scp/README.md b/archive/scp/README.md @@ -10,8 +10,8 @@ Files retain historical contents and repository-relative paths. They are evidenc not a runnable relocated workspace: use Git history for the original integrated checkout. `src/*-fragment.hs` and `test/Spec-fragments.hs` preserve removed host/test fragments and are not standalone modules. Historical usage and language semantics -remain in [the SCP reference](docs/usage.md) and -[language contract](docs/language.md). +remain in [the SCP reference](docs/usage.md.html) and +[language contract](docs/language.md.html). `test/fixtures/` preserves the complete pre-separation mixed support snapshots and receipts, unmodified. Separation initially produced dependency-closed tricu-only @@ -19,4 +19,4 @@ projections with exact export/kernel comparisons. The 38 active support modules have since been genuinely rebuilt with stable lowering; original projected snapshots remain unchanged, and current kernels carry their real native receipts. No compiler identity was relabeled. See -[validation](../../docs/validation.md#scp-archived-experiment). +[validation](../../docs/validation.md.html#scp-archived-experiment). diff --git a/archive/scp/demos/consumers/README.md b/archive/scp/demos/consumers/README.md @@ -1,9 +1,9 @@ # SCP examples Each example lives in a named directory with its sources, runners and data. -Start with the [build/run guide](../../docs/usage.md); logical workspace +Start with the [build/run guide](../../docs/usage.md.html); logical workspace aliases remain explicit in `tricu.workspace`; preparation selects their compiled -artifact exports. Set up `SCP_BOOTSTRAP` using the [SCP guide](../../docs/usage.md). +artifact exports. Set up `SCP_BOOTSTRAP` using the [SCP guide](../../docs/usage.md.html). All 37 library and 15 demo `.tri` modules use native headers. ## Native projects @@ -19,29 +19,29 @@ All 37 library and 15 demo `.tri` modules use native headers. two independently selected line-processing configurations and a compact counter. Its workspace map deliberately references the sibling `data-lines/` sources through explicit workspace-map entries. -- [`fizzbuzz/`](fizzbuzz/README.md): mini-course, computation, project and exact +- [`fizzbuzz/`](fizzbuzz/README.md.html): mini-course, computation, project and exact tree data. Also contains the lambda baseline and reference-IR probes formerly at this index's level. ## Source-running examples and experiments -- [`lessons/`](lessons/README.md): four separate `equality/`, `patterns/`, `size/` +- [`lessons/`](lessons/README.md.html): four separate `equality/`, `patterns/`, `size/` and `source/` lessons, each keeping its `.scp` sources with its `.tri` runner. - [`collect-prefixes/`](collect-prefixes): `stripPrefix`, `mapMaybe`, `find` and an application-specific fallback selector. Compiles source on launch. - [`text-summary/`](text-summary): authored file-read entry/receiver, bootstrap CLI runner and lambda comparison. Effects are handled outside SCP. -- [`source-linked-summary/`](source-linked-summary/README.md): explicit source +- [`source-linked-summary/`](source-linked-summary/README.md.html): explicit source pins and named file-read effects. Also builds source on launch. -- [`echo/`](echo/README.md): minimal named-effect request and success/failure +- [`echo/`](echo/README.md.html): minimal named-effect request and success/failure resumptions, with retained environment. - [`effect-files/`](effect-files/workflows.scp): helper-based file conversion, caller recovery, and ordered runtime batch writes. See the - [focused runner](../../README.md) + [focused runner](../../README.md.html) for reference/lexical checks and optional source-free CAS execution. - [`registry/`](registry): route DSL, generic SCP entry/receiver specimens, retained-state example and lambda comparison. -- [`layout/`](layout/README.md): authored located-token layout transitions and +- [`layout/`](layout/README.md.html): authored located-token layout transitions and independent parser comparisons. Registry and summary lambda entrypoints import shared implementations from @@ -51,9 +51,9 @@ and invoke shared tools; they do not own compiler or deployment semantics. For input/state/result contracts, read the definitions in [`lib/consumer/`](../../lib/consumer) and the -[language contract](../../docs/language.md). Experiment +[language contract](../../docs/language.md.html). Experiment measurements belong with their experiment, not in this example index. In historical checkouts, `nix build .#scpIntegrationTests --no-link` runs the focused Haskell-only artifact and project checks. See the -[archived usage guide](../../docs/usage.md) for checkout requirements. +[archived usage guide](../../docs/usage.md.html) for checkout requirements. diff --git a/archive/scp/demos/consumers/echo/README.md b/archive/scp/demos/consumers/echo/README.md @@ -16,6 +16,6 @@ result/bin/tricu eval test/consumer_echo_lexical.tri --store "$(mktemp -d)" \ It prints `echo-lexical-ok`, followed by the IO return value `t`. The interpreter and earlier prepared-worker comparison lives in `test/consumer_base_effect_protocol.tri`. See the -[language contract](../../../docs/language.md) for the general +[language contract](../../../docs/language.md.html) for the general worker/effect boundary; these are source-running checks, not deployed startup measurements. diff --git a/archive/scp/demos/consumers/fizzbuzz/README.md b/archive/scp/demos/consumers/fizzbuzz/README.md @@ -195,7 +195,7 @@ initial values and combines them with the compiled entry to make a **worker**. That lets us reuse the same code with different starting points. From the repository root, with Nix and GNU `timeout` available, after setting up -`SCP_BOOTSTRAP` as described in the [SCP guide](../../../docs/usage.md): +`SCP_BOOTSTRAP` as described in the [SCP guide](../../../docs/usage.md.html): ```sh nix build .# @@ -238,7 +238,7 @@ The project brings together that workspace, initial state, and invocation name. Its `scp-invocation.result.v1` profile selects direct invocation returning a Result. For configurations that compute state or assemble several workers, projects can instead select an ordinary SCP configuration consumer; the -[SCP guide](../../../docs/usage.md) shows both forms. +[SCP guide](../../../docs/usage.md.html) shows both forms. When you run `prepare`, the workflow: @@ -259,7 +259,7 @@ program. Runtime input can change on every invocation. For deployment, move the record and CAS together, preserving their relative layout, and run them with tricu and the launcher. The build's source files can -stay behind. The [SCP guide](../../../docs/usage.md) also shows the separate +stay behind. The [SCP guide](../../../docs/usage.md.html) also shows the separate phase commands for building code once and configuring it several ways. ## 7. Make the data your own @@ -321,8 +321,8 @@ choices preserve that same Result tree. You have now matched trees, traversed a list, derived explicit state, and combined compiled code with data for repeated invocation. The -[small lessons](../lessons/README.md) take the next step: inspecting executable -trees and comparing their representations. The [SCP guide](../../../docs/usage.md) +[small lessons](../lessons/README.md.html) take the next step: inspecting executable +trees and comparing their representations. The [SCP guide](../../../docs/usage.md.html) covers reusable workers and larger applications; the -[language contract](../../../docs/language.md) gives precise +[language contract](../../../docs/language.md.html) gives precise matching and control semantics. diff --git a/archive/scp/demos/consumers/layout/README.md b/archive/scp/demos/consumers/layout/README.md @@ -7,4 +7,4 @@ in this demo. Stored execution is covered by `test/scp_native_validation.py`. The former cold-source layout shell experiments were removed; their history remains in Git. -See the [SCP guide](../../../docs/usage.md) for the historical project workflow. +See the [SCP guide](../../../docs/usage.md.html) for the historical project workflow. diff --git a/archive/scp/demos/consumers/source-linked-summary/README.md b/archive/scp/demos/consumers/source-linked-summary/README.md @@ -47,6 +47,6 @@ runner configures a separate source CAS under `/tmp`. The command uses printed identifiers attest neither the compiler configuration nor the worker payload. At runtime, a separately prepared native CAS application can load compiled trees without re-reading `.tri`/`.scp` source; see -[the SCP build/run guide](../../../docs/usage.md) +[the SCP build/run guide](../../../docs/usage.md.html) for that distinct path. The commands above **do** compile and link source on launch: do not treat their time as a native-load measurement. diff --git a/archive/scp/docs/lowering.md b/archive/scp/docs/lowering.md @@ -1,8 +1,8 @@ # SCP lowering experiments This history collects the experiments that led to the lexical compiler. Current -semantics live in [the language contract](language.md); -entry points and focused commands live in [the usage guide](usage.md). +semantics live in [the language contract](language.md.html); +entry points and focused commands live in [the usage guide](usage.md.html). Measurements below are historical snapshots of the implementation at each step. ## From authored trees to reusable programs diff --git a/archive/scp/docs/usage.md b/archive/scp/docs/usage.md @@ -3,13 +3,13 @@ SCP is an archived, separate language experiment. This guide records historical usage; these steps are not tricu compiler acceptance or recovery prerequisites. Sources, historical launcher/tests and original mixed fixtures are preserved in -[`archive/scp/`](../README.md). The active executable no longer has a +[`archive/scp/`](../README.md.html). The active executable no longer has a `scp` command, and the former SCP Nix targets no longer exist. Commands and paths below describe historical checkouts, not the current checkout. SCP compiles to reusable tree-calculus entries; configuration is ordinary SCP computation returning named workers. See the [language -contract](language.md) for semantics. `tricu scp` owns typed +contract](language.md.html) for semantics. `tricu scp` owns typed project parsing, bounded phase orchestration, and pinned execution in the Haskell application. Compilation, configuration, and publication actions remain in `consumers.command`. @@ -76,7 +76,7 @@ computed configuration, use the existing `entry`, `input`, `state` form to run an ordinary SCP configuration consumer. Both use the same worker, invocation, and receipt publication authority; the receipt records which profile was used. The runtime input is the tree list 1 through 15. The [FizzBuzz -mini-course](../demos/consumers/fizzbuzz/README.md) derives the clocks from +mini-course](../demos/consumers/fizzbuzz/README.md.html) derives the clocks from first principles and follows this real build/run boundary. ### Author tree data @@ -237,7 +237,7 @@ receipts have distinct identities. Dynamic executable values require trusted, ABI-compatible code. The demos' shell scripts remain advanced examples composing the phase commands: `build-prefix-lines.sh`, `build-data-lines.sh`, and `build-configurations.sh`. Examples are indexed in -[`demos/consumers/README.md`](../demos/consumers/README.md). +[`demos/consumers/README.md`](../demos/consumers/README.md.html). ## Format source @@ -329,7 +329,7 @@ Application-specific workspace maps/configurations belong in `demos/`. Shared loaders, counters, handlers and renderers live in the library. Lambda baselines use `consumers.comparison.*`; alternative lowerings remain explicit experiments. Their progression and historical measurements are collected in [the lowering -experiments](lowering.md). +experiments](lowering.md.html). -Focused checks are in [validation](../../../docs/validation.md#scp-archived-experiment). Historical lowering and +Focused checks are in [validation](../../../docs/validation.md.html#scp-archived-experiment). Historical lowering and effect experiments are not part of ordinary project preparation. diff --git a/docs/arboricx-bundle-format.md b/docs/arboricx-bundle-format.md @@ -350,7 +350,7 @@ Bundles use the `.arboricx` file extension. Plain source files use `.tri`. ## Portable library reader profile `lib/binary.tri` and `lib/arboricx/` implement the following reader profile. -[Focused tests](validation.md#arboricx-reader-rewrites-opt-in) exercise complete replies and error +[Focused tests](validation.md.html#arboricx-reader-rewrites-opt-in) exercise complete replies and error precedence. Reader profiles differ at the container boundary. - Binary input is a proper list of canonical octets. Prefix reads validate only @@ -407,7 +407,7 @@ semantic verification are separate API calls; CLI loading uses both. The browser reader uses strict header/directory checks, contiguous sections, whole-file SHA-256 verification, and explicit byte/node/count limits. Its package and compiler download profiles are documented in the -[playground guide](../ext/demo-site/README.md#ordinary-package-resource-and-safety-boundaries). +[playground guide](../ext/demo-site/README.md.html#ordinary-package-resource-and-safety-boundaries). Canonical writers emit the format described here. Reordered roots/exports or changed metadata affect file identity; canonicalization is deterministic for an diff --git a/docs/build-and-run.md b/docs/build-and-run.md @@ -27,7 +27,7 @@ bundle against its recorded snapshots and published executable tree. Create a UTF-8 source file. Strings and comments support Unicode; identifiers remain ASCII. Malformed UTF-8 and an initial BOM are rejected. See -[source characters](language.md#source-characters-and-tokens). +[source characters](language.md.html#source-characters-and-tokens). ```sh WORK=$(mktemp -d) @@ -47,7 +47,7 @@ result/bin/tricu eval "$WORK/hello.tri" \ `--store` holds application objects, build records, and the automatically imported compiler. The selected stable compiler supports the -[current language features](language-features.md). +[current language features](language-features.md.html). The module exports `main`, which `eval` selects. `first` matches equations in order: a nonempty list returns its first value; the fallback returns zero. @@ -76,11 +76,11 @@ result/bin/tricu arboricx run --module "$APP_MANIFEST" --name main \ This last command executes the stored program. Bundle import defaults to indexed storage, preserving shared branches. Importing native library -dependencies is a different operation; see [modules](modules.md) -and the [artifact checks](tri-tools.md#host-artifact-checks) before choosing flat storage. +dependencies is a different operation; see [modules](modules.md.html) +and the [artifact checks](tri-tools.md.html#host-artifact-checks) before choosing flat storage. For programs with effects, select `--io` and grant the application its own file -permissions. Use trusted store directories. See [execution options](tri-tools.md#io-and-permissions). +permissions. Use trusted store directories. See [execution options](tri-tools.md.html#io-and-permissions). `WORK` is temporary and contains all objects created by this example. Keep it if you want to reuse them, or remove it when finished. @@ -106,14 +106,14 @@ to the application store. An explicit selection never falls back to package data Run `result/bin/tricu` (or `result/bin/tricu repl`) for a portable session. Definitions and expressions use the same compiler as files. Use `!help` for multiline blocks, imports, loading files, and session operations; see -[interactive semantics](tri-tools.md#interactive-sessions). +[interactive semantics](tri-tools.md.html#interactive-sessions). ## Where next -- [Language features](language-features.md) and [contracts](contracts.md). -- [Modules](modules.md) for imports and exports. -- [Tools](tri-tools.md) for formatting, IO, and compiler options. -- [Testing](validation.md): start with `nix flake check`; understand the difference +- [Language features](language-features.md.html) and [contracts](contracts.md.html). +- [Modules](modules.md.html) for imports and exports. +- [Tools](tri-tools.md.html) for formatting, IO, and compiler options. +- [Testing](validation.md.html): start with `nix flake check`; understand the difference between reference tests, candidate checks, and compiler acceptance. -- [Compiler rebuilding](compiler-rebuilding.md): for changing or recovering the +- [Compiler rebuilding](compiler-rebuilding.md.html): for changing or recovering the compiler. diff --git a/docs/compiler-rebuilding.md b/docs/compiler-rebuilding.md @@ -6,7 +6,7 @@ compiler builds itself again from the same frozen source. Independent audits verify both generations and their reproduced outputs. For ordinary application authoring, use the included compiler and -[Build and run](build-and-run.md). Rebuilding uses either an explicit bootstrap +[Build and run](build-and-run.md.html). Rebuilding uses either an explicit bootstrap kit containing the map-builder and standard IO adapter, or a completed generation from which those executables can be selected. The standalone application compiler has a different entrypoint. @@ -99,7 +99,7 @@ independent audits, and publication requirements below still apply. Agree on a coherent change and focused-check budget before implementation. Compile changed modules and affected consumers with the accepted stable compiler. Check complete results, diagnostics, demand, effects, integrity, and relevant -workloads against independent expectations. [Testing](validation.md) distinguishes +workloads against independent expectations. [Testing](validation.md.html) distinguishes these candidate checks from reference-artifact tests and acceptance. Several reviewable candidate commits may precede a generation checkpoint. Record @@ -168,7 +168,7 @@ whole-file SHA256 in `src/Main.hs` (`packagedCompilerSha256`) alongside its receipt identity is this bundle digest, not its indexed transport object hash. Publish genuinely rebuilt compiler and support fixtures using the procedures in -[Testing](validation.md#compiler-transport-and-publication). Capture matching source +[Testing](validation.md.html#compiler-transport-and-publication). Capture matching source snapshots, then check freshness and the fast gate: ```sh @@ -337,4 +337,4 @@ interruption, corruption, backend selection, and receipt options. An older closu can use an explicit `--worker-bundle`. The transport probe compiles an adapter through the selected portable toolchain and checks unit exports and loading. Its diagnostic checkpoints do not constitute an ordinary completed generation. -See [Storage](storage.md#verified-native-tree-transport) for the transport contract. +See [Storage](storage.md.html#verified-native-tree-transport) for the transport contract. diff --git a/docs/compiler.md b/docs/compiler.md @@ -5,8 +5,8 @@ already-resolved external trees, then produces executable trees and diagnostics. The Haskell host supplies reduction, file IO, hashing, verified transport, and bundle packing. -[Language](language.md) defines source semantics; [Modules](modules.md) defines -acquisition and publication; [Compiler rebuilding](compiler-rebuilding.md) +[Language](language.md.html) defines source semantics; [Modules](modules.md.html) defines +acquisition and publication; [Compiler rebuilding](compiler-rebuilding.md.html) explains how to change and verify the compiler. ## Pipeline @@ -33,7 +33,7 @@ lists become canonical Fork cells, and local bindings become scoped applications A singleton all-name function head takes the ordinary lambda path; other equation groups retain located patterns until resolution. -The [parser protocol](parser.md) defines consumption, commitment, rollback, and +The [parser protocol](parser.md.html) defines consumption, commitment, rollback, and repetition. Binary and HTTP consumers share those primitives with the compiler. ## Unit interfaces @@ -150,7 +150,7 @@ application store. Application IO receives its own grants. Indexed tool objects preserve sharing through loading. Their object hashes differ from flat tree-term hashes, so changing transport representation also changes the explicit compiler identity used in receipts. Native module publication uses -indexed objects with the same name-neutral format as CLI import. See [Storage](storage.md) for these identities and the +indexed objects with the same name-neutral format as CLI import. See [Storage](storage.md.html) for these identities and the complete-interface cache rules. ## Checks @@ -158,7 +158,7 @@ complete-interface cache rules. The test suite has independent token/span, AST/core, scope, diagnostic, pattern, and recursion expectations. Demand controls check opaque or divergent unused fields. Integrity checks cover module, receipt, object, and bundle publication. -[Testing](validation.md) separates retained-reference tests from candidate +[Testing](validation.md.html) separates retained-reference tests from candidate execution and fresh-generation acceptance. ## Investigating optimized construction @@ -189,7 +189,7 @@ for a selected compiler, not requirements imposed on stable source style. The three `lib/source/*experiment.tri` modules are opt-in compiler research, separate from canonical syntax and the production compiler map. Their contracts below describe the experiments; ordinary programs use the -[stable language](language.md). [Testing](validation.md#research-and-costs) documents +[stable language](language.md.html). [Testing](validation.md.html#research-and-costs) documents bounded Haskell-only checks using explicitly prepared artifacts. ### Trusted compiler IR @@ -290,4 +290,4 @@ positions count scalars, not bytes or display cells. Existing explicit-scalar lexer fixtures check character handling, not file decoding; the opt-in `test/native_source_utf8.py` checks the file boundary with current consumers. The included compiler has not yet been republished with this candidate boundary. -See [source characters](language.md#source-characters-and-tokens). +See [source characters](language.md.html#source-characters-and-tokens). diff --git a/docs/contracts.md b/docs/contracts.md @@ -261,7 +261,7 @@ before returning the failure Result. The host desugarer is `src/Frontend/ContractDesugar.hs`; the portable source compiler has its own corresponding lowering. The accepted profile is described -in [the source profile](language.md). +in [the source profile](language.md.html). ## 7. Modules and content-addressed storage @@ -272,8 +272,8 @@ exported contracts explicitly. The module manifest records names, object kinds, hashes, and ABIs. Content verification authenticates the stored checking code; whether a program invokes -that code follows its implementation. See [Modules](modules.md) and -[Storage](storage.md) for publication and identity. +that code follows its implementation. See [Modules](modules.md.html) and +[Storage](storage.md.html) for publication and identity. ## 8. Handling failures @@ -311,5 +311,5 @@ unchecked hash-taking writer. It preserves the existing replace-on-upload policy the hash contract does not validate bundle contents or supply general symlink containment. Root is trusted configuration, and host permissions remain necessary. -See [registry pipeline validation](validation.md#registry-server-pipelines-opt-in) +See [registry pipeline validation](validation.md.html#registry-server-pipelines-opt-in) for current artifact checks and their limits. diff --git a/docs/language-features.md b/docs/language-features.md @@ -4,9 +4,9 @@ tricu combines functions, structural patterns, local bindings, and explicit sequencing. This guide shows the tools available when writing programs with the included stable compiler. -[Language](language.md) specifies syntax and semantics; [Modules](modules.md) -covers imports and exports. Use [Build and run](build-and-run.md) to select the -compiler and [Testing](validation.md) when changing implementations. +[Language](language.md.html) specifies syntax and semantics; [Modules](modules.md.html) +covers imports and exports. Use [Build and run](build-and-run.md.html) to select the +compiler and [Testing](validation.md.html) when changing implementations. ## Select the stable compiler @@ -16,7 +16,7 @@ Native modules declare their dependencies and exports. The lower-level unit API receives a definition body and resolved external trees instead. Function representations remain inspectable and backend-sensitive. See -[Compiler architecture](compiler.md) for lowering, construction costs, and the +[Compiler architecture](compiler.md.html) for lowering, construction costs, and the separate optimized backend. ## Choose a tool @@ -105,7 +105,7 @@ from ASCII examples; use the relevant codec/API contract. Evidence: [source parser](../lib/source/parser.tri), [equation parser](../lib/source/equations.tri), and `test/Spec.hs` local-binding, -pipe-precedence and layout tests. The [formatter](tri-tools.md#tri-equation-alignment) +pipe-precedence and layout tests. The [formatter](tri-tools.md.html#tri-equation-alignment) aligns eligible equation heads. ## Explicit sequencing operators @@ -140,7 +140,7 @@ library functions. Evidence: [do AST lowering](../lib/source/ast.tri), [contract-effects demo](../demos/contractEffects.tri), [Result/Maybe helpers](../lib/base.tri), [IO helpers](../lib/io.tri), and -[parser protocol](parser.md). Portable `do` tests in +[parser protocol](parser.md.html). Portable `do` tests in `test/Spec.hs` include custom operators, nested blocks, and ignored statements. ## Library conventions worth checking before inventing helpers @@ -169,7 +169,7 @@ Evidence: [do AST lowering](../lib/source/ast.tri), libraries share this binary engine with base arithmetic, add `divMod` and exponentiation by squaring, and format decimal numbers by repeated division by ten. The checked base facade rejects zero divisors; the raw kernel has an - explicit degenerate zero convention. See [numeric boundaries](contracts.md#arithmetic-and-decimal-boundaries). + explicit degenerate zero convention. See [numeric boundaries](contracts.md.html#arithmetic-and-decimal-boundaries). - `graph` sorts small, caller-validated dependency graphs in earliest-ready input order and reports a name on an actual cycle. Names are opaque trees; uniqueness, proper lists, and dependency existence remain caller obligations. @@ -190,13 +190,13 @@ Evidence: [do AST lowering](../lib/source/ast.tri), `finally` preserves the action's ordinary result and ignores the cleanup result. Neither guarantees cleanup after abort, divergence or host exceptions. These are explicit interaction trees; real effects need - the Haskell IO driver and permissions. Consult [host ABI](host-abi.md). + the Haskell IO driver and permissions. Consult [host ABI](host-abi.md.html). - Contract helpers include `checkContract`, `withContract`, `guardC`, collection/higher-order combinators, and `x@contract` / `=@contract` annotations. Contracts and Boolean predicates have different protocols. Annotated success is a plain value, while failure is a Result; annotations are not composable with patterned/multi-equation heads in the current profile. Read - [contracts](contracts.md) before using them. + [contracts](contracts.md.html) before using them. ## Native modules @@ -210,7 +210,7 @@ There is no ambient workspace lookup, implicit prelude, or fallback to another frontend after compilation failure. Dependency cycles and name/export collisions are errors. The native profile requires a nonempty public interface and rejects bare final expressions; export `main` for CLI evaluation. See the -[module contract](modules.md) for exact rules. +[module contract](modules.md.html) for exact rules. ## Small combined example @@ -253,7 +253,7 @@ main = [(copy [1 2]) (isMarker 7) (isMarker 8) (keep (t 3 4)) The result contains, in order: `[1 2]`, `1`, `0`, the pair `t 3 4`, `5`, `99`, `6`, `8`, `9`. Compile/run through the stable portable route in -[tri-tools](tri-tools.md). +[tri-tools](tri-tools.md.html). ## Local expression matching and recursion @@ -274,8 +274,8 @@ as an application argument. Matching reuses equation order, captures, pins and final-irrefutable coverage; an initial wildcard need not inspect its subject. Unselected bodies are not run, but every body is checked for valid names. `case`, `of`, and `rec` are reserved words. See the -[language contract](language.md#expression-matching-and-explicit-local-recursion) -and [focused checks](validation.md#local-control-candidates-opt-in). +[language contract](language.md.html#expression-matching-and-explicit-local-recursion) +and [focused checks](validation.md.html#local-control-candidates-opt-in). ## Extending a program @@ -286,5 +286,5 @@ and explicit combinators adapt sequencing protocols. Before replacing a library call, check its argument order, remainder, and failure conventions. Decide which tree identities and malformed-input behavior matter to the caller. Compile a small candidate, check complete results, and measure costs -on a useful workload. Follow [Testing](validation.md) for candidate validation and +on a useful workload. Follow [Testing](validation.md.html) for candidate validation and publication. diff --git a/docs/language.md b/docs/language.md @@ -1,9 +1,9 @@ # The tricu language This is the source contract for the stable compiler shipped with tricu. See -[Build and run](build-and-run.md) for compiler selection and -[Language features](language-features.md) for practical examples. -[Modules](modules.md) specifies the directive header and dependency resolution. +[Build and run](build-and-run.md.html) for compiler selection and +[Language features](language-features.md.html) for practical examples. +[Modules](modules.md.html) specifies the directive header and dependency resolution. ## Trees and application @@ -226,7 +226,7 @@ one-value binding requires an explicit choice about the remainder. annotated call returns the checked plain value; failure is an in-band Result. Compound contract expressions are parenthesized. Named and phantom annotation forms have separate binding rules. Annotations belong to ordinary definitions, -rather than patterned or multi-equation heads. See [Contracts](contracts.md) for calling conventions, +rather than patterned or multi-equation heads. See [Contracts](contracts.md.html) for calling conventions, transformed values, higher-order proxies, and effects. ## Source formatting @@ -244,5 +244,5 @@ preserved; malformed lexing returns the original source. Header masking is used only for recognition. Line endings and final-newline presence survive formatting. The formatter uses located syntax without resolving names or requiring complete -equation coverage. See [Tools](tri-tools.md#tri-equation-alignment) for preparation +equation coverage. See [Tools](tri-tools.md.html#tri-equation-alignment) for preparation and use. diff --git a/docs/modules.md b/docs/modules.md @@ -17,8 +17,8 @@ main = M.add 20 22 For the CLI's flat workspace, put dependencies in the input file's directory: `prelude.tri`, `math.tri`, and their declared dependencies. Workspace module names start with an ASCII letter or underscore and continue with letters, digits, -underscores, or hyphens. Use [Build and run](build-and-run.md) to select the stable -compiler, and [Tools](tri-tools.md) for larger mapped library workspaces. +underscores, or hyphens. Use [Build and run](build-and-run.md.html) to select the stable +compiler, and [Tools](tri-tools.md.html) for larger mapped library workspaces. ## Headers @@ -64,7 +64,7 @@ results may have different trees; tricu programs can observe that difference. Native module objects use `arboricx.indexed-tree.v1`, and their manifests use `arboricx.module-manifest.v1`. The CLI's default indexed import supplies native -imports, stored execution, and compiler selection without flat expansion. [Storage](storage.md) defines the representations, hashes, +imports, stored execution, and compiler selection without flat expansion. [Storage](storage.md.html) defines the representations, hashes, conversion budget, receipts, and cache rules. ## Publication @@ -89,5 +89,5 @@ the neutral alias-file format. This is separate from graph workspace resolution. `lib/source/{module,object,lock,build,map,bundle}.tri` owns native module policy. The Haskell host supplies primitive IO and typed tree transport. Its separate store and recovery frontend support CLI artifact operations and recovery tools. -[Compiler architecture](compiler.md) describes the build boundary; -[Testing](validation.md) lists the module and graph probes. +[Compiler architecture](compiler.md.html) describes the build boundary; +[Testing](validation.md.html) lists the module and graph probes. diff --git a/docs/parser.md b/docs/parser.md @@ -105,5 +105,5 @@ consumers provide their own location and context adapters. The HTTP receiver caps the entire accumulated receive buffer, including any body bytes prefetched in the final chunk. Delimiter detection preserves the exact suffix. The current accumulation/search path can repeat work as chunks arrive. -See [HTTP pipeline checks](validation.md#http-syntax-and-framing) for coverage +See [HTTP pipeline checks](validation.md.html#http-syntax-and-framing) for coverage and cost measurements when changing this path. diff --git a/docs/self-hosted-arboricx-host.md b/docs/self-hosted-arboricx-host.md @@ -6,7 +6,7 @@ and decode the returned value. This keeps bundle parsing and result validation in tricu while the host supplies Tree Calculus execution. This guide describes the embedding boundary. For native development and -validation with the Haskell host, follow [Build and run](build-and-run.md). +validation with the Haskell host, follow [Build and run](build-and-run.md.html). ## Two programs @@ -52,7 +52,7 @@ err code rest = pair false (pair code rest) Raw runners return the application's tree. Typed runners return a tagged value, for example `ok (hostString characters) rest`. Unwrap the Result, then its `pair tag payload` envelope, then decode the payload for that tag. -[Host ABI](host-abi.md) specifies canonical encodings and codec failures. +[Host ABI](host-abi.md.html) specifies canonical encodings and codec failures. The reader validates the bundle, reconstructs the selected tree from backward node indices, and applies arguments in order. Typed result validation happens @@ -61,11 +61,11 @@ logical tree can require far more work than the indexed input size suggests. ## Verification -Use the [bundle format](arboricx-bundle-format.md) and its reader profiles when +Use the [bundle format](arboricx-bundle-format.md.html) and its reader profiles when choosing an ingestion boundary. Authenticate selected artifact bytes and set input, execution, and result-observation budgets independently. A valid bundle can contain a program that does not terminate. `test/Spec.hs` covers executable selection, ordered arguments, canonical codecs, and typed success/failure results. The browser has independent parser and runtime -controls. See [Testing](validation.md) for reference-artifact and candidate checks. +controls. See [Testing](validation.md.html) for reference-artifact and candidate checks. diff --git a/docs/storage.md b/docs/storage.md @@ -95,7 +95,7 @@ broader text/name profile, with typed constraints applied by consumers. Contracts are ordinary trees. An annotated export carries its checking code inside the executable; a separately exported contract is invoked by its consumer. -See [Contracts](contracts.md#7-modules-and-content-addressed-storage). +See [Contracts](contracts.md.html#7-modules-and-content-addressed-storage). ## Aliases @@ -193,4 +193,4 @@ decodes the entire tree before reuse. Invalid indices or corrupt objects fail. Restart still stages, parses, orders, resolves, and constructs the definition environment. It skips materializing completed exports. Module manifests and receipts publish after all required exports complete. See -[Compiler rebuilding](compiler-rebuilding.md) for closure audits and acceptance. +[Compiler rebuilding](compiler-rebuilding.md.html) for closure audits and acceptance. diff --git a/docs/tri-tools.md b/docs/tri-tools.md @@ -1,8 +1,8 @@ # Compile, run, and format -[Build and run](build-and-run.md) sets up the included stable compiler and a first +[Build and run](build-and-run.md.html) sets up the included stable compiler and a first application. The commands below use its `WORK` variable. -[Language](language.md) and [Modules](modules.md) define source behavior. +[Language](language.md.html) and [Modules](modules.md.html) define source behavior. ## Compile and evaluate @@ -53,8 +53,8 @@ representations. Compiler-generation backend selection is separate: generation runners use `--backend stable`. The retained optimized application artifact is `build.arboricx`. -See [Compiler architecture](compiler.md#stable-and-optimized-lowering) for its -abstraction and demand behavior, and [Compiler rebuilding](compiler-rebuilding.md) +See [Compiler architecture](compiler.md.html#stable-and-optimized-lowering) for its +abstraction and demand behavior, and [Compiler rebuilding](compiler-rebuilding.md.html) for generation procedures. ## Stored execution @@ -100,7 +100,7 @@ update. Typed object reads verify domain-separated digests before decoding. Use the whole-bundle SHA-256 for registry downloads, and module manifest hashes for CLI -execution. [Storage](storage.md) specifies these identities and trust boundaries. +execution. [Storage](storage.md.html) specifies these identities and trust boundaries. ### Indexed and flat objects @@ -153,7 +153,7 @@ change bytes. `--write` replaces the file atomically, preserving permissions and refusing symbolic links. Select one of those modes at a time. `--seconds` bounds loading and formatting, defaulting to 60. Invalid UTF-8, bad artifacts, and cancellation fail before replacement. See the -[formatting contract](language.md#source-formatting) for which groups are aligned. +[formatting contract](language.md.html#source-formatting) for which groups are aligned. ## Library workspaces and demos @@ -170,7 +170,7 @@ The helper preserves native source and binds complete dependency manifests. Supply additional prepared dependencies with repeatable `--dependencies`, or select libraries in dependency order. Import the resulting bundle indexed and run its selected export as above. Command and batch budgets default to 20 minutes; -full-cohort work uses explicitly selected limits from [Testing](validation.md). +full-cohort work uses explicitly selected limits from [Testing](validation.md.html). ## Interactive sessions diff --git a/docs/validation.md b/docs/validation.md @@ -1,9 +1,9 @@ # Testing Use the Haskell host only; build/link/test through Nix, never direct `cabal`. -See [build/run](build-and-run.md) for guide selection and the -[language-feature inventory](language-features.md) before `.tri` edits. -For representation-sensitive work, see [Compiler architecture](compiler.md). +See [build/run](build-and-run.md.html) for guide selection and the +[language-feature inventory](language-features.md.html) before `.tri` edits. +For representation-sensitive work, see [Compiler architecture](compiler.md.html). ## Fast gates @@ -49,7 +49,7 @@ barrier. A verified compiler checkpoint may explicitly defer publication: retain the audited fresh pair and generation-two native-import/recursion/program smoke coverage, leaving reference fixtures and working-source freshness pending. This permits subsequent candidate work with the verified compiler but is not final -publication of the compiler/support cohort. See [compiler rebuilding](compiler-rebuilding.md#development-batches-and-acceptance-checkpoints). +publication of the compiler/support cohort. See [compiler rebuilding](compiler-rebuilding.md.html#development-batches-and-acceptance-checkpoints). ## Three distinct checks @@ -224,7 +224,7 @@ The driver uses scripted effects. HTTP cleanup attempts close after an ordinary send Result and preserves the primary failure; terminal aborts and host exceptions are separate. Expectations include error precedence, EOF, bucketed reads, exact body lengths, binary suffixes, and the whole-buffer receive cap described in -[Parser](parser.md#http-framing-and-receive-costs). +[Parser](parser.md.html#http-framing-and-receive-costs). For receiver changes, evaluate ordinary headers, fragmented reads, near-limit success/failure, and representative concurrent IO. Preserve limit-before-acceptance @@ -351,9 +351,9 @@ independently, not treated as extensional equivalence claims. ## SCP: archived experiment SCP sources, commands, tests, demos, and the mixed workspace dispatcher are under -[`archive/scp/`](../archive/scp/README.md). They are not installed, tested or +[`archive/scp/`](../archive/scp/README.md.html). They are not installed, tested or required by active tricu builds. The former SCP Nix targets have been removed. -Historical commands in [the SCP reference](../archive/scp/docs/usage.md) require a historical checkout. +Historical commands in [the SCP reference](../archive/scp/docs/usage.md.html) require a historical checkout. The original fixture projection is recorded in `test/fixtures/support-projection.json`. Its immutable origin fingerprints remain checked inputs; rebuilt outputs are @@ -365,7 +365,7 @@ Keep its historical ledger distinct from later compilation publications. ## Compiler, transport, and publication -See [compiler rebuilding](compiler-rebuilding.md) for artifact prerequisites, +See [compiler rebuilding](compiler-rebuilding.md.html) for artifact prerequisites, backend selection, guarded generations, and independent closure audits. Runners default to stable; select it explicitly in recorded commands. @@ -438,7 +438,7 @@ Run formatter integration separately. Report preparation, loading, compilation, publication, allocation, RSS, logical size and DAG size separately. Direct-child RSS is not a descendant total. Guard stops / missing measurements remain failures, not successful coverage. -Research-profile contracts are in [Compiler architecture](compiler.md#experimental-staging-profiles). +Research-profile contracts are in [Compiler architecture](compiler.md.html#experimental-staging-profiles). ## Local-control candidates (opt-in) @@ -524,7 +524,7 @@ same-arity wrong-export control uses `parserOptional` in place of `parserMany`. Record/authenticate driver source, receipts, compiler/options, dependencies and complete manifest separately. Parser edits are compiler-affecting: these focused checks do not replace the fresh stable generation/self-rebuild and publication -requirements in [compiler rebuilding](compiler-rebuilding.md). +requirements in [compiler rebuilding](compiler-rebuilding.md.html). ## Foundational list workload comparisons (opt-in) @@ -645,7 +645,7 @@ Independent compiler models, cases, and probe templates live in the models and corpus invariants. Use compiled candidate artifacts to test edited implementations, alongside the reference and acceptance checks described above. -Current formatter preparation is documented in [tri-tools](tri-tools.md#tri-equation-alignment) +Current formatter preparation is documented in [tri-tools](tri-tools.md.html#tri-equation-alignment) and uses `test/prepare_formatter.py`, without historical reference inputs. `python3 test/shipped_compiler.py` checks the shipped accepted builder against its recorded sources and published executable tree, without generating a compiler. diff --git a/lib/math/README.md b/lib/math/README.md @@ -55,7 +55,7 @@ main input = N.add input 1 ``` Select a retained compiler artifact explicitly, as described in -[the portable tool guide](../../docs/tri-tools.md). Internal helpers are private. +[the portable tool guide](../../docs/tri-tools.md.html). Internal helpers are private. The test runner prepares such a workspace automatically. ## Implementation and limits @@ -76,7 +76,7 @@ appropriate boundary for the caller. ## Validation -The [numeric checks](../../docs/validation.md#numeric-and-decimal-candidates-opt-in) +The [numeric checks](../../docs/validation.md.html#numeric-and-decimal-candidates-opt-in) use independent integer, Boolean, and complete-tree expectations. Candidate preparation and fixture publication are separate from reference-artifact tests. Measure selected workloads with a recorded compiler; changing function trees can