selaws 0.0.0-stage → 0.1.0

package/docs/laws/match.md

@@ -0,0 +1,163 @@
+# Match law
+
+Match is Selaws' shared elimination law for sum-like semantic owners.
+
+It applies to:
+
+```text
+Option      Some / None
+Result      Ok / Err
+Validation  Valid / Invalid
+Variant     one declared family case
+```
+
+Match is not an eighth semantic owner. The owning carrier still defines which
+branches exist, what each branch means, and which payload belongs to each
+branch.
+
+There is no root `Match` value, `Match` type, or `selaws/match` entry point.
+The public realizations stay on their owners:
+
+```text
+Option.match
+Result.match
+Validation.match
+VariantFamily.match
+```
+
+## 1. Owner-defined branch universe
+
+For one owner with finite branch universe `B` and branch payload assignment
+`P`, Match eliminates one value from:
+
+```text
+sum over b in B of P(b)
+```
+
+through one handler per branch.
+
+The owner supplies `B` and `P`.
+
+Match does not reinterpret Option as Result, Result as Validation, or one
+Variant family as another. Runtime structural similarity does not identify the
+semantic owner.
+
+## 2. Typed totality
+
+A typed Match call provides a handler for every branch in the owning semantic
+universe.
+
+This requirement is determined by the owner, not by the current narrowing of
+the input value.
+
+Examples:
+
+```text
+Option      requires Some and None
+Result      requires Ok and Err
+Validation  requires Valid and Invalid
+Variant     requires every case in the declared family
+```
+
+A narrowed Some, Ok, Valid, or Variant case does not reduce the family-level
+handler obligation.
+
+## 3. Unique selection
+
+The owning carrier determines exactly one selected branch.
+
+Match resolves only that branch's handler according to the owner's handler
+boundary. Unselected handler properties are not read or invoked by Selaws
+Match execution.
+
+When selected-handler resolution completes with a callable handler, that
+handler is invoked exactly once. Any abrupt completion while resolving the
+selected handler remains ordinary JavaScript abrupt completion.
+
+## 4. Payload correlation and arity
+
+The selected handler receives exactly the payload owned by the selected branch.
+
+Nullary branches receive zero arguments.
+
+Examples:
+
+```text
+Option Some       -> present value
+Option None       -> zero arguments
+
+Result Ok         -> success value
+Result Err        -> error value
+
+Validation Valid  -> valid value
+Validation Invalid-> complete non-empty issue collection
+
+Variant unit case -> zero arguments
+Variant payload   -> stored case payload
+```
+
+Match does not flatten, convert, accumulate, or otherwise reinterpret a branch
+payload.
+
+## 5. Receiver neutrality
+
+Selaws does not supply the handler object as a callback receiver.
+
+The selected handler is invoked as an ordinary callback without a
+library-defined `this` value. A function that carries its own explicit JavaScript
+binding, such as a bound function, retains that ordinary language behavior.
+
+Receiver semantics are therefore not a hidden communication channel between a
+semantic owner and its Match handler. This rule governs callback invocation;
+it does not rewrite ordinary JavaScript property-access semantics used by an
+owner to resolve the selected handler.
+
+## 6. Completion transparency
+
+After selected-handler resolution, the selected handler's completion is the
+Match completion.
+
+```text
+ordinary return -> ordinary Match return
+throw           -> throw remains abrupt
+Promise return  -> native Promise value remains native
+```
+
+Match does not capture exceptions, await Promises, introduce asynchronous
+carriers, or normalize handler return values.
+
+The static Match result is a conservative union of the return types exposed by
+the participating handlers. Finite overloaded handlers therefore preserve
+their exposed return alternatives rather than collapsing to one overload.
+
+TypeScript can reflect some generic callable signatures as the same instantiated
+signature repeatedly. When that reflection would cycle, Selaws widens the
+affected callback result to `unknown` instead of imposing an arbitrary overload
+count or exhausting compiler instantiation depth.
+
+## 7. Runtime boundary ownership
+
+The shared Match law does not require one universal runtime validator.
+
+Fixed structural owners rely on their ordinary typed carrier boundary and
+ordinary JavaScript property lookup for the selected handler.
+
+Variant additionally owns runtime family checks because its family declaration
+exists at runtime. Variant Match therefore validates its own tagged
+representation, declared case membership, payload representation, and selected
+own handler availability.
+
+Those Variant checks are owner-specific enforcement of Variant meaning, not
+additional shared Match meaning.
+
+## 8. Implementation independence
+
+A shared law does not require one shared production helper.
+
+Each owner may keep a local implementation when that preserves clearer
+ownership, inference, and runtime boundaries. Shared conformance tests establish
+the cross-owner law.
+
+A future Match-capable owner must define its branch universe and payload
+correlation, conform to this shared law, and keep any additional runtime
+validation with the owner that can establish it.

