@mark1russell7/coeval 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @mark1russell7/coeval
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The kernel of coeval: a base for declarative languages. A program is a JSON document in an envelope, `{ type, value }`. The kind of the document names its evaluator, and a ladder finds it. A language evaluates through this kernel and keeps only what is its own.
+
+```sh
+npm install @mark1russell7/coeval
+```
+
+## A formula language in a few lines
+
+```ts
+import { context, formulaMachine, prepare } from "@mark1russell7/coeval";
+
+const machine = formulaMachine({ ops: { add: (a: number, b: number) => a + b } });
+const doc = { type: ["ops", "add"], value: [{ type: "ref", value: ["names", "x"] }, 1] };
+
+const plan = prepare(machine, doc); // the ladder, the kinds and the parts, one time
+plan.evaluate(context({ names: { x: 2 } })); // { ok: true, value: 3 }
+```
+
+A plan evaluates many times without a trace. `evaluate(machine, doc)` gives the same result with a full trace, for a debugger or an explanation.
+
+## What the kernel holds
+
+| Part | Exports | What it does |
+| --- | --- | --- |
+| Documents | `isEnvelope`, `stored`, `typePath`, `docEquals` | The envelope, the keys of a store beside it, and the equality of documents |
+| World | `lookupKind`, `Kind`, `Namespace`, `PartShape`, `ScopeRule` | The kinds, with their contracts: the shape of the parts, the names that a kind binds, and its effects. A namespace can have a fallback kind |
+| Ladder | `ask` | The evaluator of a verb: the own entry, then the kind, then the default |
+| References | `resolve`, `HostThing`, `Navigator` | A path from a root of the context: `self`, `names`, `world`, `event` or `caps` |
+| Plans | `prepare`, `planner`, `evaluate`, `run` | A document compiles one time into code. An evaluator is a function or a compiler |
+| The run side | `run`, `Runner`, `permits`, `narrow` | Effects in order, parts at the same time, capabilities that only narrow, and an abort |
+| Errors | `Result`, `EvalError`, `Failure`, `failures` | An error value has a code, a reason, a place and a cause. An evaluation does not throw |
+| The static kit | `walk`, `refsOf`, `mapRefs`, `check` | The documents of a document, its free references, and its problems before a run |
+| The formula kit | `formulaMachine`, `FormulaProfile` | The shared constructs `lit`, `ref`, `record`, `list`, `let`, `fn`, `call`, `if`, `and`, `or`, and the namespaces `ops` and `ext` |
+
+Each rule has an ID in [`docs/SPEC.md`](https://github.com/mark1russell7/coeval/blob/main/docs/SPEC.md), and each ID has a test. [The site](https://mark1russell7.github.io/coeval/) explains each idea with a live diagram.
+
+## License
+
+MIT