@orkestrel/reason 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+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

@@ -0,0 +1,74 @@
+# @orkestrel/reason
+
+A zero-dependency, synchronous, deterministic **reasoning engine**: declarative,
+JSON-serializable **definitions** are evaluated against **subjects** (plain
+data records) to produce traceable **results**. Four strategies behind one
+dispatch surface — `quantitative` (factor-based numeric scoring), `logical`
+(rule-based boolean deduction with forward / backward chaining), `symbolic`
+(algebraic equation solving by variable isolation), `inferential` (fact
+derivation with unification variables and proof trees) — each a
+`ReasonerInterface` registered on the thin `Reason` orchestrator, with three
+injectable operators (`Evaluator` / `Transformer` / `Aggregator`) doing the
+shared arithmetic. Every result is a fresh object carrying `success`, a
+human-readable `trace`, and accumulated `errors`; nothing mutates its inputs.
+Environment-agnostic — no I/O, no browser or server assumptions. Part of the
+`@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/reason
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM-only (no CommonJS build)
+
+## Usage
+
+```ts
+import {
+	createQuantitativeReasoner,
+	createReason,
+	factorGroup,
+	fieldFactor,
+	quantitativeDefinition,
+	staticFactor,
+} from '@orkestrel/reason'
+
+const reason = createReason({ reasoners: [createQuantitativeReasoner()] })
+
+const definition = quantitativeDefinition('risk', 'Risk score', [
+	factorGroup('drivers', 'sum', [
+		fieldFactor('age', 'age'), // reads subject.age, parseNumber-coerced
+		staticFactor('floor', 10), // a fixed contribution
+	]),
+])
+
+const result = reason.reason({ age: 25 }, definition) // one subject → one result
+if (result.reasoning === 'quantitative') result.value // 35 — narrow by the discriminant
+result.trace // the step-by-step account of how the value came to be
+```
+
+`reason` dispatches by `definition.reasoning` — pass an ARRAY of subjects and
+the batch overload maps them in order to an equal-length result array.
+Results are a discriminated union (`reasoning` names the axis): narrow with
+the discriminant and read the strategy-specific payload (`value` /
+`conclusion` / `solutions` / `derived`).
+
+## Guide
+
+For the full surface — the orchestrator, the four reasoners, the three
+operators, the definitions & subjects capability layer, the two workspace
+builders (`DefinitionBuilder` / `SubjectBuilder`), validators, errors, and the
+observation surface — see [`guides/src/reason.md`](guides/src/reason.md).
+
+## Package
+
+Published as a single typed entry point per the `exports` field in
+`package.json`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).