@systemfsoftware/effect-cell-types 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @systemfsoftware/effect-cell-types
 
+## 5.0.0
+
+### Major Changes
+
+- A phase can no longer require a service. `Phases` drops `readContext` and
+  `writeContext`, and a read or write phase must return an effect whose context is
+  `never`.
+
+  Those two members were a claim about what a phase needed that nothing
+  recomputed. Whenever the surrounding stage was generic over `Phases`, the
+  compiler could not see through the type parameter to what the phase body
+  actually reached for, so declaring `never` for a body requiring four services
+  was accepted. The description then compiled clean and the missing service
+  surfaced only wherever it was finally applied, or nowhere at all.
+
+  Services now arrive the same way a phase's other inputs already do: as
+  parameters. Resolve them where you build the description, take them as an
+  argument, and provide them to the phase's own effect with
+  `Effect.provideContext`. Both mistakes that used to pass now fail — claiming
+  less than the body needs leaves the phase's context wider than `never`, which
+  the phase type rejects, and claiming more than it needs widens the requirement
+  of whoever builds the description, which surfaces where that builder is run.
+
+  `apply` therefore derives a context of `never` for every description, and a
+  caller can no longer be handed a requirement it never agreed to.
+
+- The wire surface is now the seven symbols it always claimed to be: the mark,
+  the minted types, `mint`, `Fields` and `wire`. Fifteen convenience wrappers
+  around the schema library are gone. A member you built with a wrapper decodes
+  to exactly what it decoded to before; only the spelling changed.
+
+  To migrate, wrap the schema library member in `mint` where you used a wrapper:
+
+  - `string`, `number`, `boolean`, `integer` → `mint(S.String)`,
+    `mint(S.Finite)`, `mint(S.Boolean)`, `mint(S.Int)`
+  - `literal(...v)` → `mint(S.Literals([...v]))`; `union(...m)` →
+    `mint(S.Union([...m]))`; `tuple(...t)` → `mint(S.Tuple([...t]))`
+  - `nullOr(m)` / `undefinedOr(m)` / `nullishOr(m)` / `array(m)` /
+    `optional(m)` / `record(k, v)` / `suspend(t)` → the same letter under
+    `mint`, e.g. `mint(S.NullOr(m))`, `mint(S.Array(m))`, `mint(S.Record(k, v))`
+  - `refine(m, predicate)` → `mint(S.refine(predicate)(m))`
+
+### Minor Changes
+
+- A write phase now receives what its own layer's read gathered, as a second
+  argument after the encoded output.
+
+  This is for the common shape where a write persists or reports on what the read
+  found while the decision in between narrowed to what it needed. Until now such a
+  write had no channel for that value, so the layer had to keep it in a mutable
+  binding beside the description — assigned during the read, read back during the
+  write — and then guard at runtime against a value that was in fact always there.
+  The argument replaces that binding and the guard with it.
+
+  Writes that do not want the value are unchanged: a write declaring a single
+  parameter still satisfies the phase type, so nothing you have already written
+  needs to move.
+
 ## 4.0.0
 
 ### Major Changes

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { Effect } from "effect/Effect";
 import * as Result$1 from "effect/Result";
 import { Result } from "effect/Result";
 import * as Schema$1 from "effect/Schema";
-import { Schema, SchemaAST } from "effect";
+import { Schema } from "effect";
 declare namespace Workflow_d_exports {
   export { Inhabited, UninhabitedDecision, UninhabitedError, UntaggedError, Workflow, WorkflowBrand, make };
 }