package/docs/laws/option.md

@@ -0,0 +1,100 @@
+# Option law
+
+Option represents explicit presence or reasonless absence.
+
+Use Option when callers only need to distinguish “a value exists” from “no
+value exists”.
+
+```ts
+type Some<T> = Readonly<{
+  some: true;
+  value: T;
+}>;
+
+type None = Readonly<{
+  some: false;
+}>;
+
+type Option<T> = Some<T> | None;
+```
+
+If the absent branch needs a diagnostic reason, use Result or a domain-specific
+Variant instead of placing hidden meaning behind None.
+
+## Presence
+
+`Some(value)` means a value is present, including `undefined` or `null`
+when explicitly wrapped. `None` carries no diagnostic reason.
+
+Constructors preserve this distinction:
+
+```text
+some(undefined)           => Some(undefined)
+fromUndefined(undefined)  => None
+fromUndefined(null)       => Some(null)
+fromNullable(undefined)   => None
+fromNullable(null)        => None
+```
+
+Falsy values such as `0`, `false`, and `""` remain present.
+
+```ts
+const maybeName =
+  Option.fromUndefined(row.name);
+
+const label = Option.match(maybeName, {
+  some: (name) => name,
+  none: () => "Anonymous",
+});
+```
+
+## Match elimination
+
+Option's Match branch universe is exactly Some and None.
+
+`Option.match` conforms to the shared [Match law](./match.md). Typed
+elimination requires both branches even when the current input is narrowed.
+Some passes its present value to the selected handler. None is nullary and
+passes zero arguments.
+
+Option owns the presence/absence meaning. Match owns the shared elimination
+behavior: exactly one selected receiver-neutral callback runs, unselected
+handlers are untouched, and the selected callback's ordinary JavaScript
+completion is preserved.
+
+## Composition
+
+`map` transforms Some.
+
+`andThen` sequences presence-dependent work.
+
+`orElse` evaluates fallback only for None.
+
+`flatten` removes one explicit nested Option layer.
+
+`filter` keeps a present value only when its predicate accepts it.
+
+`all` combines already-materialized Options. It preserves tuple position when
+every input is Some; any None produces None. Typed input arrays must be readonly so array covariance cannot change element
+meaning behind the static type before the call. Inline array literals infer
+readonly tuples; broad `readonly Option<T>[]` inputs remain valid.
+
+```ts
+const pair = Option.all([
+  maybeFirst,
+  maybeLast,
+] as const);
+```
+
+## Observation and projection
+
+`inspect` synchronously observes Some and returns the original Option.
+Promise-like observer completion is outside that synchronous contract.
+
+`unwrapOr` and `unwrapOrElse` leave Option by choosing a fallback value.
+
+`toUndefined` and `toNullable` leave Option by projecting None to a
+conventional JavaScript sentinel.
+
+These projections do not change the law of the Option value before the
+boundary.

package/docs/laws/protocol.md

