@systemfsoftware/effect-schema-law 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @systemfsoftware/effect-schema-law
 
+## 0.9.0
+
+### Minor Changes
+
+- Declarations that were never meant to be hidden are public again.
+
+### Patch Changes
+
+- The peer requirements for `effect` and for the Effect test-runner integration now accept any compatible `4.0.0-rc` release, instead of demanding one exact release candidate.
+
+  Installing alongside a newer release candidate no longer reports an unmet peer dependency or resolves a second copy of `effect` into the dependency tree.
+
+## 0.8.0
+
+### Minor Changes
+
+- cut over to effect v4 (4.0.0-rc.108): public surface derives from effect types; peers flip effect ^3→^4
+
+### Patch Changes
+
+- Array types are spelled one way. `Array<T>` and `ReadonlyArray<T>` in emitted
+  declarations become `T[]` and `readonly T[]`, which the type checker cannot tell
+  apart: no exported type changes, only how it is written.
+
+- New version is published through npm trusted publishing, so it carries a provenance attestation you can verify.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -27,22 +27,25 @@ ruleOfSchemas('Email', Email)
 import { boundedUnion, ruleOfSchemas } from '@systemfsoftware/effect-schema-law'
 import { Schema as S } from 'effect'
 
-interface Lit {
-  readonly _tag: 'Lit'
-  readonly value: number
-}
-interface Add {
-  readonly _tag: 'Add'
+// The tag is declared once, by the schema. A hand-written `readonly _tag: 'Lit'`
+// member is refused by `no-manual-tag-member`, and deriving it keeps the tag and
+// the schema from drifting apart.
+const LitBase = S.TaggedStruct('Lit', { value: S.JsonNumber })
+const AddBase = S.TaggedStruct('Add', {})
+
+type Lit = S.Schema.Type<typeof LitBase>
+type Add = S.Schema.Type<typeof AddBase> & {
   readonly left: Expr
   readonly right: Expr
 }
 type Expr = Lit | Add
 
-const Lit = S.Struct({ _tag: S.Literal('Lit'), value: S.JsonNumber })
-const Add: S.Schema<Add> = S.suspend((): S.Schema<Add> => S.Struct({ _tag: S.Literal('Add'), left: Expr, right: Expr }))
+// Only the self-referential fields stay hand-written. The tag never participates in
+// the recursion, so the base carries it and `suspend` carries only the cycle.
+const Add: S.Codec<Add> = S.suspend((): S.Codec<Add> => S.Struct({ ...AddBase.fields, left: Expr, right: Expr }))
 
-const Expr: S.Schema<Expr> = boundedUnion('Expr', {
-  base: [Lit],
+const Expr: S.Codec<Expr> = boundedUnion('Expr', {
+  base: [LitBase],
   recur: [Add],
 })
 

package/dist/effect-schema-law-untrimmed.d.ts

@@ -0,0 +1,144 @@
+import * as AST from 'effect/SchemaAST';
+import { FastCheck } from 'effect/testing';
+import { Schema } from 'effect';
+
+/** Verdict for one schema's obligation set, carrying the detail R7 requires in a failure. */
+export declare interface AdequacyReport {
+    readonly adequate: boolean;
+    readonly undischarged: readonly Obligation[];
+    readonly message: string;
+}
+
+/**
+ * Which obligations no declared generator discharges. A bare "adequacy failed" leaves
+ * the author nothing to act on, so the message names each node's tag, every path
+ * reaching it, and the witness that proves the weakening is permissive.
+ */
+export declare const adequacyReport: (schema: Schema.ConstraintDecoder<unknown>, generators: RefusalGenerators) => AdequacyReport;
+
+/**
+ * One weakening of an Effect schema, produced by `armsOf`. Each arm identifies
+ * the AST node it removes; the rebuilt tree is the surrounding schema with
+ * that node replaced by its child or, for a dropped refinement, by the same
+ * node without that check.
+ *
+ * Two schemas reaching the same `node` share its identity and therefore its
+ * obligation key — the deduplication is the entire point of the shape.
+ */
+export declare interface Arm {
+    readonly kind: 'drop-refinement' | 'drop-to-arm' | 'drop-from-arm';
+    readonly path: string;
+    /** The node this arm removes — the obligation key. Two arms removing it are one obligation. */
+    readonly node: AST.AST;
+    readonly weakened: AST.AST;
+}
+
+/**
+ * Walk an Effect schema's AST and return every weakenable arm, recursively
+ * through `Objects`, `Union`, `Arrays`, `Declaration`, and `Suspend`, plus
+ * the v4 per-node `Checks` (refinements) and encoding `Link` chains
+ * (transformations). The walk terminates on `Suspend` cycles at `depthCap`
+ * levels; every other AST tag is a leaf whose children cannot hold a
+ * refinement, and `Union` over structurally identical members is fine because
+ * the walk keys arms by node identity, not shape.
+ *
+ * The arm's `node` is the AST node its weakening removes; reference identity
+ * is the obligation key (R3). `weakened` is the enclosing tree with `node`
+ * replaced by its child, ready to be passed to `Schema.make`.
+ */
+export declare const armsOf: (schema: Schema.ConstraintDecoder<unknown>) => readonly Arm[];
+
+/** An arm no source could draw for: the search could not look, which is not the same as finding nothing. */
+export declare interface BlindArm {
+    readonly path: string;
+    readonly kind: string;
+    readonly message: string;
+}
+
+export declare const boundedUnion: <Base extends readonly [Schema.ConstraintCodec<unknown, unknown>, ...readonly Schema.ConstraintCodec<unknown, unknown>[]], Recur extends readonly [Schema.ConstraintCodec<unknown, unknown>, ...readonly Schema.ConstraintCodec<unknown, unknown>[]]>(identifier: string, options: {
+    readonly base: Base;
+    readonly recur: Recur;
+    readonly maxDepth?: number;
+}) => Schema.Codec<Base[number]['Type'] | Recur[number]['Type'], Base[number]['Encoded'] | Recur[number]['Encoded']>;
+
+/**
+ * For each obligation, return the names of the generators whose draws
+ * the weakened schema accepts AND the original rejects. Generators
+ * whose draws the original also accepts do not discharge — they are
+ * the language the original already covers. Generators whose draws
+ * the weakened schema rejects do not discharge either.
+ *
+ * The original schema is part of the signature because discharge is
+ * defined relative to it.
+ */
+export declare const dischargedBy: (schema: Schema.ConstraintDecoder<unknown>, obligations: ReadonlyMap<AST.AST, Obligation>, generators: Readonly<Record<string, NamedArbitrary>>) => ReadonlyMap<AST.AST, readonly string[]>;
+
+/** True when `value` is a witness for some obligation: accepted by that weakening, rejected by the schema. */
+export declare const discriminates: (schema: Schema.ConstraintDecoder<unknown>, obligations: ReadonlyMap<AST.AST, Obligation>, value: unknown) => boolean;
+
+declare type NamedArbitrary = FastCheck.Arbitrary<unknown>;
+
+/**
+ * One node-keyed refutation obligation: a witness exists that the
+ * weakened schema accepts and the original rejects. Obligations are
+ * keyed by the AST node the arm removes (R3); several paths reaching
+ * one node are one obligation carrying several paths.
+ */
+export declare interface Obligation {
+    readonly node: AST.AST;
+    readonly tag: string;
+    readonly paths: readonly string[];
+    readonly weakened: AST.AST;
+    readonly witness: unknown;
+}
+
+/** Every arm of a schema, split into the ones a witness proved and the ones nothing could see. */
+export declare interface ObligationScan {
+    readonly obligations: ReadonlyMap<AST.AST, Obligation>;
+    readonly blind: readonly BlindArm[];
+}
+
+export declare const obligationsOf: (schema: Schema.ConstraintDecoder<unknown>) => ReadonlyMap<AST.AST, Obligation>;
+
+/** Named refusal generators: each draws rejection-class inputs the schema must reject. */
+export declare type RefusalGenerators = Record<string, FastCheck.Arbitrary<unknown>>;
+
+/**
+ * Property-test one schema's rejection contract. Registers per generator a refusal
+ * property (the schema rejects every draw) and a discrimination property (each draw is
+ * explained by some weakening), plus one adequacy property for the schema.
+ *
+ * Names follow the house convention: `∀b_<generator>_⊥`, `∀g_<generator>_discriminates`,
+ * `∀s_<schema>_adequate` — disjoint from `ruleOfSchemas`' `∀x_<name>_=x` pair.
+ */
+export declare const refutes: (schema: Schema.ConstraintDecoder<unknown>, generators: RefusalGenerators) => void;
+
+/**
+ * Property-test the round-trip and encode-stability laws of any Effect Schema.
+ *
+ * Registers two fast-check properties with `@effect/vitest`:
+ *   1. `∀x. enc(dec(enc(x))) === enc(x)` — encode stability across decode.
+ *   2. `∀x. dec(enc(x)) === x` — round-trip identity.
+ *
+ * Use inside a `describe` block to scope the generated tests.
+ */
+export declare const ruleOfSchemas: <A, I>(name: string, schema: Schema.Codec<A, I>) => void;
+
+/**
+ * Walk `armsOf` and classify every arm. An arm is an obligation iff a witness
+ * exists — an input the weakened schema accepts and the original rejects —
+ * drawn from a fallback chain (encoded arbitrary, type arbitrary, generic
+ * pool). An arm whose every source failed to construct is `blind`: "no
+ * obligation" and "could not look" are different answers, and collapsing
+ * them is the silent miss this scan exists to prevent.
+ */
+export declare const scanObligations: (schema: Schema.ConstraintDecoder<unknown>) => ObligationScan;
+
+/**
+ * The sampling budget is a property of the contract, not a knob. The
+ * plan pins the expectation against a literal table; the kernel draws
+ * up to this many candidates per source before exhausting the chain.
+ */
+export declare const WITNESS_BUDGET = 256;
+
+export { }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@systemfsoftware/effect-schema-law",
   "license": "Apache-2.0",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/systemfsoftware/systemfsoftware.git",
-    "directory": "packages/effect-schema-law"
+    "directory": "packages/core/effect/schema/law"
   },
-  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/effect-schema-law#readme",
+  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/core/effect/schema/law#readme",
   "bugs": "https://github.com/systemfsoftware/systemfsoftware/issues",
   "description": "Property-test the codec laws of any Effect Schema in one call — decode/encode round-trip identity and encode stability, generated with @effect/vitest and fast-check.",
   "keywords": [
@@ -36,24 +36,24 @@
     "dist"
   ],
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.108",
+    "@effect/vitest": "4.0.0-rc.111",
     "@microsoft/api-extractor": "^7.58.7",
     "@systemfsoftware/arethetypeswrong-cli": "^1.1.1",
     "@types/node": "^24",
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0-rc.111",
     "fast-check": "^4",
     "oxlint": "^1.77.0",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",
     "vitest": "^4.1.10",
+    "@systemfsoftware/effect-gherkin-spec": "^2.0.1",
+    "@systemfsoftware/tsconfig": "^1.3.3",
     "@systemfsoftware/oxlint-config": "^0.1.0",
-    "@systemfsoftware/tsconfig": "^1.3.2",
-    "@systemfsoftware/effect-gherkin-spec": "^1.0.0",
     "@systemfsoftware/vitest-config": "^0.1.0"
   },
   "peerDependencies": {
-    "@effect/vitest": "4.0.0-rc.108",
-    "effect": "4.0.0-rc.108",
+    "@effect/vitest": "^4.0.0-rc.111",
+    "effect": "^4.0.0-rc.111",
     "vitest": "*"
   },
   "publishConfig": {