selaws 0.0.0-stage → 0.1.0

package/docs/SEMANTICS.md

@@ -0,0 +1,319 @@
+# Selaws semantics
+
+Selaws is one distribution package containing independent semantic owners.
+Package co-location does not merge their laws.
+
+| Owner | Question |
+| --- | --- |
+| Identity | What scalar value is this? |
+| Evidence | What stable fact is established about this scalar? |
+| Protocol | Which labeled state transitions are admissible? |
+| Variant | Which closed labeled alternative is this, and what payload does it carry? |
+| Option | Is a value present? |
+| Validation | Which independently available checks have issues? |
+| Result | Did a recoverable computation succeed? |
+
+The detailed owner contracts are:
+
+- [Identity](./laws/identity.md)
+- [Evidence](./laws/evidence.md)
+- [Protocol](./laws/protocol.md)
+- [Variant](./laws/variant.md)
+- [Option](./laws/option.md)
+- [Validation](./laws/validation.md)
+- [Result](./laws/result.md)
+
+Cross-owner semantics can also be first-class shared laws without becoming new
+owners. The shared Match contract is [laws/match.md](./laws/match.md).
+
+The [Guide](./GUIDE.md) shows application patterns. This file defines the
+shared package laws those patterns must preserve.
+
+## 1. Semantic selection law
+
+Choose an owner by the meaning the application needs, not by implementation
+shape.
+
+A tagged union does not automatically imply Variant. Option, Validation, and
+Result are also sum-shaped, but their branches carry different laws:
+
+```text
+Variant    closed alternative identity + correlated payload
+Option     presence / reasonless absence
+Validation independent issue accumulation
+Result     recoverable success / fail-fast error
+```
+
+Likewise, a list of state-like strings does not automatically imply Protocol.
+Protocol begins only when the application needs an admissible labeled relation
+between scalar identifiers.
+
+Using one owner as a carrier for another owner's meaning does not transfer the
+second owner's laws automatically.
+
+## 2. Ownership law
+
+Each primitive owns one dominant meaning. Similar implementation shapes do not
+create a shared semantic owner.
+
+Cross-owner operations are named on the target owner because the conversion
+introduces the target meaning:
+
+```text
+Result.fromOption
+Result.fromValidation
+
+Validation.fromOption
+Validation.fromResult
+```
+
+The source information preserved by each boundary is part of the target
+owner's law.
+
+Protocol is independent of every other semantic owner. It consumes
+application-owned scalar identifiers without importing Identity, Evidence, or
+Variant meaning.
+
+Variant owns exact closed labeled alternatives and correlated payload
+formation. Option, Validation, and Result retain their presence, accumulation,
+and recoverable-failure meanings even when their carriers are also tagged
+unions.
+
+Identity and Evidence remain independent scalar meanings. Identity says which
+domain scalar this is. Evidence says which stable fact has been established
+about that same scalar.
+
+Application code composes owners through ordinary typed values.
+
+## 3. Composition law
+
+Owner independence does not prohibit useful composition. It determines which
+owner is responsible for each statement.
+
+Examples:
+
+```text
+Identity + Evidence
+  UserId carrying a separately established NonEmpty fact
+
+Variant inside Result
+  Result<User, LoadUserError>
+  where LoadUserError is a closed Variant family
+
+Validation -> Result
+  independent field issues accumulate first,
+  then the complete issue collection becomes one Result error
+
+Variant label + Protocol
+  Variant owns event payload/case identity;
+  Protocol can use the scalar event tag as a transition label
+
+Promise<Result<T,E>>
+  Promise owns scheduling/awaiting;
+  Result owns recoverable success/error data
+```
+
+Composition must preserve those boundaries. A convenience helper that makes one
+owner silently perform another owner's job changes the semantic surface and
+requires its own owner justification.
+
+## 4. Match law
+
+Match is the shared elimination law for Option, Result, Validation, and Variant.
+It is not another semantic owner and introduces no root value, type, dispatcher,
+or package subpath.
+
+The owning carrier determines the complete branch universe and the payload
+associated with each branch. Typed Match requires a handler for every branch in
+that universe even when the current value is already narrowed.
+
+For the selected branch, Match:
+
+```text
+invokes exactly one handler exactly once
+does not read or invoke unselected handler properties
+preserves the owner-defined branch payload and arity
+supplies no library-defined this receiver
+returns the selected handler completion unchanged
+```
+
+Therefore a returned Promise remains a native Promise and a thrown handler
+remains abrupt. Match does not capture, await, wrap, or normalize completion.
+
+Runtime validation beyond those shared elimination laws remains owner-specific.
+Variant can validate its runtime family representation because Variant owns a
+runtime case declaration. Fixed structural owners retain their own typed
+boundaries.
+
+The public grammar remains owner-scoped:
+
+```text
+Option.match
+Result.match
+Validation.match
+VariantFamily.match
+```
+
+A centralized `Match(value, handlers)` could not recover semantic ownership
+from transparent structural data, while `Match(owner, value, handlers)` would
+duplicate the owner and weaken TypeScript inference. Shared law therefore does
+not imply shared dispatch.
+
+## 5. Representation law
+
+Identity and Evidence enrich immutable JavaScript scalar values:
+
+```ts
+string | number | bigint | boolean | symbol
+```
+
+Successful formation returns that same primitive representation.
+
+Protocol uses those JavaScript scalar kinds as application-owned state and
+label identifiers. `Protocol.define` snapshots readonly
+`[from, label, to]` declarations into a private membership relation. The
+runtime relation is not application state.
+
+Variant snapshots a finite case declaration into immutable family constructors
+and elimination behavior. Its values remain transparent tagged JavaScript
+objects:
+
+```ts
+{ tag: caseName }
+{ tag: caseName, value: payload }
+```
+
+Variant phantom family identity adds no runtime brand.
+
+Option, Validation, and Result also use ordinary structural object and array
+data. Their TypeScript `Readonly` contracts describe typed use; runtime values
+remain transparent JavaScript data.
+
+Transparent representation is not permission to bypass each owner's formation
+and boundary laws in typed application code.
+
+## 6. Phantom identity law
+
+Named identity, evidence, and Variant families use Selaws-owned,
+package-copy-stable structural keys:
+
+```text
+~selaws.identity:<Name>
+~selaws.evidence:<Name>
+~selaws.variant:<Name>
+```
+
+A concrete string name therefore defines a shared structural identity contract.
+
+Declaration-owned identity, evidence, and Variant families use a caller-owned
+symbol as the phantom property key. The bound symbol determines declaration
+identity.
+
+The category payloads remain distinct. Reusing one symbol for independent
+owners does not make Identity imply Evidence or make either owner become
+Variant.
+
+Variant family markers additionally retain the closed case-name universe and
+case signatures needed for typed compatibility. Case-name universes are exact;
+payload positions retain ordinary TypeScript structural variance.
+
+These encodings are compatibility law: duplicate compatible Selaws
+installations can agree on the same declared named meaning without sharing a
+package-local unique-symbol brand.
+
+## 7. Completion law
+
+Ordinary transformation, recovery, fallback, observation, predicate,
+conversion, and Variant elimination callbacks follow JavaScript completion
+semantics. A thrown callback remains abrupt unless an explicit Result capture
+boundary owns the conversion.
+
+Synchronous observation helpers require synchronous completion. Promise-like
+completion is rejected rather than silently discarded. At runtime,
+Promise-like means a non-null object or function with a callable `then`.
+
+Result capture helpers are the explicit boundary that maps thrown or rejected
+JavaScript completion into recoverable Result error data.
+
+## 8. Async law
+
+Native Promise composition owns scheduling, awaiting, and rejection.
+
+```ts
+Promise<Result<T, E>>
+Promise<Option<T>>
+Promise<Validation<T, E>>
+```
+
+Selaws does not introduce an asynchronous carrier wrapper.
+
+Result does not introduce a generator or asynchronous control-flow runtime.
+Dependent async composition remains ordinary JavaScript control flow over
+`Promise<Result<T, E>>` values.
+
+Independent asynchronous work may be scheduled with Promise first and then
+combined by the relevant Selaws data owner.
+
+## 9. Information law
+
+Owner boundaries preserve information according to the target contract.
+
+- Option None gains an error only when converted to Result.
+- Option None gains an issue only when converted to Validation.
+- Invalid's complete non-empty issue collection becomes one Result error value.
+- One Result Err value becomes one Validation issue, even when that value is
+  itself an array.
+- Variant payloads remain attached to their declared case; conversion through
+  another owner must not erase that correlation unless that boundary explicitly
+  defines such a projection.
+- Protocol labels remain part of relation identity even when source and target
+  states are otherwise equal.
+
+Applications can state a different projection explicitly before or after an
+owner boundary.
+
+## 10. Snapshot law
+
+Protocol and Variant both define immutable runtime declarations from
+caller-provided declaration data.
+
+`Protocol.define` snapshots transition triples.
+
+`Variant.define` snapshots case names and case kinds.
+
+Protocol and Variant typed declarations require readonly finite tuples and
+reject directly mutable declaration arrays. This prevents mutation through the
+declaration type itself. TypeScript can still create a readonly view over a
+separately mutable alias and mutate the same backing array before definition;
+that language-level unsound aliasing is governed by the trust model below.
+
+At runtime, both owners snapshot caller-provided declaration data. Later
+mutation of caller-owned JavaScript arrays does not change the already-defined
+Protocol or Variant family.
+
+Snapshotting the declaration does not freeze application payloads, application
+state, or external storage.
+
+## 11. TypeScript trust model
+
+Selaws expresses semantic guarantees for values whose runtime state is still
+described by their ordinary TypeScript type. Formation APIs centralize honest
+introduction of phantom meaning. Assertions, `any`, and TypeScript's unsound mutable aliasing can break that
+relationship; Selaws does not reify erased static types at runtime. A readonly
+view is therefore trusted to describe the current backing value when it crosses
+a Selaws typed boundary.
+
+Protocol runtime membership establishes only whether one concrete triple was
+declared. It does not establish authorization, current-state freshness, or an
+atomic state mutation.
+
+Variant runtime formation establishes the selected declared case and preserves
+the supplied payload. Runtime payload schema validity still belongs to the
+application boundary that decoded or produced that value.
+
+Identity and Evidence predicates can validate their own scalar formation or
+fact condition. They are not general object-schema decoders.
+
+Runtime authorization, mutable freshness, revocation, schema decoding,
+normalization, persistence, version negotiation, and resource enforcement
+remain owned by application layers that can establish those facts at runtime.