@@ -0,0 +1,152 @@
+# Protocol laws
+
+Protocol owns one admissible labeled transition relation over
+application-owned scalar state and label identifiers.
+
+For a declaration `R`:
+
+```text
+R subset State x Label x State
+```
+
+`allows(from, label, to)` is true exactly when `(from, label, to)` is in that
+relation.
+
+Use Protocol when the application must state which labeled transitions are
+admissible without also introducing a state-machine runtime.
+
+```ts
+const transitions = [
+  ["pending", "pay", "paid"],
+  ["pending", "cancel", "cancelled"],
+  ["paid", "ship", "shipped"],
+] as const;
+
+const OrderProtocol =
+  Protocol.define(transitions);
+```
+
+## 1. Application-owned identifiers
+
+The application owns the meaning of state identifiers and transition labels.
+Protocol receives scalar identifiers and does not construct domain states,
+commands, events, or operations.
+
+A Protocol declaration therefore does not define a complete state universe.
+`States<Transitions>` contains states that occur in declared source or target
+positions. A state with no declared edge is outside that projection unless the
+application represents it elsewhere.
+
+## 2. Label preservation
+
+Labels are part of relation identity. Two declared transitions with the same
+source and target but different labels remain distinct transitions.
+
+```ts
+Protocol.define([
+  ["ready", "retry", "ready"],
+  ["ready", "refresh", "ready"],
+] as const);
+```
+
+`retry` and `refresh` remain separate even though their source and target are
+the same.
+
+## 3. Single relation
+
+The same readonly transition declaration determines both the TypeScript
+`Next<Transitions, From, Label>` projection and runtime
+`allows(from, label, to)` membership. The typed declaration requires a readonly outer relation and readonly
+transition triples, rejecting mutation through the declaration type itself.
+A readonly view over separately mutable backing data remains subject to the
+TypeScript trust model in [SEMANTICS.md](../SEMANTICS.md).
+
+```ts
+type AfterPay =
+  Next<
+    typeof transitions,
+    "pending",
+    "pay"
+  >;
+// "paid"
+
+OrderProtocol.allows(
+  "pending",
+  "pay",
+  "paid",
+);
+// true
+```
+
+`Next` is the static target projection.
+
+`allows` returns the runtime membership boolean. It does not assert a
+target-narrowing type predicate because broad or union source and label values
+do not preserve the correlation required for that narrowing.
+
+## 4. Snapshot stability
+
+`Protocol.define` snapshots declaration values. Typed declarations use readonly
+arrays and readonly triples. Runtime JavaScript callers may still pass ordinary
+arrays; later mutation of those caller-owned arrays does not change the already
+defined runtime relation.
+
+## 5. Set semantics
+
+Duplicate triples do not change admissibility. Declaration order is not
+semantic.
+
+## 6. Equality
+
+Runtime state and label identity follows JavaScript SameValueZero, matching
+`Map` and `Set` key semantics.
+
+## 7. Relational semantics
+
+Protocol does not require determinism. The same `(from, label)` pair may admit
+multiple target states.
+
+```ts
+const Routing = Protocol.define([
+  ["open", "advance", "left"],
+  ["open", "advance", "right"],
+] as const);
+```
+
+Both targets are admissible. Protocol does not choose one.
+
+Protocol also does not require totality. A source/label pair may have no
+declared target.
+
+## 8. Execution independence
+
+Protocol describes admissibility. It does not choose a target, store current
+state, dispatch events, execute effects, schedule timers, persist state, retry,
+or orchestrate a workflow.
+
+Variant may independently own an event vocabulary whose `tag` is used as a
+Protocol label. The Variant payload and the Protocol relation remain separate
+meanings.
+
+## 9. Freshness independence
+
+An admissible triple does not prove that a persisted or concurrently observed
+source state is still current.
+
+```ts
+if (
+  OrderProtocol.allows(
+    observedState,
+    "pay",
+    "paid",
+  )
+) {
+  // A storage owner must still establish
+  // that observedState is current when writing.
+}
+```
+
+Atomic mutation and concurrency checks remain application-owned.
+
+A labeled trace is protocol-valid exactly when every
+`(state[i], label[i], state[i + 1])` triple is admissible.

package/docs/laws/result.md

@@ -0,0 +1,124 @@
+# Result law
+
+Result represents recoverable success or error with fail-fast composition.
+
+Use Result when later work depends on earlier success or when one recoverable
+error value should stop the current dependent path.
+
+```ts
+type Result<T, E> =
+  | Readonly<{ ok: true; value: T }>
+  | Readonly<{ ok: false; error: E }>;
+```
+
+Constructors preserve the impossible generic axis as `never`.
+
+## Data algebra
+
+`map` transforms Ok.
+
+`mapError` transforms Err.
+
+`andThen` sequences a dependent Result-producing step.
+
+`orElse` recovers from Err.
+
+`flatten` removes one explicit nested Result layer.
+
+```ts
+const user = await loadUser(userId);
+
+if (!user.ok) {
+  return user;
+}
+
+return loadAccount(
+  user.value.accountId,
+);
+```
+
+Ordinary JavaScript branching is a first-class way to compose Result values.
+
+`Result.all` inspects already-materialized inputs in order and returns the
+first Err object itself. Complete success preserves tuple positions. Typed
+input arrays must be readonly so array covariance cannot replace a Result with
+one carrying a different success or error type before the call.
+
+## Match elimination
+
+Result's Match branch universe is exactly Ok and Err.
+
+`Result.match` conforms to the shared [Match law](./match.md). Typed
+elimination requires both branches even when the input is narrowed. Ok passes
+the success value; Err passes the recoverable error value.
+
+Result owns recoverable success/failure meaning. Match owns the shared
+elimination behavior and does not capture a handler throw, await a handler
+Promise, or provide the handler object as `this`.
+
+## Target-owned conversions
+
+`Result.fromOption(option, onNone)` evaluates `onNone` only for None.
+
+`Result.fromValidation(validation)` carries Invalid's complete non-empty issue
+collection as one Result error value and preserves that collection object.
+
+A Result error may itself be a domain-specific Variant. Result owns
+success/error; Variant owns the closed error vocabulary.
+
+## Abrupt capture
+
+`attempt` and `wrap` capture one synchronous invocation boundary.
+
+```ts
+const parsed = attempt(
+  () => JSON.parse(text) as unknown,
+  (cause) => ({
+    kind: "invalid-json" as const,
+    cause,
+  }),
+);
+```
+
+The caller supplies an `unknown -> E` mapper. A returned Result or other
+ordinary value is success data; capture does not flatten it.
+
+A returned Promise-like value, meaning a non-null object or function with a
+callable `then`, violates the synchronous boundary and raises `TypeError`.
+That contract error is outside the user's thrown-value mapper.
+
+`wrap` preserves the wrapped function's arguments and `this`.
+
+`attemptAsync` and `wrapAsync` own invocation throws plus rejection from the
+returned Promise-like value. Their successful payload follows native
+`Awaited` semantics.
+
+Mapper throws and ordinary Result callback throws remain abrupt.
+
+## Composition boundary
+
+Dependent Result composition uses ordinary JavaScript control flow or the
+data-level `andThen` combinator.
+
+Result does not define a generator protocol, asynchronous control runtime,
+implicit early-return syntax, scheduler, retry policy, or cancellation model.
+
+For asynchronous work, Promise remains the scheduling and awaiting owner:
+
+```ts
+const user = await loadUser(userId);
+
+if (!user.ok) {
+  return user;
+}
+
+return loadAccount(user.value.accountId);
+```
+
+## Recoverable-to-abrupt boundary
+
+`orThrow(result, mapErrorToThrowable)` returns Ok and explicitly maps Err to a
+thrown JavaScript value.
+
+This boundary is intentional and visible; an Err does not throw merely because
+it exists.

