@smthrs/sync 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/BranchShare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchShare.js","sourceRoot":"","sources":["../../src/BranchShare.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Share capabilities: the authorization boundary of a shared branch.\n *\n * A share link carries a capability, not a session. The capability names\n * exactly one branch, one access level, and one expiry, and it is signed, so\n * the holder cannot widen it. Every branch operation authorizes through\n * `verify`, which is therefore the single place cross-branch access and\n * expired links are refused.\n *\n * The signature is HMAC-SHA-256 over a length-prefixed encoding of the claims,\n * led by a scheme label. Length prefixes matter: without them a branch id\n * ending in the separator could be re-cut into a different, still-validly-\n * signed claim set. The label matters for the same reason across schemes: a\n * branch capability can never verify as a workspace capability even if one\n * secret is misconfigured into both authorities. Web Crypto is used directly\n * so the same module runs in the browser and on node.\n *\n * A `kid` inside the claims names the key that signed them, so a branch secret\n * rotates the way the workspace secret already did: the new key signs, the\n * retired key stays in the verification keyring, and the share links already\n * out keep working until they expire.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Config from \"effect/Config\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport { Access, BranchId, ShareCapability, ShareClaims } from \"./BranchProtocol.ts\"\nimport * as Admission from \"./internal/Admission.ts\"\nimport * as shareSigner from \"./internal/ShareSigner.ts\"\nimport type { SyncError } from \"./SyncError.ts\"\n\n/**\n * The branch and access one authorization request needs.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface AuthorizeRequest {\n  readonly branchId: BranchId\n  readonly access: Access\n}\n\n/**\n * What a freshly minted capability grants.\n *\n * @category models\n * @since 0.1.0\n */\nexport const MintRequest = Schema.Struct({\n  branchId: BranchId,\n  capabilityId: Schema.NonEmptyString,\n  access: Access,\n  ttlMs: Schema.Int.check(Schema.isGreaterThan(0)),\n  /** Absolute expiry ceiling for a capability delegated from a parent. */\n  maxExpiresAtMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))\n})\n\n/**\n * What a freshly minted capability grants.\n *\n * @category models\n * @since 0.1.0\n */\nexport type MintRequest = typeof MintRequest.Type\n\n/**\n * Share capability operations.\n *\n * `mint` fails with a `SyncError` when the Web Crypto signing operation\n * rejects or the absolute expiry ceiling has elapsed; `verify` fails with a\n * `SyncError` when signing rejects or the capability is refused.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly mint: (request: MintRequest) => Effect.Effect<ShareCapability, SyncError>\n  readonly verify: (\n    capability: ShareCapability,\n    request: AuthorizeRequest\n  ) => Effect.Effect<ShareClaims, SyncError>\n}\n\n/**\n * The branch share-capability authority.\n *\n * @category services\n * @since 0.1.0\n */\nexport class BranchShare extends Context.Service<BranchShare, Service>()(\"@smthrs/sync/BranchShare\") {}\n\nconst denied = shareSigner.unauthorized\n\n/**\n * Constructs a share authority that mints nothing and trusts nothing.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides: Partial<Service> = {}): Service =>\n  BranchShare.of({\n    // Both operations FAIL. `mint` used to die, which contradicted its own\n    // declared `Effect<ShareCapability, SyncError>` and left a consumer\n    // wired to this authority unable to tell \"sharing is off\" from a bug.\n    mint: () => Effect.fail(denied(\"Branch sharing is unavailable\")),\n    verify: () => Effect.fail(denied(\"Branch sharing is unavailable\")),\n    ...overrides\n  })\n\n/**\n * Provides a share authority that refuses every capability.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<BranchShare> = Layer.succeed(BranchShare, makeNoop())\n\n/**\n * Domain separation: the label leads the signed encoding, so a branch\n * signature can never be replayed as a workspace signature (or any later\n * scheme's) under a shared secret. `WorkspaceShare` has always led with its\n * own label; a one-sided label protects one direction, and the branch side is\n * the one anonymous share-link holders reach.\n */\nconst schemeLabel = \"@smthrs/sync/BranchShare/v2\"\n\n/** Length-prefixed so no two distinct claim sets share an encoding. */\nconst canonical = (claims: ShareClaims): string =>\n  shareSigner.lengthPrefixed([\n    schemeLabel,\n    claims.kid,\n    claims.branchId,\n    claims.capabilityId,\n    claims.access,\n    String(claims.issuedAtMs),\n    String(claims.expiresAtMs)\n  ])\n\n/**\n * The claim fields, copied out of the capability the caller owns.\n *\n * `Schema.Class` instances are not frozen, and `verify` awaits Web Crypto\n * between signing the claims and authorizing them. Reading the caller's object\n * again after the await let an in-process holder of the same instance widen\n * `access` — or move `expiresAtMs` — between the signature that was checked\n * and the checks that follow it.\n */\nconst snapshot = (claims: ShareClaims): ShareClaims =>\n  new ShareClaims({\n    kid: claims.kid,\n    branchId: claims.branchId,\n    capabilityId: claims.capabilityId,\n    access: claims.access,\n    issuedAtMs: claims.issuedAtMs,\n    expiresAtMs: claims.expiresAtMs\n  })\n\n/**\n * One named signing key. The secret is `Redacted` so a keyring never renders\n * it into logs or inspection output.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Key = shareSigner.Key\n\n/**\n * A keyring: the key that signs new capabilities plus every key still\n * accepted for verification. Rotation adds a new active key and keeps the\n * retired one in `keys` until its outstanding links expire, so rotating the\n * branch secret no longer breaks every share link that is already out.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Keyring = shareSigner.Keyring\n\n/**\n * Constructs the HMAC-SHA-256 share authority over a keyring.\n *\n * Every key is imported up front, so a misconfigured keyring — an unknown\n * active kid, a duplicate kid, or a key Web Crypto refuses — fails at\n * construction rather than at the first request. Secrets enter as `Redacted`\n * values: an authority never holds a plain string that a log, a span, or an\n * inspection of the keyring could render.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeHmac = (keyring: Keyring): Effect.Effect<Service, SyncError> =>\n  Effect.map(\n    shareSigner.importKeyring(keyring, \"branch\"),\n    (ring) => {\n      const mint = Effect.fn(\"BranchShare.mint\")(function*(request: MintRequest) {\n        // Decoded, not read: the declared parameter type admits an empty\n        // branch id, an empty capability id and a non-positive ttl that the\n        // schema forbids, and reading them straight into `new ShareClaims`\n        // turned a caller's bad argument into a defect out of an operation\n        // whose type promises a `SyncError`. A `ttlMs` of 0 minted an\n        // already-expired capability instead of being refused.\n        const admitted = yield* Admission.decode(MintRequest, request, \"invalid_request\")\n        yield* Effect.annotateCurrentSpan({ branchId: admitted.branchId, access: admitted.access })\n        const issuedAtMs = yield* Clock.currentTimeMillis\n        const maxExpiresAtMs = admitted.maxExpiresAtMs ?? Infinity\n        if (issuedAtMs >= maxExpiresAtMs) {\n          return yield* Effect.fail(denied(\"The share capability has expired\"))\n        }\n        const claims = new ShareClaims({\n          kid: ring.activeKid,\n          branchId: admitted.branchId,\n          capabilityId: admitted.capabilityId,\n          access: admitted.access,\n          issuedAtMs,\n          expiresAtMs: Math.min(issuedAtMs + admitted.ttlMs, maxExpiresAtMs)\n        })\n        return new ShareCapability({\n          claims,\n          signature: yield* shareSigner.signHmac(ring.active, canonical(claims))\n        })\n      })\n\n      const verify = Effect.fn(\"BranchShare.verify\")(function*(\n        capability: ShareCapability,\n        request: AuthorizeRequest\n      ) {\n        yield* Effect.annotateCurrentSpan({ branchId: request.branchId, access: request.access })\n        // Everything authorized below is read from these locals, never from\n        // the caller's objects, which may change while Web Crypto is awaited.\n        const claims = snapshot(capability.claims)\n        const signature = capability.signature\n        const branchId = request.branchId\n        const key = ring.verification.get(claims.kid)\n        if (key === undefined) {\n          return yield* Effect.fail(denied(\"The share capability names an unknown signing key\"))\n        }\n        yield* shareSigner.verifyClaims({\n          key,\n          canonical: canonical(claims),\n          signature,\n          expiresAtMs: claims.expiresAtMs,\n          granted: claims.access,\n          requested: request.access,\n          subject: \"The share capability\",\n          // The one check this authority adds, run after the signature so a\n          // forged claim set is refused as a bad signature and never reported\n          // back as the branch it names.\n          scope: claims.branchId === branchId\n            ? Effect.void\n            : Effect.fail(denied(`The share capability is scoped to branch ${claims.branchId}`))\n        })\n        return claims\n      })\n\n      return BranchShare.of({ mint, verify })\n    }\n  )\n\n/**\n * Provides the HMAC-SHA-256 share authority over a keyring.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerHmac = (keyring: Keyring): Layer.Layer<BranchShare, SyncError> =>\n  Layer.effect(BranchShare, makeHmac(keyring))\n\n/**\n * Provides the branch share authority from configuration: the secret from\n * `SMITHERS_SYNC_BRANCH_SECRET` (read as `Redacted`, never logged) and the key\n * name from `SMITHERS_SYNC_BRANCH_KEY_ID`, defaulting to `primary`. Rotation\n * beyond one configured key uses {@link layerHmac} with an explicit keyring.\n *\n * The names are the branch authority's own, not the workspace's: the scheme\n * label makes one secret in both authorities survivable, not advisable, and a\n * deployment that rotates one credential should not silently invalidate the\n * other's outstanding capabilities.\n *\n * There is deliberately no default secret: a deployment that configures\n * neither name fails to construct the authority, and every branch operation\n * stays closed.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerConfig: Layer.Layer<BranchShare, SyncError | Config.ConfigError> = Layer.effect(\n  BranchShare,\n  Effect.gen(function*() {\n    const secret = yield* Config.Redacted(\"SMITHERS_SYNC_BRANCH_SECRET\")\n    const kid = yield* Config.String(\"SMITHERS_SYNC_BRANCH_KEY_ID\").pipe(Config.withDefault(\"primary\"))\n    return yield* makeHmac({ activeKid: kid, keys: [{ kid, secret }] })\n  })\n)\n"]}