@@ -152,16 +152,23 @@ interface Phases {
   readonly decodeError: unknown;
   readonly readError: unknown;
   readonly writeError: unknown;
-  readonly readContext: unknown;
-  readonly writeContext: unknown;
 }
 /**
  * A read gathers what the decision needs, and may gather a product across its interior;
  * that interior is not type-visible, so no I/O count is claimed or enforced here. A step that
  * mutates in order to report — bumping a counter and returning the resulting rate — is one
  * such product, and belongs here rather than in a layer of its own.
+ *
+ * The context channel is pinned `never`: a phase requires nothing. Services are resolved by
+ * whoever builds the description and handed to the phase as ordinary parameters, which is
+ * the same edge that already gathers the read's inputs. The alternative — a `readContext`
+ * member on the bag — let an author write `never` for a body that reaches for a service, and
+ * nothing checked the claim: under a stage generic over `Phases` the compiler cannot see the
+ * lambda's requirement at all, so the description compiled and the missing service surfaced
+ * only where it was finally applied, or nowhere. Pinning it makes the lie unrepresentable
+ * instead of merely discouraged, and leaves `apply`'s derived `R` honestly `never`.
  */
-type ReadPhase<P extends Phases> = (command: P['command']) => Effect$1.Effect<P['raw'], P['readError'], P['readContext']>;
+type ReadPhase<P extends Phases> = (command: P['command']) => Effect$1.Effect<P['raw'], P['readError'], never>;
 /** Validation. Its `Left` is fatal: it reaches the derived error channel and no write runs. */
 type DecodePhase<P extends Phases> = (raw: P['raw']) => Result$1.Result<P['decoded'], P['decodeError']>;
 /**
@@ -176,7 +183,19 @@ type DecodePhase<P extends Phases> = (raw: P['raw']) => Result$1.Result<P['decod
 type DecidePhase<P extends Phases> = ((decoded: P['decoded']) => Result$1.Result<P['decision'], P['decisionError']>) & WorkflowBrand;
 /** Shapes what the write consumes. Total, so it receives both branches of the decision. */
 type EncodePhase<P extends Phases> = (outcome: Result$1.Result<P['decision'], P['decisionError']>) => P['output'];
-type WritePhase<P extends Phases> = (output: P['output']) => Effect$1.Effect<P['response'], P['writeError'], P['writeContext']>;
+/**
+ * The write. It receives the encoded `output` and, as a second argument, the `raw` its own
+ * layer's read gathered.
+ *
+ * `raw` is there because a write is frequently the point that persists or reports what the
+ * read found, while the decision in between deliberately narrows to what it needed. Without
+ * this argument such a write has no channel for it and the layer smuggles the value through
+ * a closure — a `let` beside the description, assigned in the read and consulted in the
+ * write, which then needs a runtime guard for a value the fold has already produced. The
+ * argument is second, and a write that does not want it declares one parameter: a unary
+ * function satisfies this type, so every write written before it existed is unchanged.
+ */
+type WritePhase<P extends Phases> = (output: P['output'], raw: P['raw']) => Effect$1.Effect<P['response'], P['writeError'], never>;
 /**
  * The invocation shape a folding consumer must use to call a phase's `run`:
  * - `'effect'` — `run` returns an `Effect`; yield it. (read, write)
@@ -350,7 +369,7 @@ declare const write: {
  * description's response is the last layer's. No scope is opened and interruptibility is
  * untouched, so a `Scope.Scope` a phase requires reaches the caller as part of the derived `R`.
  */
