@semiont/core 0.5.8 → 0.5.10

package/dist/testing.d.ts

@@ -0,0 +1,96 @@
+import { Observable } from 'rxjs';
+
+/**
+ * Marker for the state-unit pattern: a stateful, lifecycled object with an
+ * RxJS-shaped public surface, constructed by a factory function
+ * (`createFooStateUnit`), with internal state held in a closure.
+ *
+ * The structural contract is `dispose()` — the rest of the pattern
+ * (closure-based identity, Observable public surface, internal Subjects
+ * exposed as `.asObservable()` views, no leaked subscriptions, composition
+ * by parameter rather than ownership) is convention, made executable by the
+ * axiom harness in `@semiont/core/testing` (`assertStateUnitAxioms`).
+ *
+ * Lives in `@semiont/core` (not sdk) so every layer can share one definition
+ * without dependency cycles — `http-transport`'s `ActorStateUnit` sits below
+ * sdk and would otherwise have to re-declare it. See
+ * `packages/sdk/docs/STATE-UNITS.md` for the full pattern and rationale, and
+ * `.plans/STATE-UNIT-AXIOMS.md` for the axiom ledger.
+ */
+interface StateUnit {
+    /**
+     * Idempotent, total teardown. Completes every Subject the unit owns,
+     * unsubscribes every internal subscription, releases timers / abort
+     * controllers / network handles. Safe to call multiple times — the
+     * second call is a no-op.
+     */
+    dispose(): void;
+}
+
+/**
+ * Executable enforcement of the StateUnit pattern — the runtime twin of
+ * `packages/sdk/docs/STATE-UNITS.md` and the ledger in
+ * `.plans/STATE-UNIT-AXIOMS.md`. The `StateUnit` interface's own comment notes
+ * the pattern is convention; this file makes it executable.
+ *
+ * `assertStateUnitAxioms(spec)` runs every applicable axiom against a factory in
+ * one shot, throwing a labeled Error on the first violation (the axiom id is in
+ * the message). It is framework-agnostic on purpose — only `rxjs` + `fast-check`,
+ * no `vitest` — so it ships through `@semiont/core/testing` and any package's test
+ * runner can invoke it from a single `it(...)` per state unit. It lives in core
+ * (not sdk) so even packages below sdk (e.g. `http-transport`) can use it without
+ * a dependency cycle.
+ *
+ * Axioms (random-input dimension; fast-check):
+ *   A5        dispose() is idempotent and total (n ∈ [1,20] calls never throw)
+ *   A5b       post-dispose inertness — every public method is a no-op after dispose
+ *   A6        every pre-dispose subscriber (k ∈ [1,10]) sees `complete` on dispose
+ *   X3-runtime instance isolation — driving one instance never moves another's surfaces
+ * Structural assertions (single-shot):
+ *   A1        plain-object identity (no class instance)
+ *   X1        no raw Subject on the public surface
+ *   A7-passed disposing the unit must NOT dispose an injected dependency
+ *   A7-owned  disposing the unit MUST dispose its internally-constructed children
+ */
+
+/**
+ * A disposable stand-in for an injected dependency. Pass one as a unit's
+ * constructor arg, then list it in `setup().passedIn` so A7-passed can assert
+ * the unit never disposed it. Counts calls so A7-passed also holds under the
+ * repeated-dispose stress of A5.
+ */
+interface DisposeProbe extends StateUnit {
+    readonly disposeCount: number;
+}
+declare function disposeProbe(): DisposeProbe;
+type SetupResult<T extends StateUnit> = T | {
+    unit: T;
+    passedIn?: readonly DisposeProbe[];
+    teardown?: () => void;
+};
+interface StateUnitAxiomSpec<T extends StateUnit> {
+    /**
+     * Build a FRESH unit. Called many times (fast-check re-runs), so it must
+     * return an independent instance each call. Return the bare unit, or an object
+     * carrying the injected `passedIn` probes (A7-passed) and a `teardown` to
+     * release per-instance resources (e.g. a mock bus).
+     */
+    setup: () => SetupResult<T>;
+    /** Owned public Observables — Subjects the unit completes on dispose (A6, X3, post-dispose inertness). */
+    surfaces?: (unit: T) => readonly Observable<unknown>[];
+    /** Public input methods as zero-arg callers (A5b post-dispose, X3 drive). */
+    invocations?: (unit: T) => readonly (() => unknown)[];
+    /** Surfaces of internally-constructed children — must complete when the outer disposes (A7-owned). */
+    ownedChildSurfaces?: (unit: T) => readonly Observable<unknown>[];
+    /** fast-check run budget per property (default 30). */
+    numRuns?: number;
+}
+/**
+ * Run every applicable axiom against `spec`. Throws a labeled Error on the first
+ * violation. Axioms whose accessors are omitted are skipped (e.g. A7-passed
+ * runs only when `setup` returns `passedIn`; A6 only when `surfaces` is given).
+ */
+declare function assertStateUnitAxioms<T extends StateUnit>(spec: StateUnitAxiomSpec<T>): void;
+
+export { assertStateUnitAxioms, disposeProbe };
+export type { DisposeProbe, StateUnitAxiomSpec };

