@lapxo/bound 0.2.0 → 0.2.1

package/README.md

@@ -1,156 +1,75 @@
 # @lapxo/bound
 
-## Use Bound in a project
+Bound turns signed statements, observations and requirements into a place you can inspect. It keeps who said what, preserves incompatible declarations, and projects the views selected by that place. Missing evidence stays missing; a rendered page is not proof that every requirement has been met.
 
-From a project with an admitted lock and selected views, inspect its standing, ask for its evidence, then verify the committed outputs:
+The same pure engine is available to applications and to the CLI. Topos supplies the wire and interpretation contracts; Obligations supplies the constraint algebra. Bound adds admission, authenticated reading, retained receipts and declared host operations around that core.
 
-```sh
-npx @lapxo/bound@0.2.0 fold --as lines
-npx @lapxo/bound@0.2.0 fold --as receipts@1
-npx @lapxo/bound@0.2.0 fold --check
-```
-
-Use this flow to review a project change or check a dependency's declared contract. `--check` verifies existing evidence; it does not execute a missing reading. A file fold names readings and explicitly says that it computed no encounters.
-
-Independent observations are judged through the declared typed cells view. The selected topos supplies the form, origin evidence and bounds. Bound keeps attribution and exact-ID withdrawals through the fold.
-
-A selected form can instead describe a set of artifacts, a delivery interval or another domain's values. The project declares the form, origin evidence and views; Bound does not infer them from filenames or units.
-
-
-Declare what must hold. Read what does. Keep the evidence.
-
-Bound reads a project's admitted statements, checks observations against its requirements, and produces the views its selected topos declares. It keeps conflicting evidence and its origins instead of choosing a convenient answer.
-
-`fold` reads. `sign` signs a proposed lot. `land` admits that lot under the place's authority. These acts work across domains: a selected topos supplies forms, units, readers and views.
-
-## Start in an admitted project
-
-```sh
-npx @lapxo/bound@0.2.0 fold --as help
-npx @lapxo/bound@0.2.0 fold
-```
-
-The help view prints:
-
-```text
-verbs fold land sign
-flags --as --check --key --key-file --signer --place
-```
-
-The default fold runs the project's declared views. Its authority and selected topos determine what can be admitted, read and shown.
-
-Start with the team's accepted TARGET, admitted authority and selected readers. [Full usage guide](https://github.com/Lapxo/bound/blob/2053bb6d6188f04538114eae6a0add5166944ed3/docs/usage.md).
-
-## A meeting everyone can understand
-
-Ana is available from 10 to 14, Luis from 12 to 16, and the room from 10 to 13. Their common availability is 12 to 13. A boss available from 18 to 20 makes the encounter incompatible. Withdrawing that exact reading restores the overlap; Ana, Luis and the room remain.
-
-With an interval form, those are object operations: observe independent claims, meet them, withdraw by id, and read the state. A narrower compatible meet is not a fork. Folding a file of declarations alone does not calculate meeting availability.
+## A place, its readings and its receipts
 
-The same pattern applies to a delivery window, a sensor's allowed range, or an agreed performance budget. The chosen topos determines the units and how evidence is obtained. Bound does not supply a meeting-specific rule.
+A place declares its rules and selected worlds in `TARGET.bound`. Worlds supply readers and renderers for their own domains. A fold reads the declared inputs, applies the admitted constraints, and renders the selected views. `receipts.bound` carries the public evidence needed to check the resulting files; private admission history stays in the local `.bound/` store.
 
-## See how information holds together
+Unchanged regions can retain valid receipts. A changed input reopens the regions it affects, while incompatible admitted statements remain visible. A digest identifies content; it grants neither authority nor permission to reuse an old answer as current. A receipt records a reading under its declared context, rather than establishing the truth or independence of its sources.
 
