feat(client-ts): port the client to Effect

[srid]

The TypeScript client now speaks Effect. Its spawning verbs hand back
Effect.Effect<Reading, OsfactsClientError> instead of a Promise, its kind
string union becomes three Schema.TaggedErrorClasses, and the two places where
the obvious Effect-shaped move would have been wrong keep their old shape — with
the reason written into the source rather than left to be rediscovered.

Part of the follow-up campaign from juspay/kolu#2101 (comment 5182758828). This
is the upstream half; the downstream adaptations were folded into the main PRs and are green there: juspay/kolu#2101 (adopts the client, flips the supervisor seams; pins this branch) and srid/drishti#132 (adapts proc.ts). Both now ride effect 4.0.0-beta.103, matching this PR. Merge order: this PR merges first, kolu#2101 then re-pins its npins osfacts entry to the merge commit before merging, and the consumer PRs follow.

What changed

The spawning verbs return Effects. snapshotSubtree, snapshotHost,
snapshotPids, processIdentityAsync, socketHolders, host, and the function
osfactsSocketHolders returns each hand back
Effect.Effect<Success, OsfactsClientError>. Nothing spawns until the caller
runs it, every declared failure is in the type, and an interrupted fiber kills
the in-flight child instead of leaving it to run out its five-second deadline
against a host nobody is reading. socketHolders' empty-path guard is now a
typed FAILURE rather than a synchronous throw, which dissolves the old
"async, so this one guard rejects like the others" note — the return type says
it now.

The empty-pid-list short-circuits are preserved and pinned: snapshotSubtree
and snapshotPids over an empty array answer emptySnapshotReading() without
spawning anything.

Three tagged error classes. OsfactsSpawnError, OsfactsVersionError, and
OsfactsParseError replace OsfactsClientError's kind field, one-to-one at
every raise site. OsfactsClientError survives as the union TYPE, with
isOsfactsClientError as its guard. They are still Errors, which is what lets
the sync island go on throwing them.

exactOptionalPropertyTypes is on. It makes HostReading's four
genuinely-absent fields machine-checked, and forces the two deliberately
present-and-undefined shapes — ListenerRow.uid and SocketHolder.command —
to say so in their types (?: T | undefined, one comment each). No output shape
moved: the four optional HostReading fields, the present-undefined uid, the
threads / frequencyMhz null forms, and SocketOccupancy's non-empty-tuple
held arm with its two literal detail strings are byte-identical.

One runtime dependency. effect at 4.0.0-beta.102 — the exact version both
consumers already pin. The two-line pnpm-workspace.yaml beside it declines
msgpackr's optional native accelerator, which arrives through effect's own
graph and which pnpm 11 otherwise refuses to guess about — it fails an install
that has no recorded decision for a build script. (The nested file is inert in a
consumer that grafts this directory as a workspace member; verified.)

Two decisions, written down rather than assumed

The sync island stays sync. snapshotPidsSync, processIdentity, and
processIdentityFromEnv remain synchronous over execFileSync and keep
throwing. Two structural reasons, both now in client.ts's module header: the
consumers' single-instance gate (acquirePidGate in @kolu/surface-daemon,
shared by kolu's three daemons and drishti) is a deliberately synchronous claim
path, and async there reorders the gate against the boot side effects it guards;
and execFileSync cannot be interrupted, so an Effect wrapper would add the
ceremony of a fiber while advertising a capability the call does not have.

The spawn is execFile under Effect.callback, not a platform command
layer. The reason is written at the spawn site:

1. childFailure.ts classifies a child's fate by reading NODE's error shapes —
   .code / .status / .stderr / .signal. A command layer reshapes a
   failure into its own vocabulary, and the exit-2 refusal and the
   signal-truncation rule are one-line rules whose failure mode is a silently
   discarded (or silently accepted) document. They would go inert without a
   single test turning red.
2. The deadline that matters is the CHILD's. CHILD_OPTIONS.timeout with
   killSignal: "SIGKILL" is kernel-enforced against a wedged binary; an Effect
   timeout interrupts the FIBER, which is a fact about the caller.
   OSFACTS_COMMAND_TIMEOUT_MS therefore means exactly what it meant.
3. Zero new platform deps keeps drishti — which runs this client under Bun —
   safe.