package/dist/testing.js

@@ -0,0 +1,176 @@
+import * as fc from 'fast-check';
+import { Subject } from 'rxjs';
+
+// src/state-unit-axioms.ts
+function disposeProbe() {
+  let n = 0;
+  return {
+    dispose() {
+      n += 1;
+    },
+    get disposeCount() {
+      return n;
+    }
+  };
+}
+function normalize(r) {
+  if (r && typeof r === "object" && "unit" in r) {
+    return { unit: r.unit, passedIn: r.passedIn ?? [], teardown: r.teardown ?? (() => {
+    }) };
+  }
+  return { unit: r, passedIn: [], teardown: () => {
+  } };
+}
+function swallowAsync(value) {
+  if (value && typeof value === "object" && typeof value.then === "function") {
+    value.then(void 0, () => {
+    });
+  }
+}
+function assertStateUnitAxioms(spec) {
+  const numRuns = spec.numRuns ?? 30;
+  const fresh = () => normalize(spec.setup());
+  const run = (axiom, prop) => {
+    try {
+      fc.assert(prop, { numRuns });
+    } catch (e) {
+      throw new Error(`${axiom}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  };
+  {
+    const { unit, teardown } = fresh();
+    const proto = Object.getPrototypeOf(unit);
+    if (proto !== Object.prototype && proto !== null) {
+      throw new Error("A1: state unit is not a plain object (has a class prototype)");
+    }
+    unit.dispose();
+    teardown();
+  }
+  {
+    const { unit, teardown } = fresh();
+    for (const [key, value] of Object.entries(unit)) {
+      if (value instanceof Subject && value.source === void 0) {
+        throw new Error(`X1: public field "${key}" is a raw Subject \u2014 expose it via .asObservable()`);
+      }
+    }
+    unit.dispose();
+    teardown();
+  }
+  {
+    const { unit, passedIn, teardown } = fresh();
+    unit.dispose();
+    passedIn.forEach((probe, i) => {
+      if (probe.disposeCount > 0) {
+        throw new Error(`A7-passed: the unit disposed injected dependency #${i} (it doesn't own it)`);
+      }
+    });
+    teardown();
+  }
+  run("A5", fc.property(fc.integer({ min: 1, max: 20 }), (n) => {
+    const { unit, passedIn, teardown } = fresh();
+    for (let i = 0; i < n; i++) unit.dispose();
+    passedIn.forEach((probe, i) => {
+      if (probe.disposeCount > 0) {
+        throw new Error(`injected dependency #${i} disposed under ${n} dispose() calls`);
+      }
+    });
+    teardown();
+  }));
+  if (spec.surfaces) {
+    const surfaces = spec.surfaces;
+    run("A6", fc.property(fc.integer({ min: 1, max: 10 }), (k) => {
+      const { unit, teardown } = fresh();
+      const completed = [];
+      const subs = surfaces(unit).flatMap(
+        (o) => Array.from({ length: k }, () => {
+          const idx = completed.push(false) - 1;
+          return o.subscribe({ complete: () => {
+            completed[idx] = true;
+          } });
+        })
+      );
+      unit.dispose();
+      completed.forEach((seen, idx) => {
+        if (!seen) throw new Error(`a subscriber did not see complete on dispose (k=${k}, sub #${idx})`);
+      });
+      subs.forEach((s) => s.unsubscribe());
+      teardown();
+    }));
+  }
+  if (spec.invocations) {
+    const invocations = spec.invocations;
+    run("A5b", fc.property(fc.array(fc.nat(), { maxLength: 12 }), (seq) => {
+      const { unit, teardown } = fresh();
+      const callers = invocations(unit);
+      unit.dispose();
+      for (const raw of seq) {
+        if (callers.length === 0) break;
+        swallowAsync(callers[raw % callers.length]());
+      }
+      teardown();
+    }));
+  }
+  if (spec.surfaces && spec.invocations) {
+    const surfaces = spec.surfaces;
+    const invocations = spec.invocations;
+    run("X3-runtime", fc.property(fc.array(fc.nat(), { minLength: 1, maxLength: 8 }), (seq) => {
+      const a = fresh();
+      const b = fresh();
+      const bSurfaces = surfaces(b.unit);
+      const bCounts = bSurfaces.map(() => 0);
+      const bSubs = bSurfaces.map((o, i) => o.subscribe(() => {
+        bCounts[i] += 1;
+      }));
+      const baseline = bCounts.slice();
+      const aCallers = invocations(a.unit);
+      for (const raw of seq) {
+        if (aCallers.length === 0) break;
+        swallowAsync(aCallers[raw % aCallers.length]());
+      }
+      bCounts.forEach((count, i) => {
+        if (count !== baseline[i]) {
+          throw new Error(`driving instance A perturbed instance B's surface #${i}`);
+        }
+      });
+      bSubs.forEach((s) => s.unsubscribe());
+      a.unit.dispose();
+      b.unit.dispose();
+      a.teardown();
+      b.teardown();
+    }));
+  }
+  if (spec.ownedChildSurfaces) {
+    const { unit, teardown } = fresh();
+    const childSurfaces = spec.ownedChildSurfaces(unit);
+    const completed = childSurfaces.map(() => false);
+    const subs = childSurfaces.map((o, i) => o.subscribe({ complete: () => {
+      completed[i] = true;
+    } }));
+    unit.dispose();
+    completed.forEach((seen, i) => {
+      if (!seen) throw new Error(`A7-owned: owned child surface #${i} did not complete on outer dispose`);
+    });
+    subs.forEach((s) => s.unsubscribe());
+    teardown();
+  }
+  if (spec.surfaces) {
+    const { unit, teardown } = fresh();
+    unit.dispose();
+    spec.surfaces(unit).forEach((o, i) => {
+      let nexts = 0;
+      let done = false;
+      o.subscribe({ next: () => {
+        nexts += 1;
+      }, complete: () => {
+        done = true;
+      } }).unsubscribe();
+      if (nexts > 0) throw new Error(`A5b/inert: owned surface #${i} emitted a value after dispose`);
+      if (!done) throw new Error(`A5b/inert: owned surface #${i} did not complete after dispose`);
+    });
+    teardown();
+  }
+}
+
+export { assertStateUnitAxioms, disposeProbe };
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state-unit-axioms.ts"],"names":[],"mappings":"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","file":"testing.js","sourcesContent":["/**\n * Executable enforcement of the StateUnit pattern — the runtime twin of\n * `packages/sdk/docs/STATE-UNITS.md` and the ledger in\n * `.plans/STATE-UNIT-AXIOMS.md`. The `StateUnit` interface's own comment notes\n * the pattern is convention; this file makes it executable.\n *\n * `assertStateUnitAxioms(spec)` runs every applicable axiom against a factory in\n * one shot, throwing a labeled Error on the first violation (the axiom id is in\n * the message). It is framework-agnostic on purpose — only `rxjs` + `fast-check`,\n * no `vitest` — so it ships through `@semiont/core/testing` and any package's test\n * runner can invoke it from a single `it(...)` per state unit. It lives in core\n * (not sdk) so even packages below sdk (e.g. `http-transport`) can use it without\n * a dependency cycle.\n *\n * Axioms (random-input dimension; fast-check):\n *   A5        dispose() is idempotent and total (n ∈ [1,20] calls never throw)\n *   A5b       post-dispose inertness — every public method is a no-op after dispose\n *   A6        every pre-dispose subscriber (k ∈ [1,10]) sees `complete` on dispose\n *   X3-runtime instance isolation — driving one instance never moves another's surfaces\n * Structural assertions (single-shot):\n *   A1        plain-object identity (no class instance)\n *   X1        no raw Subject on the public surface\n *   A7-passed disposing the unit must NOT dispose an injected dependency\n *   A7-owned  disposing the unit MUST dispose its internally-constructed children\n */\n\nimport * as fc from 'fast-check';\nimport { Subject, type Observable } from 'rxjs';\nimport type { StateUnit } from './state-unit';\n\n/**\n * A disposable stand-in for an injected dependency. Pass one as a unit's\n * constructor arg, then list it in `setup().passedIn` so A7-passed can assert\n * the unit never disposed it. Counts calls so A7-passed also holds under the\n * repeated-dispose stress of A5.\n */\nexport interface DisposeProbe extends StateUnit {\n  readonly disposeCount: number;\n}\n\nexport function disposeProbe(): DisposeProbe {\n  let n = 0;\n  return {\n    dispose() { n += 1; },\n    get disposeCount() { return n; },\n  };\n}\n\ntype SetupResult<T extends StateUnit> =\n  | T\n  | { unit: T; passedIn?: readonly DisposeProbe[]; teardown?: () => void };\n\nexport interface StateUnitAxiomSpec<T extends StateUnit> {\n  /**\n   * Build a FRESH unit. Called many times (fast-check re-runs), so it must\n   * return an independent instance each call. Return the bare unit, or an object\n   * carrying the injected `passedIn` probes (A7-passed) and a `teardown` to\n   * release per-instance resources (e.g. a mock bus).\n   */\n  setup: () => SetupResult<T>;\n  /** Owned public Observables — Subjects the unit completes on dispose (A6, X3, post-dispose inertness). */\n  surfaces?: (unit: T) => readonly Observable<unknown>[];\n  /** Public input methods as zero-arg callers (A5b post-dispose, X3 drive). */\n  invocations?: (unit: T) => readonly (() => unknown)[];\n  /** Surfaces of internally-constructed children — must complete when the outer disposes (A7-owned). */\n  ownedChildSurfaces?: (unit: T) => readonly Observable<unknown>[];\n  /** fast-check run budget per property (default 30). */\n  numRuns?: number;\n}\n\ninterface Normalized<T extends StateUnit> {\n  unit: T;\n  passedIn: readonly DisposeProbe[];\n  teardown: () => void;\n}\n\nfunction normalize<T extends StateUnit>(r: SetupResult<T>): Normalized<T> {\n  if (r && typeof r === 'object' && 'unit' in r) {\n    return { unit: r.unit, passedIn: r.passedIn ?? [], teardown: r.teardown ?? (() => {}) };\n  }\n  return { unit: r as T, passedIn: [], teardown: () => {} };\n}\n\nfunction swallowAsync(value: unknown): void {\n  if (value && typeof value === 'object' && typeof (value as { then?: unknown }).then === 'function') {\n    (value as Promise<unknown>).then(undefined, () => {});\n  }\n}\n\n/**\n * Run every applicable axiom against `spec`. Throws a labeled Error on the first\n * violation. Axioms whose accessors are omitted are skipped (e.g. A7-passed\n * runs only when `setup` returns `passedIn`; A6 only when `surfaces` is given).\n */\nexport function assertStateUnitAxioms<T extends StateUnit>(spec: StateUnitAxiomSpec<T>): void {\n  const numRuns = spec.numRuns ?? 30;\n  const fresh = (): Normalized<T> => normalize(spec.setup());\n\n  // fast-check's default falsification message is just \"Property failed after N\n  // tests {seed}\" — it drops the thrown axiom id. Prepend the axiom so a real\n  // failure names itself; the seed/shrink detail is preserved.\n  const run = (axiom: string, prop: Parameters<typeof fc.assert>[0]): void => {\n    try {\n      fc.assert(prop, { numRuns });\n    } catch (e) {\n      throw new Error(`${axiom}: ${e instanceof Error ? e.message : String(e)}`);\n    }\n  };\n\n  // A1 — plain-object identity (no class instance).\n  {\n    const { unit, teardown } = fresh();\n    const proto = Object.getPrototypeOf(unit);\n    if (proto !== Object.prototype && proto !== null) {\n      throw new Error('A1: state unit is not a plain object (has a class prototype)');\n    }\n    unit.dispose();\n    teardown();\n  }\n\n  // X1 — no raw *origin* Subject on the public surface (expose `.asObservable()`).\n  // Flag only origin Subjects — `new Subject` / `new BehaviorSubject`, the unit's own\n  // state, where `.source` is undefined. Derived `AnonymousSubject`s from `Subject.lift`\n  // (`shareReplay().pipe(...)`) carry a `.source` and are inert sinks (`.next()` does\n  // nothing useful) — idiomatic, not the forgotten-internal-Subject smell — so exclude them.\n  {\n    const { unit, teardown } = fresh();\n    for (const [key, value] of Object.entries(unit)) {\n      if (value instanceof Subject && (value as { source?: unknown }).source === undefined) {\n        throw new Error(`X1: public field \"${key}\" is a raw Subject — expose it via .asObservable()`);\n      }\n    }\n    unit.dispose();\n    teardown();\n  }\n\n  // A7-passed — disposing the unit must NOT dispose an injected dependency.\n  {\n    const { unit, passedIn, teardown } = fresh();\n    unit.dispose();\n    passedIn.forEach((probe, i) => {\n      if (probe.disposeCount > 0) {\n        throw new Error(`A7-passed: the unit disposed injected dependency #${i} (it doesn't own it)`);\n      }\n    });\n    teardown();\n  }\n\n  // A5 — dispose() idempotent & total: n calls never throw; injected deps stay untouched.\n  run('A5', fc.property(fc.integer({ min: 1, max: 20 }), (n) => {\n    const { unit, passedIn, teardown } = fresh();\n    for (let i = 0; i < n; i++) unit.dispose();\n    passedIn.forEach((probe, i) => {\n      if (probe.disposeCount > 0) {\n        throw new Error(`injected dependency #${i} disposed under ${n} dispose() calls`);\n      }\n    });\n    teardown();\n  }));\n\n  // A6 — k pre-dispose subscribers on each owned surface all see `complete` on dispose.\n  if (spec.surfaces) {\n    const surfaces = spec.surfaces;\n    run('A6', fc.property(fc.integer({ min: 1, max: 10 }), (k) => {\n      const { unit, teardown } = fresh();\n      const completed: boolean[] = [];\n      const subs = surfaces(unit).flatMap((o) =>\n        Array.from({ length: k }, () => {\n          const idx = completed.push(false) - 1;\n          return o.subscribe({ complete: () => { completed[idx] = true; } });\n        }),\n      );\n      unit.dispose();\n      completed.forEach((seen, idx) => {\n        if (!seen) throw new Error(`a subscriber did not see complete on dispose (k=${k}, sub #${idx})`);\n      });\n      subs.forEach((s) => s.unsubscribe());\n      teardown();\n    }));\n  }\n\n  // A5b — post-dispose inertness: every public method is a no-op (no throw) after dispose.\n  if (spec.invocations) {\n    const invocations = spec.invocations;\n    run('A5b', fc.property(fc.array(fc.nat(), { maxLength: 12 }), (seq) => {\n      const { unit, teardown } = fresh();\n      const callers = invocations(unit);\n      unit.dispose();\n      for (const raw of seq) {\n        if (callers.length === 0) break;\n        swallowAsync(callers[raw % callers.length]());\n      }\n      teardown();\n    }));\n  }\n\n  // X3-runtime — instance isolation: driving instance A never moves instance B's surfaces.\n  if (spec.surfaces && spec.invocations) {\n    const surfaces = spec.surfaces;\n    const invocations = spec.invocations;\n    run('X3-runtime', fc.property(fc.array(fc.nat(), { minLength: 1, maxLength: 8 }), (seq) => {\n      const a = fresh();\n      const b = fresh();\n      const bSurfaces = surfaces(b.unit);\n      const bCounts = bSurfaces.map(() => 0);\n      const bSubs = bSurfaces.map((o, i) => o.subscribe(() => { bCounts[i] += 1; }));\n      const baseline = bCounts.slice(); // initial replay captured synchronously above\n      const aCallers = invocations(a.unit);\n      for (const raw of seq) {\n        if (aCallers.length === 0) break;\n        swallowAsync(aCallers[raw % aCallers.length]());\n      }\n      bCounts.forEach((count, i) => {\n        if (count !== baseline[i]) {\n          throw new Error(`driving instance A perturbed instance B's surface #${i}`);\n        }\n      });\n      bSubs.forEach((s) => s.unsubscribe());\n      a.unit.dispose();\n      b.unit.dispose();\n      a.teardown();\n      b.teardown();\n    }));\n  }\n\n  // A7-owned — internally-constructed children are disposed (their surfaces complete) on outer dispose.\n  if (spec.ownedChildSurfaces) {\n    const { unit, teardown } = fresh();\n    const childSurfaces = spec.ownedChildSurfaces(unit);\n    const completed = childSurfaces.map(() => false);\n    const subs = childSurfaces.map((o, i) => o.subscribe({ complete: () => { completed[i] = true; } }));\n    unit.dispose();\n    completed.forEach((seen, i) => {\n      if (!seen) throw new Error(`A7-owned: owned child surface #${i} did not complete on outer dispose`);\n    });\n    subs.forEach((s) => s.unsubscribe());\n    teardown();\n  }\n\n  // Post-dispose surface inertness: a NEW subscription after dispose completes with no `next`.\n  if (spec.surfaces) {\n    const { unit, teardown } = fresh();\n    unit.dispose();\n    spec.surfaces(unit).forEach((o, i) => {\n      let nexts = 0;\n      let done = false;\n      o.subscribe({ next: () => { nexts += 1; }, complete: () => { done = true; } }).unsubscribe();\n      if (nexts > 0) throw new Error(`A5b/inert: owned surface #${i} emitted a value after dispose`);\n      if (!done) throw new Error(`A5b/inert: owned surface #${i} did not complete after dispose`);\n    });\n    teardown();\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/core",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Core types and domain logic for Semiont - Resource, Annotation, and Graph models",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +15,11 @@
       "types": "./dist/config/node-config-loader.d.ts",
       "import": "./dist/config/node-config-loader.js",
       "default": "./dist/config/node-config-loader.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
     }
   },
   "engines": {
@@ -74,6 +79,14 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "rxjs": "^7.8.1",
-    "smol-toml": "^1.6.1"
+    "smol-toml": "^1.7.0"
+  },
+  "peerDependencies": {
+    "fast-check": "^4.8.0"
+  },
+  "peerDependenciesMeta": {
+    "fast-check": {
+      "optional": true
+    }
   }
 }