package/docs/laws/evidence.md

@@ -0,0 +1,113 @@
+# Evidence law
+
+Evidence answers:
+
+```text
+What stable fact is established about this scalar value?
+```
+
+Use Evidence when the application already has the right scalar value and must
+record that a separate predicate has been established without replacing the
+value's identity.
+
+```ts
+const NonEmpty = evidence.string(
+  "NonEmpty",
+  (value) => value.length > 0,
+);
+
+const checked = NonEmpty(userId);
+```
+
+Evidence applies to immutable scalar carriers, so aliasing cannot mutate the
+underlying value after the fact is established.
+
+## Named evidence
+
+```ts
+import { evidence } from "selaws/evidence";
+
+const NonEmpty = evidence.string(
+  "NonEmpty",
+  (value) => value.length > 0,
+);
+```
+
+A concrete literal name maps to
+`~selaws.evidence:<Name>`. This Selaws-owned key keeps compatible producers
+and duplicate Selaws installations structurally compatible.
+
+Every Evidence factory has a predicate because evidence is introduced only
+after the fact is established.
+
+## Declaration-owned evidence
+
+```ts
+import {
+  defineFact,
+  type Evidence,
+} from "selaws/evidence";
+
+const nonEmptyKey: unique symbol =
+  Symbol("NonEmpty");
+
+type NonEmpty<T extends string> =
+  Evidence<T, typeof nonEmptyKey>;
+
+const NonEmpty = defineFact<string>()(
+  nonEmptyKey,
+  (establish) => ({
+    check<T extends string>(value: T) {
+      return value.length > 0
+        ? establish(value)
+        : undefined;
+    },
+  }),
+);
+```
+
+A non-empty finite set of narrow symbol fact keys represents accumulated
+declaration-owned evidence.
+
+`defineFact` keeps the establishment operation private to the declaration
+callback so the declaring module owns how the fact becomes available.
+
+## Composition
+
+Establishing evidence preserves identity and earlier evidence on the same
+scalar.
+
+```text
+UserId
++ NonEmpty
++ Ascii
+```
+
+Identity and Evidence use distinct phantom categories. Reusing one symbol for
+both categories does not make identity imply evidence.
+
+`evidence.Proven<typeof Fact, Value>` expresses a named or declaration-owned
+fact on an existing compatible scalar type when inference alone is not
+sufficient.
+
+## Transformation
+
+Evidence applies to the scalar value that was established.
+
+```ts
+const checked = NonEmpty(userId);
+
+if (checked !== undefined) {
+  const trimmed = checked.trim();
+
+  const checkedTrimmed =
+    NonEmpty(trimmed);
+}
+```
+
+An operation such as `.trim()` produces another scalar value. Relevant
+evidence is established again on that new value.
+
+Evidence does not claim mutable freshness, authorization, external provenance,
+or facts about aggregate objects. Those meanings remain with owners that can
+establish them.