-declare const apply: <P extends Phases>(description: WriteDone<P>, command: P['command']) => Effect$1.Effect<P["response"], P["decodeError"] | P["readError"] | P["writeError"], P["readContext"] | P["writeContext"]>;
+declare const apply: <P extends Phases>(description: WriteDone<P>, command: P['command']) => Effect$1.Effect<P["response"], P["decodeError"] | P["readError"] | P["writeError"], never>;
 /** One phase's vocabulary entry: what it is called, its purity, its invocation shape. */
 interface PhaseFact {
   readonly name: Phase<Phases>['name'];
@@ -407,13 +426,13 @@ declare namespace Policy_d_exports {
 }
 type Policy<A, E, R> = (self: Effect<A, E, R>) => Effect<A, E, R>;
 declare namespace Wire_d_exports {
-  export { AnyMinted, Fields, Mark, Minted, MintedField, array, boolean, integer, literal, mint, nullOr, nullishOr, number, optional, record, refine, string, suspend, tuple, undefinedOr, union, wire };
+  export { AnyMinted, Fields, Mark, Minted, MintedField, mint, wire };
 }
 /**
  * Marker a wire member carries once this workspace declares its type. The property type is the
  * fix, so the compiler diagnostic names it.
  *
- * It sits on the schema, never on the decoded value: `Schema.Type<typeof Wire.string>` is `string`.
+ * It sits on the schema, never on the decoded value: `Schema.Type<typeof Wire.mint(S.String)>` is `string`.
  */
 interface Mark {
   readonly __WIRE_MEMBER_IS_NOT_BUILT_FROM_THE_ALPHABET__: 'this member names a type this workspace does not declare; build it from Wire, or admit a foreign schema deliberately with Wire.mint';
@@ -427,8 +446,7 @@ type Minted<A, I = A> = Schema.Codec<A, I> & Mark;
 /** Any marked schema, for constraint positions. */
 type AnyMinted = Schema.Top & Mark;
 /**
- * Any marked struct member — a schema, or a property signature from {@link optional}.
- *
+ * Any marked struct member — a schema, or a property signature from `S.optional`.
  * The permissive `Constraint` arm rather than a narrower schema type, whose `never` variants
  * would fail the assignability check before the marker is reached, leaving the diagnostic to
  * report an unrelated type error.
@@ -437,37 +455,11 @@ type MintedField = Schema.Constraint & Mark;
 /**
  * Mark a member whose type this workspace declares.
  *
- * Prefer the alphabet below; reach for this only to admit a schema the alphabet cannot express,
- * including a vendor's own. The value returned is the one passed in, and its concrete type is
- * preserved, so a marked struct stays a struct and Effect's inference keeps working.
+ * The value returned is the one passed in, and its concrete type is preserved, so a marked
+ * struct stays a struct and Effect's inference keeps working. Reach for it to admit anything
+ * the schema library can express, including a vendor's own schema — deliberately.
  */
 declare const mint: <Field extends Schema.Constraint>(field: Field) => Field & Mark;
-declare const string: Schema.String & Mark;
-declare const number: Schema.Finite & Mark;
-declare const boolean: Schema.Boolean & Mark;
-declare const integer: Schema.Int & Mark;
-declare const literal: <const Literals extends ReadonlyArray<SchemaAST.LiteralValue>>(...literals: Literals) => Schema.Literals<Literals> & Mark;
-declare const nullOr: <A, I>(member: Minted<A, I>) => Minted<A | null, I | null>;
-declare const undefinedOr: <A, I>(member: Minted<A, I>) => Minted<A | undefined, I | undefined>;
-declare const nullishOr: <A, I>(member: Minted<A, I>) => Minted<A | null | undefined, I | null | undefined>;
-declare const array: <A, I>(member: Minted<A, I>) => Minted<ReadonlyArray<A>, ReadonlyArray<I>>;
-/** A field that may be absent from the payload entirely, as distinct from present and `undefined`. */
-declare const optional: <Member extends AnyMinted>(member: Member) => Schema.optional<Member> & Mark;
-declare const record: <K extends Schema.Record.Key & Mark, V extends AnyMinted>(key: K, value: V) => Schema.$Record<K, V> & Mark;
-declare const union: <Members extends readonly [AnyMinted, AnyMinted, ...Array<AnyMinted>]>(...members: Members) => Schema.Union<Members> & Mark;
-declare const tuple: <Elements extends ReadonlyArray<AnyMinted>>(...elements: Elements) => Schema.Tuple<Elements> & Mark;
-declare const suspend: <A, I>(thunk: () => Minted<A, I>) => Minted<A, I>;
-/**
- * Constrain a member's values. Effect's own `member.pipe(Schema.check(Schema.isMinLength(1)))`
- * preserves the mark, but returns the schema with the concrete decode/encode pair fused; this
- * combinator is the alphabet's own shape for the same operation, so a refined member keeps the
- * declaration this workspace makes of its type.
- *
- * `S.refine` needs a type-guard as its predicate argument; the workspace's predicate is a plain
- * `(a: A) => boolean` that narrows nothing, so a truth-preserving `value is A` guard is written
- * at this one call site rather than widening the public signature.
- */
-declare const refine: <A, I>(member: Minted<A, I>, predicate: (a: A) => boolean, annotations?: Schema.Annotations.Filter) => Minted<A, I>;
 type Fields = Record<string, MintedField>;
 declare const wire: <F extends Fields>(fields: F) => Schema.Struct<F> & Mark;
 //#endregion

package/dist/index.mjs

@@ -218,9 +218,15 @@ const runLayer = (layer, command) => Effect$1.gen(function* () {
 	const last = phases[phases.length - 1];
 	if (!last || last.name !== "write") return yield* Effect$1.die(/* @__PURE__ */ new Error("effect-cell-types: a layer reached the interpreter without a write phase closing it"));
 	let value = command;
+	let raw = command;
 	for (const phase of phases.slice(0, -1)) switch (phase.convention) {
 		case "effect":
-			value = yield* phase.run(value);
+			if (phase.name === "read") {
+				value = yield* phase.run(value);
+				raw = value;
+				break;
+			}
+			value = yield* phase.run(value, raw);
 			break;
 		case "either-fail":
 			value = yield* Result$1.match(phase.run(value), {
@@ -240,7 +246,7 @@ const runLayer = (layer, command) => Effect$1.gen(function* () {
 			return yield* Effect$1.die(/* @__PURE__ */ new Error(`effect-cell-types: unknown phase convention ${String(unreachable)}`));
 		}
 	}
-	return yield* last.run(value);
+	return yield* last.run(value, raw);
 });
 /**
 * Applies a description. The return type is deliberately not annotated: `gen` accumulates
@@ -312,79 +318,38 @@ var Policy_exports = /* @__PURE__ */ __exportAll({});
 *
 * ```ts
 * import { Wire } from '@systemfsoftware/effect-cell-types'
-* import { Schema } from 'effect'
+* import { Effect, Schema as S } from 'effect'
 *
 * const Invoice = Wire.wire({
-*   id: Wire.string,
-*   amountDue: Wire.nullOr(Wire.number),
-*   status: Wire.literal('draft', 'open', 'paid'),
-*   lineItems: Wire.array(Wire.string),
-*   metadata: Wire.record(Wire.string, Wire.string),
-*   deleted: Wire.optional(Wire.boolean),
+*   id: Wire.mint(S.String),
+*   amountDue: Wire.mint(S.NullOr(Wire.mint(S.Finite))),
+*   status: Wire.mint(S.Literals(['draft', 'open', 'paid'])),
+*   lineItems: Wire.mint(S.Array(Wire.mint(S.String))),
+*   metadata: Wire.mint(S.Record(Wire.mint(S.String), Wire.mint(S.String))),
+*   deleted: Wire.mint(S.optional(Wire.mint(S.Boolean))),
 * })
 *
 * // Decodes to your own type — `{ id: string; amountDue: number | null; ... }`.
-* const invoice = Schema.decodeUnknownSync(Invoice)(payload)
+* const invoice = yield* Schema.decode(Invoice)(payload)
 * ```
 *
-* Only declarations that use the alphabet are constrained, and {@link mint} admits a foreign
-* schema deliberately. It is a guardrail, not a security boundary.
+* Only declarations that name members through {@link mint} are constrained, and mint admits a
+* foreign schema deliberately. It is a guardrail, not a security boundary.
 */
 var Wire_exports = /* @__PURE__ */ __exportAll({
-	array: () => array,
-	boolean: () => boolean,
-	integer: () => integer,
-	literal: () => literal,
 	mint: () => mint,
-	nullOr: () => nullOr,
-	nullishOr: () => nullishOr,
-	number: () => number,
-	optional: () => optional,
-	record: () => record,
-	refine: () => refine,
-	string: () => string,
-	suspend: () => suspend,
-	tuple: () => tuple,
-	undefinedOr: () => undefinedOr,
-	union: () => union,
 	wire: () => wire
 });
 /**
 * Mark a member whose type this workspace declares.
 *
-* Prefer the alphabet below; reach for this only to admit a schema the alphabet cannot express,
-* including a vendor's own. The value returned is the one passed in, and its concrete type is
-* preserved, so a marked struct stays a struct and Effect's inference keeps working.
+* The value returned is the one passed in, and its concrete type is preserved, so a marked
+* struct stays a struct and Effect's inference keeps working. Reach for it to admit anything
+* the schema library can express, including a vendor's own schema — deliberately.
 */
 const mint = (field) => {
 	return field;
 };
-const string = mint(Schema.String);
-const number = mint(Schema.Finite);
-const boolean = mint(Schema.Boolean);
-const integer = mint(Schema.Int);
-const literal = (...literals) => mint(Schema.Literals(literals));
-const nullOr = (member) => mint(Schema.NullOr(member));
-const undefinedOr = (member) => mint(Schema.UndefinedOr(member));
-const nullishOr = (member) => mint(Schema.NullishOr(member));
-const array = (member) => mint(Schema.Array(member));
-/** A field that may be absent from the payload entirely, as distinct from present and `undefined`. */
-const optional = (member) => mint(Schema.optional(member));
-const record = (key, value) => mint(Schema.Record(key, value));
-const union = (...members) => mint(Schema.Union(members));
-const tuple = (...elements) => mint(Schema.Tuple(elements));
-const suspend = (thunk) => mint(Schema.suspend(thunk));
-/**
-* Constrain a member's values. Effect's own `member.pipe(Schema.check(Schema.isMinLength(1)))`
-* preserves the mark, but returns the schema with the concrete decode/encode pair fused; this
-* combinator is the alphabet's own shape for the same operation, so a refined member keeps the
-* declaration this workspace makes of its type.
-*
-* `S.refine` needs a type-guard as its predicate argument; the workspace's predicate is a plain
-* `(a: A) => boolean` that narrows nothing, so a truth-preserving `value is A` guard is written
-* at this one call site rather than widening the public signature.
-*/
-const refine = (member, predicate, annotations) => mint(Schema.refine((value) => predicate(value), annotations)(member));
 const wire = (fields) => mint(Schema.Struct(fields));
 //#endregion
 export { Cell_exports as Cell, Policy_exports as Policy, Wire_exports as Wire, Workflow_exports as Workflow };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@systemfsoftware/effect-cell-types",
   "license": "Apache-2.0",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
@@ -32,23 +32,23 @@
     "dist"
   ],
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.111",
+    "@effect/vitest": "4.0.0-rc.112",
     "@microsoft/api-extractor": "^7.58.7",
     "@systemfsoftware/arethetypeswrong-cli": "^1.1.1",
     "@types/node": "^24",
-    "effect": "4.0.0-rc.111",
+    "effect": "^4.0.0-rc.112",
     "oxlint": "^1.77.0",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",
     "tstyche": "^7.1.0",
     "vitest": "^4.1.10",
     "@systemfsoftware/effect-gherkin-spec": "2.0.1",
+    "@systemfsoftware/tsconfig": "^1.3.3",
     "@systemfsoftware/oxlint-config": "^0.1.0",
-    "@systemfsoftware/vitest-config": "^0.1.0",
-    "@systemfsoftware/tsconfig": "^1.3.3"
+    "@systemfsoftware/vitest-config": "^0.1.0"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-rc.111"
+    "effect": "^4.0.0-rc.112"
   },
   "publishConfig": {
     "provenance": true
@@ -58,7 +58,6 @@
     "build": "tsdown && pnpm api:check",
     "typecheck": "tsc --noEmit --incremental",
     "test": "vitest run --passWithNoTests",
-    "test:run": "vitest run --passWithNoTests",
     "test:types": "TSTYCHE_TYPESCRIPT_MODULE=tstyche-typescript tstyche",
     "api:check": "api-extractor run",
     "api:update": "api-extractor run --local",