package/dist/esm/RunCatalog.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Workspace run enumeration for synchronization.
+ *
+ * @since 0.1.0
+ */
+import type { JournalEvent } from "@smthrs/journal";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { SyncError } from "./SyncError.ts";
+/**
+ * Workspace run enumeration operations.
+ *
+ * `list` is the AUTHORITATIVE run set and `changes` is only a low-latency
+ * wake: a subscriber that misses an announcement re-lists rather than losing
+ * state, and a subscriber whose covered set must stay accurate re-lists on a
+ * cadence of its own. Every implementation returns a fresh array from `list`,
+ * so a caller may retain and sort what it receives without disturbing another
+ * reader.
+ *
+ * `list` names each run AT MOST ONCE. Every implementation here deduplicates,
+ * and `SyncServer` deduplicates again at the seam rather than trusting a
+ * host's catalog, because both fan-out paths key a run's served position by
+ * run id: a run named twice is read twice from the same position and its
+ * entries are served twice.
+ *
+ * The catalog is supplied by the host rather than derived from the journal:
+ * `@smthrs/journal` has no workspace-wide list or watch contract, and
+ * `@smthrs/engine-store` owns the durable run set that {@link makePolling}
+ * reads.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly list: Effect.Effect<ReadonlyArray<JournalEvent.RunId>>;
+    readonly changes: Stream.Stream<JournalEvent.RunId>;
+}
+declare const RunCatalog_base: Context.ServiceClass<RunCatalog, "@smthrs/sync/RunCatalog", Service>;
+/**
+ * Host-provided workspace run catalog.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class RunCatalog extends RunCatalog_base {
+}
+/**
+ * Provides an immutable run catalog.
+ *
+ * `list` answers with a fresh array each time, matching {@link makeMemory} and
+ * {@link makePolling}. Handing every caller the same instance let one reader
+ * sort or splice the catalog in place for every other reader, which is a
+ * defect a `ReadonlyArray` type hides from TypeScript and not from JavaScript.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerStatic: (ids: ReadonlyArray<JournalEvent.RunId>) => Layer.Layer<RunCatalog>;
+/**
+ * Announcements a stalled {@link Service.changes} subscriber may fall behind
+ * by before the oldest are dropped.
+ *
+ * `changes` is a notification feed, not a log: a follower reads it to learn
+ * that the workspace gained a run and then reads the run itself. Retaining an
+ * unbounded backlog for a subscriber that has stopped pulling — a disconnected
+ * tab whose socket has not timed out yet, a follower blocked behind a slow
+ * consumer — is therefore pure cost, and the workspace's whole run history is
+ * the upper bound on it. A subscriber that falls further behind than this
+ * bound loses the oldest announcements; `list` still names every run, so a
+ * follower that reconnects or re-lists converges.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultChangesCapacity = 1024;
+/**
+ * Options for the in-memory run catalog.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MemoryOptions {
+    /**
+     * Announcements a stalled subscriber may fall behind by. Defaults to
+     * {@link defaultChangesCapacity}.
+     */
+    readonly changesCapacity?: number | undefined;
+}
+/**
+ * Constructs a mutable in-memory run catalog.
+ *
+ * A run is published exactly once, when it is first registered. The
+ * announcement feed slides: registering never waits on a stalled subscriber,
+ * and never grows the process on its behalf.
+ *
+ * Fails with `invalid_request` when `changesCapacity` is not a positive safe
+ * integer, rather than handing it to `PubSub.sliding` as a capacity.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeMemory: (options?: MemoryOptions) => Effect.Effect<{
+    readonly catalog: Service;
+    readonly register: (runId: JournalEvent.RunId) => Effect.Effect<void>;
+}, SyncError>;
+/**
+ * How often {@link makePolling} re-reads its source when the caller names no
+ * interval, in milliseconds.
+ *
+ * A workspace follower learns of a new run within one interval of it being
+ * created, and the read costs one bounded query per interval per composition,
+ * not per subscriber. A second is short enough that a run appears in a UI
+ * while the operator is still looking at the command that started it, and
+ * long enough that an idle workspace is close to free.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultPollIntervalMs = 1000;
+/**
+ * Options for the polling run catalog.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface PollingOptions<E, R> {
+    /**
+     * Reads the workspace's current run set. `@smthrs/engine-store` supplies
+     * the durable one over `flows_runs`; anything that answers the same
+     * question works, and the catalog holds no assumption about which.
+     */
+    readonly read: Effect.Effect<ReadonlyArray<JournalEvent.RunId>, E, R>;
+    /** Milliseconds between reads. Defaults to {@link defaultPollIntervalMs}. */
+    readonly intervalMs?: number | undefined;
+    /**
+     * Announcements a stalled subscriber may fall behind by. Defaults to
+     * {@link defaultChangesCapacity}.
+     */
+    readonly changesCapacity?: number | undefined;
+}
+/**
+ * Constructs a run catalog that polls a durable source.
+ *
+ * Polling, not waking. rc.0 has no cross-process event delivery, so a
+ * follower learns of a run another engine created by asking the workspace
+ * again, and the interval is the whole of the policy.
+ *
+ * The catalog primes itself before it returns, so the first read a follower
+ * makes is already current and a workspace that cannot be read at all fails
+ * the composition instead of serving an empty run set. After that a failed
+ * read is a warning and nothing else: the previous view stands, the interval
+ * holds, and no subscription attached to the catalog is torn down for it.
+ * The warning is written once per outage, with the first failure's cause, and
+ * one info line marks the read that ends it; the polls in between are silent.
+ *
+ * A run is announced once, when it first appears. A run the read stops
+ * naming, which is what retention collecting it looks like, leaves the view;
+ * `list` is the workspace's run set, not a log of every run it ever had.
+ *
+ * `list` answers with a fresh array each time, matching {@link layerStatic} and
+ * {@link makeMemory}. Handing back the stored snapshot let a caller sort or
+ * splice the authoritative run set in place under the poll fiber that owns it,
+ * which is a defect a `ReadonlyArray` type hides from TypeScript and not from
+ * JavaScript.
+ *
+ * The poll fiber belongs to the caller's scope. Closing the scope stops it.
+ *
+ * Both numeric options are validated here, before the first read: an
+ * `intervalMs` of `NaN` or zero reached `Effect.delay` as the whole of the
+ * poll cadence, which is a loop with no interval rather than a refusal.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makePolling: <E, R>(options: PollingOptions<E, R>) => Effect.Effect<Service, E | SyncError, R | Scope.Scope>;
+/**
+ * Provides a run catalog that polls a durable source. The poll fiber lives as
+ * long as the layer's scope.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerPolling: <E, R>(options: PollingOptions<E, R>) => Layer.Layer<RunCatalog, E | SyncError, R>;
+/**
+ * Provides the mutable in-memory run catalog, matching how every other
+ * implementation here is provided. Fails with `invalid_request` when
+ * `changesCapacity` is not a positive safe integer.
+ *
+ * The layer provides the catalog alone. A composition that also registers runs
+ * builds {@link makeMemory} itself and keeps its `register`.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerMemory: (options?: MemoryOptions) => Layer.Layer<RunCatalog, SyncError>;
+/**
+ * Provides an empty run catalog.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<RunCatalog>;
+export {};
+//# sourceMappingURL=RunCatalog.d.ts.map

package/dist/esm/RunCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunCatalog.d.ts","sourceRoot":"","sources":["../../src/RunCatalog.ts"],"names":[],"mappings":"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"}

package/dist/esm/RunCatalog.js

@@ -0,0 +1,196 @@
+/**
+ * Workspace run enumeration for synchronization.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+import { positiveInt } from "./internal/PolicyOptions.js";
+/**
+ * Host-provided workspace run catalog.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class RunCatalog extends Context.Service()("@smthrs/sync/RunCatalog") {
+}
+/**
+ * Provides an immutable run catalog.
+ *
+ * `list` answers with a fresh array each time, matching {@link makeMemory} and
+ * {@link makePolling}. Handing every caller the same instance let one reader
+ * sort or splice the catalog in place for every other reader, which is a
+ * defect a `ReadonlyArray` type hides from TypeScript and not from JavaScript.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerStatic = (ids) => {
+    const known = Array.from(new Set(ids));
+    return Layer.succeed(RunCatalog, RunCatalog.of({
+        list: Effect.sync(() => [...known]),
+        changes: Stream.empty
+    }));
+};
+/**
+ * Announcements a stalled {@link Service.changes} subscriber may fall behind
+ * by before the oldest are dropped.
+ *
+ * `changes` is a notification feed, not a log: a follower reads it to learn
+ * that the workspace gained a run and then reads the run itself. Retaining an
+ * unbounded backlog for a subscriber that has stopped pulling — a disconnected
+ * tab whose socket has not timed out yet, a follower blocked behind a slow
+ * consumer — is therefore pure cost, and the workspace's whole run history is
+ * the upper bound on it. A subscriber that falls further behind than this
+ * bound loses the oldest announcements; `list` still names every run, so a
+ * follower that reconnects or re-lists converges.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultChangesCapacity = 1024;
+/**
+ * Constructs a mutable in-memory run catalog.
+ *
+ * A run is published exactly once, when it is first registered. The
+ * announcement feed slides: registering never waits on a stalled subscriber,
+ * and never grows the process on its behalf.
+ *
+ * Fails with `invalid_request` when `changesCapacity` is not a positive safe
+ * integer, rather than handing it to `PubSub.sliding` as a capacity.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeMemory = (options = {}) => Effect.gen(function* () {
+    const known = new Set();
+    const changes = yield* PubSub.sliding(yield* positiveInt("RunCatalog.MemoryOptions.changesCapacity", options.changesCapacity, defaultChangesCapacity));
+    return {
+        catalog: RunCatalog.of({
+            list: Effect.sync(() => Array.from(known)).pipe(Effect.withSpan("RunCatalog.list")),
+            changes: Stream.fromPubSub(changes)
+        }),
+        register: Effect.fn("RunCatalog.register")((runId) => Effect.suspend(() => {
+            if (known.has(runId))
+                return Effect.void;
+            known.add(runId);
+            return PubSub.publish(changes, runId).pipe(Effect.asVoid);
+        }))
+    };
+});
+/**
+ * How often {@link makePolling} re-reads its source when the caller names no
+ * interval, in milliseconds.
+ *
+ * A workspace follower learns of a new run within one interval of it being
+ * created, and the read costs one bounded query per interval per composition,
+ * not per subscriber. A second is short enough that a run appears in a UI
+ * while the operator is still looking at the command that started it, and
+ * long enough that an idle workspace is close to free.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultPollIntervalMs = 1000;
+/**
+ * Constructs a run catalog that polls a durable source.
+ *
+ * Polling, not waking. rc.0 has no cross-process event delivery, so a
+ * follower learns of a run another engine created by asking the workspace
+ * again, and the interval is the whole of the policy.
+ *
+ * The catalog primes itself before it returns, so the first read a follower
+ * makes is already current and a workspace that cannot be read at all fails
+ * the composition instead of serving an empty run set. After that a failed
+ * read is a warning and nothing else: the previous view stands, the interval
+ * holds, and no subscription attached to the catalog is torn down for it.
+ * The warning is written once per outage, with the first failure's cause, and
+ * one info line marks the read that ends it; the polls in between are silent.
+ *
+ * A run is announced once, when it first appears. A run the read stops
+ * naming, which is what retention collecting it looks like, leaves the view;
+ * `list` is the workspace's run set, not a log of every run it ever had.
+ *
+ * `list` answers with a fresh array each time, matching {@link layerStatic} and
+ * {@link makeMemory}. Handing back the stored snapshot let a caller sort or
+ * splice the authoritative run set in place under the poll fiber that owns it,
+ * which is a defect a `ReadonlyArray` type hides from TypeScript and not from
+ * JavaScript.
+ *
+ * The poll fiber belongs to the caller's scope. Closing the scope stops it.
+ *
+ * Both numeric options are validated here, before the first read: an
+ * `intervalMs` of `NaN` or zero reached `Effect.delay` as the whole of the
+ * poll cadence, which is a loop with no interval rather than a refusal.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makePolling = (options) => Effect.gen(function* () {
+    const intervalMs = yield* positiveInt("RunCatalog.PollingOptions.intervalMs", options.intervalMs, defaultPollIntervalMs);
+    const changes = yield* PubSub.sliding(yield* positiveInt("RunCatalog.PollingOptions.changesCapacity", options.changesCapacity, defaultChangesCapacity));
+    const snapshot = yield* Ref.make([]);
+    const refresh = Effect.gen(function* () {
+        const read = yield* options.read;
+        const next = Array.from(new Set(read));
+        const previous = new Set(yield* Ref.get(snapshot));
+        yield* Ref.set(snapshot, next);
+        for (const runId of next) {
+            // Publishing never waits on a stalled subscriber, and never grows the
+            // process on its behalf: the feed slides.
+            if (!previous.has(runId))
+                yield* PubSub.publish(changes, runId);
+        }
+    });
+    yield* refresh;
+    // The log follows the outage's transitions, not the poll cadence. With
+    // the default interval a workspace that stays unreadable would otherwise
+    // write one identical warning per second per catalog for as long as it
+    // lasts, and the line that says it ended would never be written.
+    const consecutiveFailures = yield* Ref.make(0);
+    const poll = refresh.pipe(Effect.matchCauseEffect({
+        onFailure: (cause) => Effect.flatMap(Ref.updateAndGet(consecutiveFailures, (count) => count + 1), (count) => count === 1
+            ? Effect.logWarning("The workspace run catalog could not be read; the previous view stands", cause)
+            : Effect.void),
+        onSuccess: () => Effect.flatMap(Ref.getAndSet(consecutiveFailures, 0), (count) => count === 0
+            ? Effect.void
+            : Effect.logInfo(`The workspace run catalog is readable again after ${count} failed reads`))
+    }));
+    yield* poll.pipe(Effect.delay(intervalMs), Effect.forever, Effect.forkScoped);
+    return RunCatalog.of({
+        list: Effect.map(Ref.get(snapshot), (ids) => [...ids]).pipe(Effect.withSpan("RunCatalog.list")),
+        changes: Stream.fromPubSub(changes)
+    });
+});
+/**
+ * Provides a run catalog that polls a durable source. The poll fiber lives as
+ * long as the layer's scope.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerPolling = (options) => Layer.effect(RunCatalog, makePolling(options));
+/**
+ * Provides the mutable in-memory run catalog, matching how every other
+ * implementation here is provided. Fails with `invalid_request` when
+ * `changesCapacity` is not a positive safe integer.
+ *
+ * The layer provides the catalog alone. A composition that also registers runs
+ * builds {@link makeMemory} itself and keeps its `register`.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerMemory = (options = {}) => Layer.effect(RunCatalog, Effect.map(makeMemory(options), ({ catalog }) => catalog));
+/**
+ * Provides an empty run catalog.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = layerStatic([]);
+//# sourceMappingURL=RunCatalog.js.map

package/dist/esm/RunCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunCatalog.js","sourceRoot":"","sources":["../../src/RunCatalog.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace run enumeration for synchronization.\n *\n * @since 0.1.0\n */\n\nimport type { JournalEvent } from \"@smthrs/journal\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as PubSub from \"effect/PubSub\"\nimport * as Ref from \"effect/Ref\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport { positiveInt } from \"./internal/PolicyOptions.ts\"\nimport type { SyncError } from \"./SyncError.ts\"\n\n/**\n * Workspace run enumeration operations.\n *\n * `list` is the AUTHORITATIVE run set and `changes` is only a low-latency\n * wake: a subscriber that misses an announcement re-lists rather than losing\n * state, and a subscriber whose covered set must stay accurate re-lists on a\n * cadence of its own. Every implementation returns a fresh array from `list`,\n * so a caller may retain and sort what it receives without disturbing another\n * reader.\n *\n * `list` names each run AT MOST ONCE. Every implementation here deduplicates,\n * and `SyncServer` deduplicates again at the seam rather than trusting a\n * host's catalog, because both fan-out paths key a run's served position by\n * run id: a run named twice is read twice from the same position and its\n * entries are served twice.\n *\n * The catalog is supplied by the host rather than derived from the journal:\n * `@smthrs/journal` has no workspace-wide list or watch contract, and\n * `@smthrs/engine-store` owns the durable run set that {@link makePolling}\n * reads.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly list: Effect.Effect<ReadonlyArray<JournalEvent.RunId>>\n  readonly changes: Stream.Stream<JournalEvent.RunId>\n}\n\n/**\n * Host-provided workspace run catalog.\n *\n * @category services\n * @since 0.1.0\n */\nexport class RunCatalog extends Context.Service<RunCatalog, Service>()(\"@smthrs/sync/RunCatalog\") {}\n\n/**\n * Provides an immutable run catalog.\n *\n * `list` answers with a fresh array each time, matching {@link makeMemory} and\n * {@link makePolling}. Handing every caller the same instance let one reader\n * sort or splice the catalog in place for every other reader, which is a\n * defect a `ReadonlyArray` type hides from TypeScript and not from JavaScript.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerStatic = (\n  ids: ReadonlyArray<JournalEvent.RunId>\n): Layer.Layer<RunCatalog> => {\n  const known = Array.from(new Set(ids))\n  return Layer.succeed(\n    RunCatalog,\n    RunCatalog.of({\n      list: Effect.sync(() => [...known]),\n      changes: Stream.empty\n    })\n  )\n}\n\n/**\n * Announcements a stalled {@link Service.changes} subscriber may fall behind\n * by before the oldest are dropped.\n *\n * `changes` is a notification feed, not a log: a follower reads it to learn\n * that the workspace gained a run and then reads the run itself. Retaining an\n * unbounded backlog for a subscriber that has stopped pulling — a disconnected\n * tab whose socket has not timed out yet, a follower blocked behind a slow\n * consumer — is therefore pure cost, and the workspace's whole run history is\n * the upper bound on it. A subscriber that falls further behind than this\n * bound loses the oldest announcements; `list` still names every run, so a\n * follower that reconnects or re-lists converges.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultChangesCapacity = 1024\n\n/**\n * Options for the in-memory run catalog.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface MemoryOptions {\n  /**\n   * Announcements a stalled subscriber may fall behind by. Defaults to\n   * {@link defaultChangesCapacity}.\n   */\n  readonly changesCapacity?: number | undefined\n}\n\n/**\n * Constructs a mutable in-memory run catalog.\n *\n * A run is published exactly once, when it is first registered. The\n * announcement feed slides: registering never waits on a stalled subscriber,\n * and never grows the process on its behalf.\n *\n * Fails with `invalid_request` when `changesCapacity` is not a positive safe\n * integer, rather than handing it to `PubSub.sliding` as a capacity.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeMemory = (options: MemoryOptions = {}): Effect.Effect<{\n  readonly catalog: Service\n  readonly register: (runId: JournalEvent.RunId) => Effect.Effect<void>\n}, SyncError> =>\n  Effect.gen(function*() {\n    const known = new Set<JournalEvent.RunId>()\n    const changes = yield* PubSub.sliding<JournalEvent.RunId>(\n      yield* positiveInt(\"RunCatalog.MemoryOptions.changesCapacity\", options.changesCapacity, defaultChangesCapacity)\n    )\n    return {\n      catalog: RunCatalog.of({\n        list: Effect.sync(() => Array.from(known)).pipe(Effect.withSpan(\"RunCatalog.list\")),\n        changes: Stream.fromPubSub(changes)\n      }),\n      register: Effect.fn(\"RunCatalog.register\")((runId) =>\n        Effect.suspend(() => {\n          if (known.has(runId)) return Effect.void\n          known.add(runId)\n          return PubSub.publish(changes, runId).pipe(Effect.asVoid)\n        })\n      )\n    }\n  })\n\n/**\n * How often {@link makePolling} re-reads its source when the caller names no\n * interval, in milliseconds.\n *\n * A workspace follower learns of a new run within one interval of it being\n * created, and the read costs one bounded query per interval per composition,\n * not per subscriber. A second is short enough that a run appears in a UI\n * while the operator is still looking at the command that started it, and\n * long enough that an idle workspace is close to free.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultPollIntervalMs = 1000\n\n/**\n * Options for the polling run catalog.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface PollingOptions<E, R> {\n  /**\n   * Reads the workspace's current run set. `@smthrs/engine-store` supplies\n   * the durable one over `flows_runs`; anything that answers the same\n   * question works, and the catalog holds no assumption about which.\n   */\n  readonly read: Effect.Effect<ReadonlyArray<JournalEvent.RunId>, E, R>\n  /** Milliseconds between reads. Defaults to {@link defaultPollIntervalMs}. */\n  readonly intervalMs?: number | undefined\n  /**\n   * Announcements a stalled subscriber may fall behind by. Defaults to\n   * {@link defaultChangesCapacity}.\n   */\n  readonly changesCapacity?: number | undefined\n}\n\n/**\n * Constructs a run catalog that polls a durable source.\n *\n * Polling, not waking. rc.0 has no cross-process event delivery, so a\n * follower learns of a run another engine created by asking the workspace\n * again, and the interval is the whole of the policy.\n *\n * The catalog primes itself before it returns, so the first read a follower\n * makes is already current and a workspace that cannot be read at all fails\n * the composition instead of serving an empty run set. After that a failed\n * read is a warning and nothing else: the previous view stands, the interval\n * holds, and no subscription attached to the catalog is torn down for it.\n * The warning is written once per outage, with the first failure's cause, and\n * one info line marks the read that ends it; the polls in between are silent.\n *\n * A run is announced once, when it first appears. A run the read stops\n * naming, which is what retention collecting it looks like, leaves the view;\n * `list` is the workspace's run set, not a log of every run it ever had.\n *\n * `list` answers with a fresh array each time, matching {@link layerStatic} and\n * {@link makeMemory}. Handing back the stored snapshot let a caller sort or\n * splice the authoritative run set in place under the poll fiber that owns it,\n * which is a defect a `ReadonlyArray` type hides from TypeScript and not from\n * JavaScript.\n *\n * The poll fiber belongs to the caller's scope. Closing the scope stops it.\n *\n * Both numeric options are validated here, before the first read: an\n * `intervalMs` of `NaN` or zero reached `Effect.delay` as the whole of the\n * poll cadence, which is a loop with no interval rather than a refusal.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makePolling = <E, R>(\n  options: PollingOptions<E, R>\n): Effect.Effect<Service, E | SyncError, R | Scope.Scope> =>\n  Effect.gen(function*() {\n    const intervalMs = yield* positiveInt(\n      \"RunCatalog.PollingOptions.intervalMs\",\n      options.intervalMs,\n      defaultPollIntervalMs\n    )\n    const changes = yield* PubSub.sliding<JournalEvent.RunId>(\n      yield* positiveInt(\"RunCatalog.PollingOptions.changesCapacity\", options.changesCapacity, defaultChangesCapacity)\n    )\n    const snapshot = yield* Ref.make<ReadonlyArray<JournalEvent.RunId>>([])\n\n    const refresh = Effect.gen(function*() {\n      const read = yield* options.read\n      const next = Array.from(new Set(read))\n      const previous = new Set(yield* Ref.get(snapshot))\n      yield* Ref.set(snapshot, next)\n      for (const runId of next) {\n        // Publishing never waits on a stalled subscriber, and never grows the\n        // process on its behalf: the feed slides.\n        if (!previous.has(runId)) yield* PubSub.publish(changes, runId)\n      }\n    })\n\n    yield* refresh\n    // The log follows the outage's transitions, not the poll cadence. With\n    // the default interval a workspace that stays unreadable would otherwise\n    // write one identical warning per second per catalog for as long as it\n    // lasts, and the line that says it ended would never be written.\n    const consecutiveFailures = yield* Ref.make(0)\n    const poll = refresh.pipe(\n      Effect.matchCauseEffect({\n        onFailure: (cause) =>\n          Effect.flatMap(Ref.updateAndGet(consecutiveFailures, (count) => count + 1), (count) =>\n            count === 1\n              ? Effect.logWarning(\"The workspace run catalog could not be read; the previous view stands\", cause)\n              : Effect.void),\n        onSuccess: () =>\n          Effect.flatMap(Ref.getAndSet(consecutiveFailures, 0), (count) =>\n            count === 0\n              ? Effect.void\n              : Effect.logInfo(`The workspace run catalog is readable again after ${count} failed reads`))\n      })\n    )\n    yield* poll.pipe(\n      Effect.delay(intervalMs),\n      Effect.forever,\n      Effect.forkScoped\n    )\n\n    return RunCatalog.of({\n      list: Effect.map(Ref.get(snapshot), (ids) => [...ids]).pipe(Effect.withSpan(\"RunCatalog.list\")),\n      changes: Stream.fromPubSub(changes)\n    })\n  })\n\n/**\n * Provides a run catalog that polls a durable source. The poll fiber lives as\n * long as the layer's scope.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerPolling = <E, R>(\n  options: PollingOptions<E, R>\n): Layer.Layer<RunCatalog, E | SyncError, R> => Layer.effect(RunCatalog, makePolling(options))\n\n/**\n * Provides the mutable in-memory run catalog, matching how every other\n * implementation here is provided. Fails with `invalid_request` when\n * `changesCapacity` is not a positive safe integer.\n *\n * The layer provides the catalog alone. A composition that also registers runs\n * builds {@link makeMemory} itself and keeps its `register`.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerMemory = (options: MemoryOptions = {}): Layer.Layer<RunCatalog, SyncError> =>\n  Layer.effect(RunCatalog, Effect.map(makeMemory(options), ({ catalog }) => catalog))\n\n/**\n * Provides an empty run catalog.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<RunCatalog> = layerStatic([])\n"]}