package/docs/laws/identity.md

@@ -0,0 +1,126 @@
+# Identity law
+
+Identity answers:
+
+```text
+What scalar value is this?
+```
+
+Use Identity when two values can have the same JavaScript scalar
+representation but belong to different application domains.
+
+```ts
+const UserId = identity.string("UserId");
+const OrderId = identity.string("OrderId");
+
+type UserId = identity.Value<typeof UserId>;
+type OrderId = identity.Value<typeof OrderId>;
+```
+
+A `UserId` and an `OrderId` may both be strings at runtime while remaining
+distinct typed meanings.
+
+## Carrier
+
+Identity applies to immutable scalar carriers:
+
+```ts
+string | number | bigint | boolean | symbol
+```
+
+Formation preserves the original runtime primitive. Identity does not wrap the
+value in an object.
+
+## Named identity
+
+```ts
+import { identity } from "selaws/identity";
+
+const UserId = identity.string("UserId");
+type UserId = identity.Value<typeof UserId>;
+
+const id = UserId("u_1");
+```
+
+A concrete literal name maps to the Selaws-owned structural phantom key
+`~selaws.identity:<Name>`.
+
+```text
+same carrier + same literal name => same named identity
+different literal names          => different named identities
+```
+
+The name must denote one concrete identity. Broad strings, unions, patterns,
+and branded string spaces do not satisfy that requirement.
+
+Named identity is appropriate when compatible producers intentionally share the
+same structural identity contract.
+
+## Declaration-owned identity
+
+```ts
+import {
+  defineIdentity,
+  type Identity,
+} from "selaws/identity";
+
+const userIdKey: unique symbol =
+  Symbol("UserId");
+
+type UserId =
+  Identity<string, typeof userIdKey>;
+
+const UserId = defineIdentity<string>()(
+  userIdKey,
+  (mint) => ({
+    fromString(value: string): UserId {
+      return mint(value);
+    },
+  }),
+);
+```
+
+The token itself is the phantom property key. One identity requires one narrow
+symbol token. Separate symbols denote separate identities.
+
+`defineIdentity` supplies `mint` only inside the definition callback. The
+declaring module chooses which public formation operations can introduce the
+identity.
+
+## Checked local formation
+
+A predicate can own a local scalar formation condition:
+
+```ts
+const Port = identity.number(
+  "Port",
+  (value) =>
+    Number.isInteger(value) &&
+    value >= 0 &&
+    value <= 65_535,
+);
+
+const port = Port(input);
+// Port | undefined
+```
+
+Accepted scalar input returns the identity-bearing value. Rejected or
+wrong-carrier input returns `undefined`.
+
+The predicate establishes only this owner's scalar condition. Identity does not
+become an object-schema decoder, normalizer, authorization system, or external
+data validator.
+
+## Composition
+
+Forming a new identity on a scalar preserves existing intersections carried by
+that same value. Independent identities can therefore coexist when explicitly
+formed.
+
+Named identity keeps its structural key spelling unchanged, so compatible
+producers and duplicate Selaws installations preserve the same identity.
+Declaration-owned identity remains keyed by the caller-owned symbol rather than
+a package-owned unique symbol.
+
+Identity and Evidence are independent. A value's identity does not imply that a
+fact has been established about it.