Hyperlink Factories

The tag is the contract; the layer is the runtime

srcexamples

A HyperService splits cleanly in two. The tag carries the wire contract — the payload / success / error schemas — and nothing else; it is the wire SSOT and the thing a client (even a browser) imports. The layer carries the runtime — the effect worker, polling, autoStart. Never cross them: schemas never move into layer config (that breaks the wire SSOT and RPC safety), and the worker never moves onto the tag (that drags the engine into the light contract).

// contract — the wire schema, passed positionally
class Mail extends WorkPool.Tag<Mail>()("@acme/Mail", Job) {}

// runtime — in the layer
WorkPool.layer(Mail, { effect: handleJob, autoStart: true })

// ❌ bad — wire schema in the layer (no longer SSOT; client and server can disagree)
WorkPool.layer(Mail, { payload: Job, effect: handleJob })

Pass tag schemas positionally when you can

srcexamples

When a tag needs only its wire schema, pass it positionally — its the clearest form. Reach for the { payload, success, error } config object only when the tag carries more than one wire slot, or extra configuration. WorkPool always takes the object, because its lane structure (laneCount, namedLanes) lives on the tag alongside the payload.

// ✅ single schema → positional
class Mail extends WorkPool.Tag<Mail>()("@acme/Mail", Job) {}

// config object — more than one wire slot
class Ingest extends Daemon.Tag<Ingest>()("app/Ingest", { success: Report, error: PullFailed }) {}

// untyped WorkPool — always the object; lane config rides on the tag
class Jobs extends WorkPool.priority<Jobs>()("@acme/Jobs", {
  payload: Job,
  laneCount: 4,
  namedLanes: { interactive: 0, standard: 2, batch: 3 },
}) {}

Compose behaviour with piped combinators, not constructor flags

srcexamples

Optional behaviour — scheduling, readiness, distribution — is piped onto the HyperService, never passed as a constructor flag. Each combinator is composable and independent, so the base stays small and you add only what you need (this is Principles → Dont fight the framework in the concrete).

// base tag runs immediately; add behaviour by piping
class Ingest extends Daemon.Tag<Ingest>()("app/Ingest", { success: Report })
  .pipe(
    Daemon.schedule([Daemon.window(openAt, closeAt)]),  // when it may run
    Hyperlink.withReadiness(isWarm),                        // when it counts as ready
  ) {}

Data-last tag duals must not constrain Svc-bearing tag unions

src

A combinator meant for class X extends Tag<X>()(…).pipe(combinator(…)) must not constrain its data-last T as HyperlinkTag | NodeBoundTag. Those types carry a default Svc = ServiceOf<S, Self>; stock tsc expands that while Self is still being declared and hits TS2589 (tsgo often stays quiet — gate with both). Constrain T with a shallow brand that only needs the spec (the package uses PipeableTag = { readonly [specSym]: FlatSpec } for withReadiness / distributed). T is still inferred as the concrete tag, so (tag: T) => T preserves it.

// ✅ shallow — PipeableTag / equivalent
<T extends PipeableTag>(…): (tag: T) => T

// ❌ deep — reopens TS2589 on node-bound class .pipe under stock tsc
<T extends HyperlinkTag<any, any, any> | NodeBoundTag<any, any, any, any>>(…): (tag: T) => T

Polling and schedule are different questions — never conflate

srcexamples

Two independent axes govern a running Daemon:

• The schedule answers whether an instance should be running at all — it arms and disarms.

• Polling answers how often an already-armed instance repeats its tick.

A base Daemon.Tag is always armed and runs immediately; .pipe(Daemon.schedule([...])) gates it to windows, and seeding Daemon.schedule([]) starts it disarmed. Polling (Polling.spaced, …) is set separately in the layer. Dont reach for one to do the others job.

Daemon.layer(Ingest, {
  effect: pull,
  polling: Polling.spaced(Duration.seconds(30)),  // cadence — not "should it run"
})

The default queue stays lean; custom lanes are a separate type

srcexamples

The default WorkPool is exactly three lanes — high / normal / low — and stays that way. When you need a different lane count or a weighted take, that is WorkPool, a separate type, not a wider-shaped default queue. Its scheduling code is loaded only when selected (see Build & browser safety), so the default queue never carries the weight of lane machinery it doesnt use.

// default — three fixed lanes; schema positional
class Mail extends WorkPool.Tag<Mail>()("@acme/Mail", Job) {}

// custom — N named lanes, a distinct type; lane config forces the object form
class Jobs extends WorkPool.priority<Jobs>()("@acme/Jobs", {
  payload: Job,
  laneCount: 4,
  namedLanes: { interactive: 0, standard: 2, batch: 3 },
}) {}

Two related facts live elsewhere: the .Tag class-extends form → Public types; durability is presence-driven (serviceOption) → Storage.

The same code runs local or remote

srcexamples

A HyperService is driven by the same yield* Tag whether it is in-process or served over RPC — only the layer you provide differs. Never branch on local-vs-remote in a consumer. A field either behaves identically in both, or its divergence surfaces as a type or dependency error — never a silent same-looking-but-different (see Principles → Fail loudly).

Use the locked serve vocabulary

srcexamples

Four verbs, one axis — how a HyperService is made available:

• layer — local only.

• serve — local and served over RPC (the default for a node).

