From 91e96af97c1839f20cf706104a4ff49fda248e40 Mon Sep 17 00:00:00 2001 From: Haitian Chen <16521919+erthoaers@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:06:56 -0800 Subject: [PATCH 1/3] docs: state the formula conversion rules with kalyx --- docs/architecture.md | 50 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index febef88..1bc6570 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,8 @@ # Architecture This page states the design rules of kosmo's first release for the editing -structure of formulas, versions, the host job layer, the keyboard event record, +structure of formulas, versions, formula conversion with kalyx, the host job +layer, the keyboard event record, the source layout, the platform boundary, the framework, and rendering, text and determinism. It also names the two frontends of the first release and lists every component with its verification level. @@ -253,6 +254,53 @@ result: - Handling a still-running job whose history entry was evicted is defined with the Scratchpad. +## Formula conversion + +kosmo gives kalyx a formula as linear text and reads every result back from +kalyx's output line. These rules hold for kalyx 0.1.0, the version that the +first release locks. When kosmo moves to a later kalyx version, they are +checked again against that version's grammar and output lines. + +- **Only complete input.** An incomplete or invalid structure produces no + text and submits no job; conversion returns its holes or the position that + makes it invalid instead. `□` is never sent. +- **Only the locked grammar.** Conversion writes only forms that kalyx + 0.1.0's grammar reads: + - no juxtaposition, and no digit directly followed by a name: kosmo treats + `2x` as a juxtaposition, and kalyx reads it as one invalid number literal, + never as a product; + - no unary plus and no character outside ASCII; + - `.5` and `1.` are written as `0.5` and `1`. + + Function-call syntax and reserved names are passed on unchanged, and kalyx + reports them as `Unsupported`. +- **The grammar only grows.** Text that kalyx 0.1.0 accepts reads the same in + every later kalyx version. Writings that it rejects, such as calls and + reserved names, may later get a value or a different error, so they are + judged again when kosmo moves to a later version. +- **Results only through output lines.** The submitter receives a result only + as the output line that `kalyx::command::serialize` writes, and parses it + with the display model. kalyx terms and `Outcome` stay with the kalyx runner + on the worker thread; the runner takes the outcome kind and the error class + from the `Outcome`. kosmo never uses kalyx's debug output. The wording of an + error's message is not part of kalyx's interface, so kosmo reads the other + fields of the line. +- **Spans.** The span of an error is a half-open range of bytes of the linear + text, and it may be empty. kosmo maps it back to a position in the editing + structure: a non-empty span to a block with a range of items, an empty span + to the position between two items, and the span `-` to the whole line. +- **Versions.** The output line echoes the three versions of the request. The + job layer first checks them against the request: outside `cancel_requested`, + a mismatch ends the job as `failed`. Whether the result is current is then + judged from the three versions and the submission, as + [current, superseded and stale results](#current-superseded-and-stale-results) + describes. +- **Reading back.** The display text of every value of kalyx 0.1.0 is input + of its grammar that reads back as the same term, so a result can be read + back into an editing structure and reused. Reading back runs under the + limits of a request; a term near those limits reads back only under larger + limits. + ## Completion and cancellation kalyx's command contract leaves the order of a cancel request and a stop From b970705216a3a58633162edfc04068de238d2961 Mon Sep 17 00:00:00 2001 From: Haitian Chen <16521919+erthoaers@users.noreply.github.com> Date: Sun, 15 Nov 2026 21:16:54 -0800 Subject: [PATCH 2/3] docs: apply review to the formula conversion rules --- docs/architecture.md | 81 ++++++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 1bc6570..9c04251 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,10 +2,10 @@ This page states the design rules of kosmo's first release for the editing structure of formulas, versions, formula conversion with kalyx, the host job -layer, the keyboard event record, -the source layout, the platform boundary, the framework, and rendering, text -and determinism. It also names the two frontends of the first release and -lists every component with its verification level. +layer, the keyboard event record, the source layout, the platform boundary, +the framework, and rendering, text and determinism. It also names the two +frontends of the first release and lists every component with its verification +level. The rules are fixed before the code that follows them. So far the only product code is the `kosmo` program, which only reports its version: every component @@ -256,24 +256,26 @@ result: ## Formula conversion -kosmo gives kalyx a formula as linear text and reads every result back from -kalyx's output line. These rules hold for kalyx 0.1.0, the version that the -first release locks. When kosmo moves to a later kalyx version, they are -checked again against that version's grammar and output lines. - -- **Only complete input.** An incomplete or invalid structure produces no - text and submits no job; conversion returns its holes or the position that - makes it invalid instead. `□` is never sent. -- **Only the locked grammar.** Conversion writes only forms that kalyx - 0.1.0's grammar reads: +kosmo gives kalyx a formula as linear text and takes every result from kalyx's +output line. Conversion runs before submission, so a job carries only the +linear text. These rules hold for kalyx 0.1.0, the version that the first +release locks. When kosmo moves to a later kalyx version, they are checked +again, and revised where needed, against that version's grammar and output +lines. + +- **Only complete input.** Conversion produces no text for an incomplete or + invalid structure, so no job is submitted; it returns the holes or the + position that makes the structure invalid instead, as + [holes and completeness](#holes-and-completeness) defines them. +- **Only the locked grammar.** Conversion writes only forms that kalyx 0.1.0's + grammar accepts, with one exception: - no juxtaposition, and no digit directly followed by a name: kosmo treats `2x` as a juxtaposition, and kalyx reads it as one invalid number literal, never as a product; - no unary plus and no character outside ASCII; - - `.5` and `1.` are written as `0.5` and `1`. - - Function-call syntax and reserved names are passed on unchanged, and kalyx - reports them as `Unsupported`. + - `.5` and `1.` are written as `0.5` and `1`; + - the exception is function-call syntax and reserved names: conversion + passes them on unchanged, and kalyx reports them as `Unsupported`. - **The grammar only grows.** Text that kalyx 0.1.0 accepts reads the same in every later kalyx version. Writings that it rejects, such as calls and reserved names, may later get a value or a different error, so they are @@ -281,25 +283,32 @@ checked again against that version's grammar and output lines. - **Results only through output lines.** The submitter receives a result only as the output line that `kalyx::command::serialize` writes, and parses it with the display model. kalyx terms and `Outcome` stay with the kalyx runner - on the worker thread; the runner takes the outcome kind and the error class - from the `Outcome`. kosmo never uses kalyx's debug output. The wording of an - error's message is not part of kalyx's interface, so kosmo reads the other - fields of the line. + on the worker thread (see [host job layer](#host-job-layer)); the runner + takes the outcome kind and the error class from the `Outcome`, or from + `serialize` when writing the line fails, as + [protocol stub types](#protocol-stub-types) state. kosmo never uses the + `Debug` formatting of kalyx's types. The wording of an error's message is + not part of kalyx's interface, so kosmo reads the other fields of the line. - **Spans.** The span of an error is a half-open range of bytes of the linear - text, and it may be empty. kosmo maps it back to a position in the editing - structure: a non-empty span to a block with a range of items, an empty span - to the position between two items, and the span `-` to the whole line. -- **Versions.** The output line echoes the three versions of the request. The - job layer first checks them against the request: outside `cancel_requested`, - a mismatch ends the job as `failed`. Whether the result is current is then - judged from the three versions and the submission, as + text, and it may be empty. The submitter maps it back into the snapshot that + the text was converted from: a non-empty span to a fragment, an empty span + to a position, which is an index between items, and an error without a + span, written `-`, to the whole line. +- **Version echo.** The output line echoes the three versions of the request. + The job layer first checks them against the request: outside + `cancel_requested`, a mismatch ends the job as `failed`, as + [terminal states](#terminal-states) describes. Whether the result is current + is then judged from the three versions and the submission, as [current, superseded and stale results](#current-superseded-and-stale-results) describes. -- **Reading back.** The display text of every value of kalyx 0.1.0 is input - of its grammar that reads back as the same term, so a result can be read - back into an editing structure and reused. Reading back runs under the - limits of a request; a term near those limits reads back only under larger - limits. +- **Reading back.** The display text of every value of kalyx 0.1.0 is text + that its grammar accepts and reads back as the same term, so a value can be + read back into a separate editing structure, which reuse inserts into the + buffer as a copy. That structure is checked against the editing structure's + own limits, as [node identity](#node-identity) states. When the text is + submitted again, kalyx reads it under the limits of that request like any + other input, so the text of a term near those limits is read only under + larger limits. ## Completion and cancellation @@ -521,8 +530,8 @@ job at a time in the order it receives them. - Results return only as output lines, which the submitter parses with the display model. - There is no settings field; the kalyx runner always passes `Settings::new()`. -- All conversion is in the kalyx runner, which builds `Request` and `Context` - on the worker thread; kalyx terms never leave it. +- All conversion into kalyx types is in the kalyx runner, which builds + `Request` and `Context` on the worker thread; kalyx terms never leave it. - A resource scope has no field yet; it will be a new field with a default. | kalyx `Request` field | Filled from | From c0de2874511e402047708515b02ae5546f0e071c Mon Sep 17 00:00:00 2001 From: Haitian Chen <16521919+erthoaers@users.noreply.github.com> Date: Sun, 15 Nov 2026 21:23:38 -0800 Subject: [PATCH 3/3] docs: tighten the wording of the formula conversion rules --- docs/architecture.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 9c04251..de87c61 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -268,7 +268,7 @@ lines. position that makes the structure invalid instead, as [holes and completeness](#holes-and-completeness) defines them. - **Only the locked grammar.** Conversion writes only forms that kalyx 0.1.0's - grammar accepts, with one exception: + grammar accepts, with one exception that the last item names: - no juxtaposition, and no digit directly followed by a name: kosmo treats `2x` as a juxtaposition, and kalyx reads it as one invalid number literal, never as a product; @@ -286,14 +286,14 @@ lines. on the worker thread (see [host job layer](#host-job-layer)); the runner takes the outcome kind and the error class from the `Outcome`, or from `serialize` when writing the line fails, as - [protocol stub types](#protocol-stub-types) state. kosmo never uses the + [protocol stub types](#protocol-stub-types) states. kosmo never uses the `Debug` formatting of kalyx's types. The wording of an error's message is not part of kalyx's interface, so kosmo reads the other fields of the line. - **Spans.** The span of an error is a half-open range of bytes of the linear text, and it may be empty. The submitter maps it back into the snapshot that the text was converted from: a non-empty span to a fragment, an empty span - to a position, which is an index between items, and an error without a - span, written `-`, to the whole line. + to a position between items, and an error without a span, written `-`, to + the whole line. - **Version echo.** The output line echoes the three versions of the request. The job layer first checks them against the request: outside `cancel_requested`, a mismatch ends the job as `failed`, as @@ -303,8 +303,8 @@ lines. describes. - **Reading back.** The display text of every value of kalyx 0.1.0 is text that its grammar accepts and reads back as the same term, so a value can be - read back into a separate editing structure, which reuse inserts into the - buffer as a copy. That structure is checked against the editing structure's + read back into a separate editing structure, from which reuse inserts copies + into the buffer. That structure is checked against the editing structure's own limits, as [node identity](#node-identity) states. When the text is submitted again, kalyx reads it under the limits of that request like any other input, so the text of a term near those limits is read only under