package/dist/esm/SyncAuth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The sync read path's connection authentication: implementations of the
+ * `SyncRpcs.SyncAuth` RPC middleware.
+ *
+ * A connection presents a {@link WorkspaceShare.WorkspaceCapability} in the
+ * {@link capabilityHeader} request header. {@link layer} verifies it against
+ * the workspace's {@link WorkspaceShare.WorkspaceShare} authority and runs
+ * the handler as the workspace principal. A request with no header runs as
+ * the anonymous principal — branch share capabilities carried in request
+ * payloads still authorize branch reads — and the server refuses anonymous
+ * access to every non-branch run. A request whose header is present but
+ * malformed, forged, expired, or signed by an unknown key is refused
+ * outright: presence of a credential is a claim, and a false claim is never
+ * downgraded to anonymity.
+ *
+ * There is deliberately no trusted pass-through implementation here: the only
+ * sanctioned bypass is an in-process caller providing `SyncPrincipal` itself,
+ * never a transport.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as RpcMiddleware from "effect/unstable/rpc/RpcMiddleware";
+import { SyncError } from "./SyncError.ts";
+import { SyncAuth } from "./SyncRpcs.ts";
+import * as WorkspaceShare from "./WorkspaceShare.ts";
+/**
+ * The request header a connection presents its workspace capability in.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const capabilityHeader = "flows-sync-workspace";
+/**
+ * Renders a workspace capability as its header value: unpadded base64url of
+ * the schema-encoded capability JSON.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const encodeCapability: (capability: WorkspaceShare.WorkspaceCapability) => Effect.Effect<string, SyncError>;
+/**
+ * Decodes a capability header value. Every malformation folds to the same
+ * `unauthorized` refusal so the header is not a parsing oracle.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const decodeCapability: (value: string) => Effect.Effect<WorkspaceShare.WorkspaceCapability, SyncError>;
+/**
+ * Provides the workspace-capability authentication middleware: no header
+ * runs the handler as anonymous, a verified header runs it as the workspace
+ * principal, and anything else refuses the request. Verification faults
+ * (Web Crypto failing) propagate as their own error rather than as a
+ * refusal.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<SyncAuth, never, WorkspaceShare.WorkspaceShare>;
+/**
+ * Stamps every outgoing request from a generated RPC client with the given
+ * workspace capability.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerClient: (capability: WorkspaceShare.WorkspaceCapability) => Layer.Layer<RpcMiddleware.ForClient<SyncAuth>, SyncError>;
+//# sourceMappingURL=SyncAuth.d.ts.map

package/dist/esm/SyncAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncAuth.d.ts","sourceRoot":"","sources":["../../src/SyncAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAIrC,OAAO,KAAK,aAAa,MAAM,mCAAmC,CAAA;AAGlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,yBAAyB,CAAA;AAItD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,YAAY,cAAc,CAAC,mBAAmB,KAC7C,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAajC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,mBAAmB,EAAE,SAAS,CAe3G,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,cAAc,CAyB7E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,YAAY,cAAc,CAAC,mBAAmB,KAC7C,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,SAAS,CAKxD,CAAA"}