prod-ready: fix condition bug, async support, input validation, updated CI

[twinksanderson]

1. Condition state mutation was broken

Problem: The condition value was stored as this.True — a public property initialized to the boolean true. The guard (!!this.True) ? this.True = condition : null caused any subsequent .condition() call after the first truthy value to be silently ignored. Calling .condition(false).condition(true) would not update the condition. The public property also exposed internal state to accidental mutation by external code.

Fix: Renamed to this._condition. Replaced the guard with this._condition = Boolean(condition) — last call wins, always.

---

2. Promise return values from handlers were discarded

Problem: Handlers could return Promises, but execute() never awaited them — they would fire and be forgotten, with no way to know if they resolved or rejected.

Fix: execute() is now async. All active handlers are collected and awaited concurrently via Promise.all, with rejection propagation intact.

---

3. Invalid handler arguments failed at the wrong time

Problem: Passing a non-function to onTrue() or onFalse() produced no error at the call site. The failure surfaced later at .execute() time with a confusing message, making the root cause hard to trace.

Fix: Both methods now validate the argument immediately and throw TypeError with a descriptive message pointing to the offending call.

---

4. No structured error handling path

Problem: Any exception thrown inside a handler propagated directly to the caller with no interception point. There was no way to handle errors gracefully without wrapping every .execute() call in try/catch.

Fix: Added .onError(fn). When set, errors are routed to the handler instead of being re-thrown. Execution completes normally from the caller's perspective.

---

5. No execution timeout

Problem: A slow or hanging handler would block indefinitely. There was no mechanism to enforce a time bound on execution.

Fix: .timeout(ms) wraps the execution in a Promise.race against a rejection timer. On breach, throws TimeoutError — a subclass of ConditionallyExecuteError — with the configured duration in the message.

---

6. No retry support

Problem: Transient handler failures required manual retry logic at the call site, duplicated across every use.

Fix: .retry(n, { backoff }) retries the handler invocation up to n times. Supports 'none', 'linear' (n × 100ms), and 'exponential' (2ⁿ × 100ms) backoff strategies.

---

7. No composability layer

Problem: Cross-cutting concerns — logging, tracing, feature flags, auth checks — had to be embedded directly into handlers or duplicated across call sites. There was no interception layer.

Fix: .use(middleware) installs an Express-style middleware function receiving (ctx, next). Middleware can inspect or mutate ctx.condition, ctx.branch, and ctx.handlers before and after execution. Middleware composes in registration order.

---

8. Condition logic was always inline

Problem: Condition functions could not be named, shared, or tested in isolation. Every use site required an inline expression or a manually imported function.

Fix: ConditionallyExecute.register(name, fn) stores named condition functions in a static Map. Passing a string to .condition('name') resolves it from the registry at execute time. unregister() and clearRegistry() allow cleanup in tests.

---

9. No synchronous execution path

Problem: Synchronous use cases paid the full async overhead of Promise.all even when no async work was involved.

Fix: executeSync() executes handlers in a tight for-loop with no Promise construction. Measured overhead vs. native if:

Variant	Time	Overhead
Native if	~0.07 µs	1×
executeSync()	~0.09 µs	~1.4×
execute()	~0.41 µs	~5×

---

10. No distributed execution primitives

Problem: The library had no extensibility story for running handlers across multiple nodes or enforcing agreement before proceeding. The plugin system added in this PR enables this, but no plugins existed in the original codebase.

Fix: Two plugins added under plugins/:

MultiThreadedPlugin — in-process consensus via worker_threads. Spins up N worker threads, each votes on the condition independently, coordinator proceeds only when majority agrees.

GrpcConsensusPlugin — real distributed execution over gRPC (HTTP/2 + Protobuf). The coordinator fans out Execute() RPC calls to all registered node addresses simultaneously. Each node runs its locally-registered handler and reports back. If fewer than quorum nodes confirm successful execution, a QuorumError is thrown containing .reached, .required, .total, and .nodeResults[] for diagnostics.

const n1 = await startGrpcNode(50051, { deploy: () => { /* node 1 work */ } });
const n2 = await startGrpcNode(50052, { deploy: () => { /* node 2 work */ } });
const n3 = await startGrpcNode(50053, { deploy: () => { /* node 3 work */ } });

await new ConditionallyExecute()
  .use(GrpcConsensusPlugin({
    nodes: ['localhost:50051', 'localhost:50052', 'localhost:50053'],
    handlerName: 'deploy',
    quorum: 2,
  }))
  .condition(isReadyForDeploy)
  .onTrue(() => console.log('Quorum reached. Proceeding.'))
  .execute();

await Promise.all([n1.close(), n2.close(), n3.close()]);

---

11. Test coverage was insufficient to detect regressions

Problem: The original suite had 6 tests covering the happy path only. No async coverage, no edge case coverage, no way to detect silent regressions in condition evaluation or branch selection.

Fix: 61 tests across three suites, run in parallel via node test-parallel.js:

Suite	Tests
Core (test.js)	47
MultiThreadedPlugin (test-multi-threaded.js)	8
GrpcConsensusPlugin (test-grpc.js)	6

Stryker mutation testing applied to index.js: 89.57% mutation score (143 killed / 3 timeout / 15 survived / 2 no-coverage). Configured thresholds: high ≥ 80%, low ≥ 60%, break < 50%.

---

12. CI configuration was outdated

Problem: Workflow used actions/checkout@v2 and actions/setup-node@v1 (both deprecated). Test matrix included Node 16 (EOL since September 2023). No linting step.

Fix: Updated to actions/checkout@v4 and actions/setup-node@v4 with npm cache. Removed Node 16 from the matrix. Added engines: { node: ">=18" } to package.json. Added ESLint with a lint step in CI.