The callback reassembles node's error into exactly the shape
promisify(execFile) used to hand over, so the classifier still sees ONE shape
from both twins. That invariant ("the only thing that may differ is HOW the
child is invoked") is restated in childFailure.ts's header.

Tests

39 → 41, all green on the CI line (nix develop .#client-ts -c …,
pnpm install --frozen-lockfile && pnpm run typecheck && pnpm run test:unit).
Every existing assertion that pins bytes, shapes, or messages survives verbatim;
only the call shapes moved (Effect verbs run through Effect.runPromise).

Two new pins, each falsifiable:

• Interruption kills the child. A stub that exec sleep 30s after reporting
  its pid; the fiber is interrupted and the pid is watched until the kernel says
  it is gone. Reverting the finalizer turns it red (verified).
• An empty pid scope spawns nothing. Asked with "" as the binary path —
  which assertBinPath refuses — so a reading coming back at all is the proof.

The bad-row corpora now assert the tagged class rather than the old base class,
and the version test asserts OsfactsVersionError plus the guard. The
childFailure pins on exit-1-document / exit-2-refusal / signal-refusal are
untouched and still green; the async path's exit-1 and exit-2 pins are what
prove the reassembled stdio reaches the classifier.

Consumer impact

Both consumers adapt at their pin bumps; neither is broken today, because both
reach this client through a pinned graft.

• kolu grafts client-ts as the workspace member osfacts-client from its
  npins osfacts pin. A downstream kolu PR adapting the call sites (and bumping
  the pin) is next in the campaign.
• drishti reaches the same bytes through kolu's overlay and runs under Bun —
  which is one of the three reasons the spawn stays on node's execFile.

The delta a consumer has to absorb: the seven spawning verbs return Effects;
OsfactsClientError is a union type rather than a class, so new OsfactsClientError(...) and err.kind become the three classes and
isOsfactsClientError; everything else — the sync island, the parsers, the
folds, bakedOsFactsBin, every row and reading type, and every constant — is
unchanged.

🤖 Generated with Claude Code

[srid]

Campaign disposition — upstream half (re-walked at final HEAD 86091cf6)

Per the definition of done in juspay/kolu#2101 (comment):

• The ~9 Promise verbs → Effect: all six async verbs plus osfactsSocketHolders' inner function now return Effect.Effect<_, OsfactsClientError>. Empty-scope short-circuits still never spawn (pinned); socketHolders' empty-path guard became a typed failure (the async-so-it-rejects design note dissolved, and says so).
• Error vocabulary: OsfactsSpawnError / OsfactsVersionError / OsfactsParseError (Schema.TaggedErrorClass), union alias OsfactsClientError, runtime guard isOsfactsClientError. Every old kind raise site maps 1:1.
• The sync twins — decided, not drifted: snapshotPidsSync / processIdentity / processIdentityFromEnv stay raw-sync, reason written in the module header — the consumers' single-instance gate claim (acquirePidGate, shared by kolu's three daemons and drishti) is a deliberately synchronous claim path, and execFileSync cannot be interrupted, so an Effect wrapper adds ceremony without capability.
• Spawn mechanism — decided deviation from the Command-layer suggestion, reason written at the site: the spawns stay on execFile under an Effect wrapper because (a) childFailure's twin-symmetry invariant and its exit-2-refusal / signal-truncation discrimination read Node execFile error shapes, which a Command layer would reshape; (b) the child-level timeout + SIGKILL must stay kernel-enforced — an Effect timeout interrupts the fiber, not a wedged child; (c) zero platform deps keeps the Bun consumer (drishti) safe. Effect interruption does kill the in-flight child, and that is falsified (reverting the finalizer turns the test red).
• No new unbounded wait/retry/fallback: none added; OSFACTS_COMMAND_TIMEOUT_MS semantics unchanged.
• The pin spelling: the package declares the literal "effect": "4.0.0-beta.102" (catalog spellings don't resolve outside kolu's workspace); kolu's effectPin gate learned the site in the downstream PR.
• Bonus: exactOptionalPropertyTypes: true is ON in client-ts's own tsconfig, making the exact-optional HostReading spelling machine-checked; the two deliberate present-undefined shapes (ListenerRow.uid, SocketHolder.command) are spelled ?: T | undefined with their one-line reasons.
• Receipts: 39 → 41 tests, all byte/shape/message assertions surviving verbatim; CI 12/12 green both OSes (client-ts, hermetic, live-oracle, CodeQL).

Merge — parked, with the ordering: juspay/kolu#2101 merges first, then this PR, then kolu's adoption PR (juspay/kolu#2103) re-pins osfacts to this PR's merge commit. Merging is the maintainer's act; everything on this side is complete and green.

Downstream: juspay/kolu#2103 (adoption, green) · srid/drishti#133 (pair, green).

🤖 Generated with Claude Code