• serveRemote — served only, not runnable in-process (plain impl; R via handler requirements).

• client — a remote handle to a served HyperService.

Toolkit engines that build a Hyperlink Driver mount with Hyperlink.serveRemoteDriver (preserves the drivers worker R). Apps call Gate.serveRemote / Daemon.serveRemote / WorkPool.serveRemote — not the Driver helper — unless they are assembling a custom engine.

Transport is a separate line: httpServer / http / connect. Http appears only there — the core verbs stay transport-agnostic, so the same HyperService can be served over any protocol.

Serve / listen / *Server preserve open R (and E)

srcexamples

Every HyperService may have requirements — including other HyperServices. Serve layers, Node.listen / unix / http / ws, and httpServer / wsServer / ipcServer must keep those channels open so callers Layer.provide dependencies outside. Closing R at the server boundary is rejected. Shared deps: provide once onto the server. Mutually exclusive deps of the same tag: Layer.provide onto each serve layer (see Managing Layers).

Serve through the engines spec-checked form, never a bare literal

srcexamples

Serve a HyperService through its engine form (WorkPool.serve, Daemon.serve) — these mount the handlers and keep the worker or tick alive. Hyperlink.serve only mounts handlers; using it for a WorkPool leaves the worker dead. Never hand-write a { tag, impl } literal: it types as Record<string, unknown> and silently swallows typos — the engine form spec-checks the impl against the tag.

Put serve layers in the listen / *Server list; provide deps outside

srcexamples

Node.http([...serveLayers], 3000) / Node.ws / httpServer / wsServer union each layers requirement R, like Layer.mergeAll. Pass serves as the list argument (not a later bare Layer.provide of a serve onto something that doesnt demand it — that prunes). Discharge deps with Layer.provide / provideMerge after the server (shared) or on each serve layer (isolated). Prefer Node.http / Node.ws (nameless + port / ":port" / url shorthand) over httpServer / wsServer when the battery localhost bind is enough.

// ✅ good — serves in the list; shared dep outside
const live = Node.http([
  Hyperlink.serve(Counter, counterImpl),
  Hyperlink.serve(Mail, mailImpl),
], 3000).pipe(Layer.provide(Db.layer))

// ❌ bad — bare provide of a serve layer onto a program that doesn't require it prunes the mount
program.pipe(Layer.provide(Hyperlink.serve(Counter, counterImpl)))

Declare dependencies in the worker; provide at the serve boundary

srcexamples

A worker or tick body declares its dependencies with yield* Tag — it never Effect.provides them inline. Provide whole-service deps once, at the serve/layer boundary, so strictEffectProvide stays clean and the same body works local or served. Do not hoist a sub-effect-scoped dep to serve — that widens R for the whole body; keep an app-local scoping combinator beside the handler service — do not look for a package locally helper.

One instance, one materialization

srcexamples

A HyperService is a single instance. Its local use and its served handlers share one materialization — serving must not re-run the impl generator. Compose extra behaviour as post-construction combinators (withReadiness, distributed) piped onto the HyperService, not as re-materializations or baked constructor options (see Principles → Dont fight the framework).

One HyperService = N node-local instances

srcexamples

One class. Each node runs its own instance; peers gives you the per-node handles.

// one tag — not one-per-node
class Prices extends WorkPool.Tag<Prices>()("app/Prices", Job) {}

const perNode = yield* Hyperlink.peers(Prices)
// { "node-a": handle, "node-b": handle, … } — keyed by node

Readiness is per-node and local — never a cross-node hop

srcexamples

Readiness derives from a HyperServices own status and rolls up into that nodes /health. Reaching into a peer to decide your own readiness cascades one nodes failure into its neighbours.

// ✅ derived from this instance's own status
class Prices extends WorkPool.Tag<Prices>()("app/Prices", Job)
  .pipe(Hyperlink.withReadiness((svc) =>
    Effect.map(svc.status.get, (s) => s.phase === "running"),
  )) {}

// ❌ readiness that hops to peers — a down neighbour drags this node down
Hyperlink.withReadiness(() => Effect.map(Hyperlink.peers(Prices), allReady))

For a stadium-board view of the pack (Reachable / Unreachable), use FleetHealth — a separate glass; do not stuff the fold into withReadiness.

Fold over leaf fields; fleet views stay out of the fan-out

srcexamples

peers fans out to leaf handles. A fleet-marked field is already a combined view, so its excluded from the fan-out — folding over it would re-aggregate an aggregate. Fold leaves, and add your own node explicitly.

// a combined field is marked fleet → not re-fanned-out by peers
class Prices extends WorkPool.Tag<Prices>()("app/Prices", Job) {
  static readonly totalDepth = Hyperlink.fleet(Hyperlink.effect(Schema.Number))
}

// fold over leaves, self included explicitly (never silently)
const depthByNode = { ...(yield* Hyperlink.peers(Prices)), [self.key]: local }

Peers are lazy and degrade to a partial mesh

srcexamples

peersLayer never connects eagerly. No url ⇒ skip that peer, never throw. Urls come from the node or Config — never frozen into the contract.

Hyperlink.peersLayer(Prices, self, {
  nodes,
  url: (node) => Config.option(Config.string(`${node.key}_URL`)),
  //   Config.option → undefined skips a peer (partial mesh)
  //   a raw ConfigError fails the build loudly (misconfiguration)
})