package/docs/laws/validation.md

@@ -0,0 +1,111 @@
+# Validation law
+
+Validation represents valid data or a non-empty ordered issue collection.
+
+Use Validation when multiple checks can be evaluated independently from values
+that are already available and callers should receive every issue found in that
+pass.
+
+```ts
+type ValidationIssues<E> =
+  readonly [E, ...E[]];
+
+type Validation<T, E> =
+  | Readonly<{ valid: true; value: T }>
+  | Readonly<{
+      valid: false;
+      errors: ValidationIssues<E>;
+    }>;
+```
+
+## Non-empty invalidity
+
+Every Invalid contains at least one issue. The constructor therefore requires
+one first issue.
+
+```ts
+Validation.invalid(
+  "name-required",
+  "email-invalid",
+);
+```
+
+There is no empty Invalid state.
+
+## Independent accumulation
+
+Validation accumulates issues only across inputs that are already independently
+available.
+
+```ts
+const form = Validation.struct([
+  ["name", validateName(raw.name)],
+  ["email", validateEmail(raw.email)],
+]);
+```
+
+`Validation.all` traverses tuple positions in order. Complete success
+preserves the tuple shape. Failure concatenates every issue collection in input
+order while retaining each collection's internal order and duplicates. Typed
+input arrays must be readonly so array covariance cannot replace a Validation
+with one carrying a different value or issue type before the call.
+
+`Validation.struct` performs the analogous product for one finite readonly tuple
+of readonly `[key, Validation]` entries. Keys are concrete string or symbol
+identities. Complete success produces one ordinary data property per declared
+key. Failure concatenates every issue collection in entry order while retaining
+internal order and duplicates.
+
+The typed grammar rejects directly mutable outer or inner tuples, duplicate
+keys, broad string/symbol key spaces, and broad-length or union declarations
+because those do not identify one exact stable keyed product. A readonly view
+over separately mutable backing data remains subject to the TypeScript trust
+model in [SEMANTICS.md](../SEMANTICS.md). Runtime JavaScript callers must supply one array of exact
+pairs, unique string/symbol keys, and structural Validation values with own
+branch fields. Large issue collections are accumulated iteratively.
+
+Validation does not schedule checks and does not run dependent work whose input
+does not yet exist.
+
+## Match elimination
+
+Validation's Match branch universe is exactly Valid and Invalid.
+
+`Validation.match` conforms to the shared [Match law](./match.md). Valid
+passes its value. Invalid passes the complete non-empty issue collection as one
+handler payload; Match does not flatten or iterate that collection.
+
+Typed elimination requires both branches even when the input is narrowed. The
+selected handler is invoked once without a library-defined receiver, and its
+ordinary return, throw, or Promise completion is preserved.
+
+## Mapping and observation
+
+`map` transforms Valid.
+
+`mapError` transforms each issue exactly once in order.
+
+`inspect` synchronously observes Valid and returns the original Validation.
+
+`inspectErrors` synchronously observes the complete non-empty issue collection
+as one value and returns the original Validation.
+
+`unwrapOr` and `unwrapOrElse` leave Validation through an explicit fallback.
+
+## Target-owned conversions
+
+`Validation.fromOption(option, onNone)` evaluates `onNone` only for None and
+creates one issue.
+
+`Validation.fromResult(result)` turns Err into exactly one issue. An array or
+other aggregate Err value remains one issue value rather than being spread.
+
+The reverse boundary is owned by Result:
+
+```ts
+const ready =
+  Result.fromValidation(form);
+```
+
+That conversion carries Invalid's complete non-empty issue collection as one
+Result error value.