-![Cells, travelling bounds and a local join](https://raw.githubusercontent.com/Lapxo/bound/2053bb6d6188f04538114eae6a0add5166944ed3/docs/readme-assets/atlas.svg)
-
-A travelling ceiling on B reaches C and G through their declared rest. A local join widens B alone. D is independent. The figure shows those relations; point size and camera distance do not measure information.
-
-| State | Meaning |
-| --- | --- |
-| REQUIRED | Compatible bounds, fewer than two independent origins. |
-| FREE | Independent origins meet and their encounter fits the bounds. |
-| CONFLICT | Bounds conflict, or eligible claims have no common encounter. |
-| FORBIDDEN | An inhabited encounter does not fit the bounds. |
-
-Bounds are checked before origins and claims. A receipt is evidence of a reading, not another origin. Duplicating one does not add freedom.
-
-## Change a project without erasing evidence
-
-Work in the project's directory. Use an existing admitted key identifier and its matching private key stored outside every repository. The admitted key also names its signer with `keys/<who> measure=signer value=file`; `signer/timeout` and `signer/response-bytes` declare its limits. Your public key and coverage belong to the authority contract; possession of a private key alone does not authorize a scope.
+## Install and use
 
 ```sh
-export BOUND_KEY_ID='your-admitted-key-id'
-export BOUND_KEY_FILE="$HOME/Private/keys/your-device.pem"
-lot_dir="$(mktemp -d)"
+npm install @lapxo/bound@0.2.1
 ```
 
-Have the selected view produce a proposal at `$lot_dir/proposal.bound`, or prepare the project's permitted lines there for review. Unsigned proposals use `by=target`, without a preassigned epoch or `sig`. Lots stay outside the repository; the committed bound files are only `TARGET.bound` and `receipts.bound`.
+In a place with admitted declarations and closed public receipts, check the existing evidence without running its readers again:
 
 ```sh
-npx @lapxo/bound@0.2.0 sign "$lot_dir/proposal.bound" \
-  --key "$BOUND_KEY_ID" --key-file "$BOUND_KEY_FILE" \
-  > "$lot_dir/signed.bound" &&
-npx @lapxo/bound@0.2.0 land "$lot_dir/signed.bound" &&
-npx @lapxo/bound@0.2.0 fold
+npx @lapxo/bound@0.2.1 fold --check
 ```
 
-`sign` assigns the admitted epoch and writes the signed lot to stdout. `land` validates the whole lot before admission. A refusal is evidence to inspect; it is not success. Do not proceed after a failed signature or admission. The key file is a PKCS8 private key matching the admitted public key; do not put it in the lot, source tree, package or CI artifacts.
+For a change, prepare a proposal, sign with a key already covered by the place, admit the signed lot, then fold and inspect the result. Signing and admission do not by themselves pay a requirement. The [usage guide](docs/usage.md) covers keys, coverage, proposals, withdrawals and release policy.
 
-For typed object withdrawals, `takes` names the exact claim or mark id. Removing a local join leaves the travelling sign live. For untyped configuration, use the wire's exact withdrawal selectors; do not combine withdrawal and replacement with identical selectors in one lot. Wire alphabet updates supersede by epoch.
+## Embed the engine
 
-[Authority, withdrawals, receipts and PR review](docs/usage.md).
+`objectFold` projects already admitted records in effective order. It does not acquire content, verify signatures, choose authority, commit an act or write storage. Those preparation steps belong to the host.
 
-## Read a declared view and reuse its evidence
+For an authenticated reference, your host supplies the independently accepted trust context: signer grants and epoch, selected form, policy, byte and record bounds, content and cryptographic ports. The carrier cannot choose those inputs. This example verifies the carrier through `/reference`, then uses the same `/engine` projection as the CLI:
 
-When the project has admitted a cells view:
+```js
+import { objectFold } from '@lapxo/bound/engine';
+import { inspectAuthenticatedReference } from '@lapxo/bound/reference';
 
-```sh
-npx @lapxo/bound@0.2.0 fold --as cells
+export async function openAndProject(reference, trust) {
+  const opened = await inspectAuthenticatedReference(reference, trust);
+  return objectFold(opened.records, trust.objects);
+}
 ```
 
-The installed interval scene printed this on an unchanged second reading:
+Captured on a clean installed consumer, with two independently admitted fixture places and an altered carrier in each:
 
 ```text
-RECEIPTS 4 read · 0 opened · idle · provider 0
-```
-
-Native receipts identify the live semantic inputs, declared rest, selected topos, codecs and selected rendering implementation. They exclude delivery count, display paths and Bound's error wrapper. A local join changes its own cell's receipt. A travelling sign changes dependent cells. Missing or corrupt carried bytes cannot prove reuse.
-
-For judgement:
-
-```sh
-npx @lapxo/bound@0.2.0 fold --check
+README sensor · REQUIRED · altered carrier refused
+README editorial · REQUIRED · altered carrier refused
 ```
 
-Keep stdout, stderr and the exit status. `--check` is not an install-and-build replacement. A source test passing does not pay an unread ceiling, prove a cold clone, or accept a release.
-
-## Select a topos by what it declares
-
-`sources/<name>` says where a world can be obtained. An admitted `uses/<name>` names the digest of that topos's folded standing: canonical live claims in wire byte order, excluding signature envelopes and host shape. Re-signing the same standing preserves the pin. A changed live form, class, view or offer changes it.
+Opening and projecting a reference never commit an act. The authenticated context binds the standing contract and refusal catalog by digest, so consumers can identify the contracts used to interpret the result.
 
-`restsOn` closes artifact bytes separately. A capsule is one offer. Forms, classes and views need no capsule merely to be selected. Runtime and packing do not define standing identity. npm dependency ranges remain package metadata; they are not standing pins.
+## Public boundaries
 
-| Responsibility | Owner |
+| Entry | Responsibility |
 | --- | --- |
-| Meet, state, live acts and rest | Obligations |
-| Wire, forms, classes, views and offer contracts | Topos |
-| Admission, folding and evidence | Bound |
-| Domain measurement and representation | Selected topos |
-| Storage, transport and execution | Host |
-
-Cell `restsOn` is the object's relation. Directory prefixes and file summaries are host coordinates, not object rest. Wire tokens are protocol constants, not organization, host, path or key literals.
-
-## Repository rules
-
-Commit `TARGET.bound`, `receipts.bound` and the outputs the forge reads. Ignore `.bound/` from the first line of `.gitignore`. Keep proposals, signed lots, keys, ledgers, caches and dependency blobs outside the published tree. CI logs and test results are workflow artifacts; do not commit or package them. Cross-machine portability proof (L6) remains pending for 0.1.10.
-
-The lock is the project's own contract and pins. Read a dependency's declarations from its selected standing; do not copy its lines into your lock. README, package metadata and workflows must be renders of admitted declarations. A scan is an observation, not permission to lower a ceiling.
-
-A PR proposes lines and the leaf changes they render. The judge uses the team's accepted contract independently of the proposed revision. Preserve refusals, conflicting origins and unpaid demands. [Repository and contribution rules](https://github.com/Lapxo/bound/blob/2053bb6d6188f04538114eae6a0add5166944ed3/docs/usage.md#repository-and-pr-review).
-
-## An atlas you can question
-
-Information can share a history without sharing a single presentation. The same admitted cells can support a compact status view, a spatial view of their relations, or a focused reading of one disagreement. Each view asks for a region and resolution; its selected topos determines the representation.
-
-This makes changes inspectable. A local act can remain local, travelling bounds can reach dependent cells, and a receipt can name the inputs of the reading you saw. You can ask what changed and what depends on it without turning a drawing into the algebra.
+| `/engine` | Pure projection of admitted object records; optional, explicitly injected host ports. |
+| `/reference` | Inspect a carrier against the host's accepted context and verify its content and authority. |
+| `/reference/native` | Export a signed carrier from a real admitted place and open it with an explicitly selected backend. |
+| `/wasm` | Load the optional WASM adapter for the published object projection. |
+| `/refusals` and `/standing-contract` | Read the machine-readable contracts bound into authenticated exports. |
 
-A pin names standing, not a download URL or runtime entry. Its declared artifact dependencies close the bytes needed for an offered operation. The boundary lets a form or view remain meaningful even when it has no executable capsule.
+Native opening selects **ESM or WASM explicitly**; an unsupported selection refuses rather than falling back. The WASM adapter covers the published object projection. Admission, effects and the whole CLI do not run inside WASM. Cross-machine evidence (L6) remains pending.
 
-Use Bound where independently attributed observations must be judged against an accepted contract: compatibility between components, operational limits, or a team's project requirements. The selected topos must supply the actual measurements; a digest identifies the evidence without declaring it true.
+The host supplies bounded [signer, content and persistence ports](docs/contracts/host-ports.md). Their identities and limits are explicit. Retaining bytes is an explicit operation: it grants no admission or permission to reuse a response. The existing authority path verifies signatures before returning an authenticated carrier.
 
-[Contribute a counterexample or a proposed lot](CONTRIBUTING.md).
+[Complete standing](docs/contracts/standing.md) covers declared key classes and committed local acts, preserving attribution, exact withdrawals and conflicts. [Refusals](docs/contracts/refusals.md) have machine-readable codes, meanings and suggested next steps; human diagnostics are not parsed as authority.
 
+## Contracts and foundations
 
-## Foundations and related libraries
+- [Native authenticated export](docs/contracts/reference-export.md) and [reference backends](docs/contracts/reference-backend.md).
+- [Pure engine](docs/contracts/engine.md), [host ports](docs/contracts/host-ports.md) and [CLI usage](docs/usage.md).
+- [Topos](https://github.com/Lapxo/topos): wire, interpretation and identity contracts.
+- [Obligations](https://github.com/Lapxo/obligations): the unchanged constraint algebra.
 
-The two-sided constraint object is described in Nahum Ochoa's [Two-Sided Constraints on a Valued Lattice](https://doi.org/10.5281/zenodo.21858428), DOI `10.5281/zenodo.21858428`. Bound uses the object through [Obligations](https://github.com/Lapxo/obligations); [Topos](https://github.com/Lapxo/topos) supplies the wire and contracts for forms, views and selected worlds. Bound admits, folds and retains evidence across those declared boundaries. A digest identifies bytes; it does not certify that an observation is true.
+The underlying object is described in [Two-Sided Constraints on a Valued Lattice](https://doi.org/10.5281/zenodo.21858428), DOI `10.5281/zenodo.21858428`.