@de-otio/trellis 0.10.10 → 0.11.0

package/dist/lib/realtime/index.d.ts

@@ -0,0 +1,21 @@
+export type { Channel, ChannelKind, ScopeType, VerifiedIdentity, DeliveryTarget, DeliveryResult, DeliveryContext, DeliveryDecision, QuietHoursConfig, WakeupEnvelope, EncryptedBlob, PutResult, SettingStore, ChangedSettingMeta, ChangeCursorStore, RealtimeTransport, DeliveryPolicyResolver, } from "./types.js";
+export { encodeWakeup, decodeWakeup, supportsChangeCursor } from "./types.js";
+export { channelName, parseChannel, channelFor, authorizeSubscription, } from "./channel.js";
+export { CalmDeliveryResolver, ALWAYS_DELIVER_TYPES, } from "./delivery-policy.js";
+export { InMemorySettingStore } from "./setting-store.js";
+export { PollTransport } from "./poll-transport.js";
+export { NoopRealtimeTransport } from "./no-op-transport.js";
+import type { RealtimeTransport } from "./types.js";
+/**
+ * Consuming app (Skybber) calls this at startup with its concrete transport
+ * (e.g. AppSyncEventsTransport). MUST run before buildEnv-consumers serve.
+ */
+export declare function setRealtimeProvider(transport: RealtimeTransport): void;
+/**
+ * Returns the injected transport if a provider was registered, else the
+ * supplied fallback. `buildEnv` calls this with the default Poll/Noop transport.
+ */
+export declare function resolveRealtimeTransport(fallback: RealtimeTransport): RealtimeTransport;
+/** Test-only: clear the injected provider so tests don't leak across cases. */
+export declare function __resetRealtimeProviderForTests(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/realtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/index.ts"],"names":[],"mappings":"AAQA,YAAY,EAEV,OAAO,EACP,WAAW,EACX,SAAS,EAET,gBAAgB,EAEhB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAEhB,cAAc,EAEd,aAAa,EACb,SAAS,EACT,YAAY,EAEZ,kBAAkB,EAClB,iBAAiB,EAEjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAWpD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAEtE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CAEnB;AAED,+EAA+E;AAC/E,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/lib/realtime/index.js

@@ -0,0 +1,39 @@
+// CONTRACT: stable — coordinate changes. See types.ts banner.
+//
+// Public barrel for the RealtimeTransport seam — the ONLY import path consumers
+// use (published as `@de-otio/trellis/realtime`). Re-exports the frozen types,
+// the channel helpers, the ports + defaults, the two in-core transports, and
+// the provider-injection hook a consuming app (Skybber) uses to plug in its
+// AppSyncEventsTransport WITHOUT core importing any AWS SDK.
+export { encodeWakeup, decodeWakeup, supportsChangeCursor } from "./types.js";
+export { channelName, parseChannel, channelFor, authorizeSubscription, } from "./channel.js";
+export { CalmDeliveryResolver, ALWAYS_DELIVER_TYPES, } from "./delivery-policy.js";
+export { InMemorySettingStore } from "./setting-store.js";
+export { PollTransport } from "./poll-transport.js";
+export { NoopRealtimeTransport } from "./no-op-transport.js";
+// ---------------------------------------------------------------------------
+// Provider-injection hook (mirrors registerExtension). A consuming app calls
+// setRealtimeProvider() at startup, BEFORE buildEnv-consumers serve, with its
+// concrete transport. resolveRealtimeTransport() returns the injected transport
+// if present, else the supplied fallback (the core Poll/Noop default).
+// ---------------------------------------------------------------------------
+let injected;
+/**
+ * Consuming app (Skybber) calls this at startup with its concrete transport
+ * (e.g. AppSyncEventsTransport). MUST run before buildEnv-consumers serve.
+ */
+export function setRealtimeProvider(transport) {
+    injected = transport;
+}
+/**
+ * Returns the injected transport if a provider was registered, else the
+ * supplied fallback. `buildEnv` calls this with the default Poll/Noop transport.
+ */
+export function resolveRealtimeTransport(fallback) {
+    return injected ?? fallback;
+}
+/** Test-only: clear the injected provider so tests don't leak across cases. */
+export function __resetRealtimeProviderForTests() {
+    injected = undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/realtime/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,6DAA6D;AA6B7D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAI7D,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,uEAAuE;AACvE,8EAA8E;AAE9E,IAAI,QAAuC,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA4B;IAC9D,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA2B;IAE3B,OAAO,QAAQ,IAAI,QAAQ,CAAC;AAC9B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,+BAA+B;IAC7C,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC"}

package/dist/lib/realtime/no-op-transport.d.ts

@@ -0,0 +1,10 @@
+import type { Channel, DeliveryPolicyResolver, DeliveryResult, DeliveryTarget, EncryptedBlob, PutResult, RealtimeTransport } from "./types.js";
+export declare class NoopRealtimeTransport implements RealtimeTransport {
+    private readonly policy;
+    readonly kind: "noop";
+    constructor(policy: DeliveryPolicyResolver);
+    deliver(target: DeliveryTarget, channel: Channel, _payload: Uint8Array): Promise<DeliveryResult>;
+    getSetting(_userId: string, _namespace: string): Promise<EncryptedBlob | null>;
+    putSetting(_userId: string, _namespace: string, _blob: EncryptedBlob, _expectVersion: number): Promise<PutResult>;
+}
+//# sourceMappingURL=no-op-transport.d.ts.map

package/dist/lib/realtime/no-op-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-op-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/no-op-transport.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,OAAO,EAEP,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAepB,qBAAa,qBAAsB,YAAW,iBAAiB;IAGjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAEH,MAAM,EAAE,sBAAsB;IAErD,OAAO,CACX,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,CAAC;IAepB,UAAU,CACd,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAI1B,UAAU,CACd,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,EACpB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,CAAC;CAGtB"}

package/dist/lib/realtime/no-op-transport.js

@@ -0,0 +1,44 @@
+// CONTRACT-adjacent — the CI transport. See types.ts banner.
+//
+// NoopRealtimeTransport: the same shape as PollTransport but with NO store and
+// NO wire. It still runs the policy fence inside deliver() (so the fence-runs-
+// on-every-transport invariant holds), then drops. getSetting/putSetting are
+// inert (no store). Used in tests/CI where neither a store nor a socket exists.
+function fenceContextFor(target, channel) {
+    const type = channel.kind === "safety" ? "SAFETY_ALERT" : "SYSTEM";
+    return {
+        type,
+        recipientUserId: target.userId,
+        tenantId: target.tenantId,
+        now: new Date(),
+    };
+}
+export class NoopRealtimeTransport {
+    policy;
+    kind = "noop";
+    constructor(policy) {
+        this.policy = policy;
+    }
+    async deliver(target, channel, _payload) {
+        // Best-effort: a transport-internal fault (e.g. a throwing resolver) is
+        // caught and surfaced as transport_error, never a reject that could roll
+        // back a persisted write (frozen contract §2.3).
+        try {
+            const decision = this.policy.decide(fenceContextFor(target, channel));
+            if (!decision.deliver) {
+                return { delivered: false, reason: "policy_denied" };
+            }
+            return { delivered: false, reason: "no_transport" };
+        }
+        catch {
+            return { delivered: false, reason: "transport_error" };
+        }
+    }
+    async getSetting(_userId, _namespace) {
+        return null;
+    }
+    async putSetting(_userId, _namespace, _blob, _expectVersion) {
+        return { ok: false, reason: "not_found", current: null };
+    }
+}
+//# sourceMappingURL=no-op-transport.js.map

package/dist/lib/realtime/no-op-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-op-transport.js","sourceRoot":"","sources":["../../../src/lib/realtime/no-op-transport.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAahF,SAAS,eAAe,CACtB,MAAsB,EACtB,OAAgB;IAEhB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnE,OAAO;QACL,IAAI;QACJ,eAAe,EAAE,MAAM,CAAC,MAAM;QAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,IAAI,IAAI,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,qBAAqB;IAGH;IAFpB,IAAI,GAAG,MAAe,CAAC;IAEhC,YAA6B,MAA8B;QAA9B,WAAM,GAAN,MAAM,CAAwB;IAAG,CAAC;IAE/D,KAAK,CAAC,OAAO,CACX,MAAsB,EACtB,OAAgB,EAChB,QAAoB;QAEpB,wEAAwE;QACxE,yEAAyE;QACzE,iDAAiD;QACjD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YACtE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CACd,OAAe,EACf,UAAkB;QAElB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,UAAU,CACd,OAAe,EACf,UAAkB,EAClB,KAAoB,EACpB,cAAsB;QAEtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3D,CAAC;CACF"}

package/dist/lib/realtime/poll-transport.d.ts

@@ -0,0 +1,11 @@
+import type { Channel, DeliveryPolicyResolver, DeliveryResult, DeliveryTarget, EncryptedBlob, PutResult, RealtimeTransport, SettingStore } from "./types.js";
+export declare class PollTransport implements RealtimeTransport {
+    private readonly store;
+    private readonly policy;
+    readonly kind: "poll";
+    constructor(store: SettingStore, policy: DeliveryPolicyResolver);
+    deliver(target: DeliveryTarget, channel: Channel, _payload: Uint8Array): Promise<DeliveryResult>;
+    getSetting(userId: string, namespace: string): Promise<EncryptedBlob | null>;
+    putSetting(userId: string, namespace: string, blob: EncryptedBlob, expectVersion: number): Promise<PutResult>;
+}
+//# sourceMappingURL=poll-transport.d.ts.map

package/dist/lib/realtime/poll-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/poll-transport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,OAAO,EAEP,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,YAAY,EACb,MAAM,YAAY,CAAC;AA0BpB,qBAAa,aAAc,YAAW,iBAAiB;IAInD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAGb,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,sBAAsB;IAG3C,OAAO,CACX,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,CAAC;IAmB1B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAI5E,UAAU,CACR,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,EACnB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,CAAC;CAGtB"}

package/dist/lib/realtime/poll-transport.js

@@ -0,0 +1,68 @@
+// CONTRACT-adjacent — the default transport. See types.ts banner.
+//
+// PollTransport makes core runnable and testable with NO realtime infra. It is
+// a correctness default, explicitly NOT the scale answer.
+//
+//   deliver()  -> runs the policy fence, then NO-OPs the wire send and returns
+//                 { delivered: false, reason: "no_transport" } (clients poll;
+//                 the side-effecting persistence — the Notification row / the
+//                 setting version bump — is what the next poll observes). The
+//                 fence still runs so swapping in AppSync changes the pipe, not
+//                 a single call site.
+//   getSetting / putSetting -> delegate to the injected SettingStore (the real
+//                 REST-backed sync path).
+/**
+ * Build the `DeliveryContext` the policy fence needs from a `deliver()` call.
+ * PollTransport has no notification metadata at the wire boundary (the floor
+ * decision was already made by the caller for persistence), so it constructs a
+ * minimal, fence-running context. The interface keeps payloads opaque, so the
+ * transport derives only routing-level inputs.
+ */
+function fenceContextFor(target, channel) {
+    // Map the channel kind back onto a NotificationType-shaped floor input: the
+    // "safety" kind is critical-always, everything else is best-effort. We do not
+    // have the original NotificationType here, so we synthesize the floor-relevant
+    // signal: a "safety" channel must never be suppressed.
+    const type = channel.kind === "safety" ? "SAFETY_ALERT" : "SYSTEM";
+    return {
+        type,
+        recipientUserId: target.userId,
+        tenantId: target.tenantId,
+        now: new Date(),
+    };
+}
+export class PollTransport {
+    store;
+    policy;
+    kind = "poll";
+    constructor(store, policy) {
+        this.store = store;
+        this.policy = policy;
+    }
+    async deliver(target, channel, _payload) {
+        // deliver() is BEST-EFFORT: it MUST NOT reject in a way that could roll back
+        // a persisted write upstream. Any internal fault (e.g. a throwing resolver)
+        // is caught and surfaced as transport_error (frozen contract §2.3 + the
+        // realtime-transport.ts binding rules).
+        try {
+            // The policy fence runs on EVERY transport, even the no-op one.
+            const decision = this.policy.decide(fenceContextFor(target, channel));
+            if (!decision.deliver) {
+                return { delivered: false, reason: "policy_denied" };
+            }
+            // Poll model: there is no socket. The client learns of the change on its
+            // next poll, so the wire send is a deliberate no-op.
+            return { delivered: false, reason: "no_transport" };
+        }
+        catch {
+            return { delivered: false, reason: "transport_error" };
+        }
+    }
+    getSetting(userId, namespace) {
+        return this.store.get(userId, namespace);
+    }
+    putSetting(userId, namespace, blob, expectVersion) {
+        return this.store.put(userId, namespace, blob, expectVersion);
+    }
+}
+//# sourceMappingURL=poll-transport.js.map

package/dist/lib/realtime/poll-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-transport.js","sourceRoot":"","sources":["../../../src/lib/realtime/poll-transport.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,+EAA+E;AAC/E,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,sCAAsC;AACtC,+EAA+E;AAC/E,0CAA0C;AAc1C;;;;;;GAMG;AACH,SAAS,eAAe,CACtB,MAAsB,EACtB,OAAgB;IAEhB,4EAA4E;IAC5E,8EAA8E;IAC9E,+EAA+E;IAC/E,uDAAuD;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnE,OAAO;QACL,IAAI;QACJ,eAAe,EAAE,MAAM,CAAC,MAAM;QAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,IAAI,IAAI,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,aAAa;IAIL;IACA;IAJV,IAAI,GAAG,MAAe,CAAC;IAEhC,YACmB,KAAmB,EACnB,MAA8B;QAD9B,UAAK,GAAL,KAAK,CAAc;QACnB,WAAM,GAAN,MAAM,CAAwB;IAC9C,CAAC;IAEJ,KAAK,CAAC,OAAO,CACX,MAAsB,EACtB,OAAgB,EAChB,QAAoB;QAEpB,6EAA6E;QAC7E,4EAA4E;QAC5E,wEAAwE;QACxE,wCAAwC;QACxC,IAAI,CAAC;YACH,gEAAgE;YAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YACtE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,yEAAyE;YACzE,qDAAqD;YACrD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IAED,UAAU,CAAC,MAAc,EAAE,SAAiB;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU,CACR,MAAc,EACd,SAAiB,EACjB,IAAmB,EACnB,aAAqB;QAErB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;CACF"}

package/dist/lib/realtime/push-notifier.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from "../logger.js";
+import type { ChannelKind, RealtimeTransport } from "./types.js";
+/** The kinds WS4 routes a content-free notification wakeup onto. */
+export type WakeupKind = Extract<ChannelKind, "wakeup" | "safety">;
+export interface PushNotifierInput {
+    /** Server-resolved recipient. */
+    target: {
+        userId: string;
+        tenantId: string;
+    };
+    /**
+     * Channel kind: ALWAYS_DELIVER notifications route to "safety" (the floor
+     * channel), everything else to "wakeup". Constrained to the two content-free
+     * kinds WS4 owns — there is no overload that accepts "message"/"thread".
+     */
+    kind: WakeupKind;
+}
+/**
+ * Build the content-free wakeup payload for a notification. The envelope is the
+ * frozen WS1 `WakeupEnvelope` and carries NO notification content — only the
+ * envelope version and the channel kind. There is deliberately no `changeToken`
+ * for notification wakeups (that field is the setting_sync version pointer); a
+ * notification wakeup says only "something changed on this surface; refetch".
+ */
+export declare function buildNotificationWakeup(kind: WakeupKind): Uint8Array;
+/**
+ * Relay a content-free wakeup over the realtime transport, best-effort.
+ *
+ * Resolves to `true` if the transport reported a delivery, `false` otherwise
+ * (policy-denied, no transport, transport error, or a thrown transport). NEVER
+ * throws — the caller's persisted write is durable regardless.
+ */
+export declare class PushNotifier {
+    private readonly transport;
+    private readonly logger;
+    constructor(transport: RealtimeTransport, logger: Logger);
+    notify(input: PushNotifierInput): Promise<boolean>;
+}
+//# sourceMappingURL=push-notifier.d.ts.map

package/dist/lib/realtime/push-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-notifier.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/push-notifier.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAkB,MAAM,YAAY,CAAC;AAEjF,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;OAIG;IACH,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAGpE;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,MAAM;IAG3B,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;CA8BzD"}

package/dist/lib/realtime/push-notifier.js

@@ -0,0 +1,76 @@
+// WS4 — content-free push consumer.
+//
+// PushNotifier is the ONE place that turns a "deliver" decision into a wire
+// wakeup. It exists so `notification-handler.ts` stays slim and so the
+// content-free guarantee is structural, not a per-call-site discipline:
+//
+//   1. The payload is built ONLY via `encodeWakeup()` (the frozen WS1 envelope).
+//      WS4 is FORBIDDEN by the contract from constructing arbitrary Uint8Array
+//      for wakeup/setting_sync/safety kinds — there is no code path here that
+//      can put a title/body/data on the wire (types.ts §2.4).
+//   2. The channel is built ONLY via `channelFor()` — tenant- and user-scoped,
+//      server-resolved, never client-asserted.
+//   3. `transport.deliver()` is BEST-EFFORT: a transport throw is caught and
+//      logged, NEVER rethrown, so it can never roll back the already-persisted
+//      Notification row. Polling remains the floor.
+//
+// The policy fence (CalmDeliveryResolver floor) runs in TWO places by design:
+// the caller gates on its decision (so a deferred/blocked/preference-off
+// notification never reaches here), AND the transport re-runs the fence inside
+// `deliver()`. PushNotifier itself does not re-decide — it relays the decision
+// the caller already made onto the correct channel kind.
+import { channelFor } from "./channel.js";
+import { encodeWakeup } from "./types.js";
+/**
+ * Build the content-free wakeup payload for a notification. The envelope is the
+ * frozen WS1 `WakeupEnvelope` and carries NO notification content — only the
+ * envelope version and the channel kind. There is deliberately no `changeToken`
+ * for notification wakeups (that field is the setting_sync version pointer); a
+ * notification wakeup says only "something changed on this surface; refetch".
+ */
+export function buildNotificationWakeup(kind) {
+    const envelope = { v: 1, kind };
+    return encodeWakeup(envelope);
+}
+/**
+ * Relay a content-free wakeup over the realtime transport, best-effort.
+ *
+ * Resolves to `true` if the transport reported a delivery, `false` otherwise
+ * (policy-denied, no transport, transport error, or a thrown transport). NEVER
+ * throws — the caller's persisted write is durable regardless.
+ */
+export class PushNotifier {
+    transport;
+    logger;
+    constructor(transport, logger) {
+        this.transport = transport;
+        this.logger = logger;
+    }
+    async notify(input) {
+        const { target, kind } = input;
+        const channel = channelFor(kind, {
+            tenantId: target.tenantId,
+            userId: target.userId,
+        });
+        const payload = buildNotificationWakeup(kind);
+        try {
+            const result = await this.transport.deliver({ userId: target.userId, tenantId: target.tenantId }, channel, payload);
+            if (!result.delivered) {
+                // Not an error — poll/no-transport/policy are normal outcomes. Logged
+                // at debug so the absence of a push is observable without noise.
+                this.logger.debug("realtime wakeup not delivered", {
+                    reason: result.reason,
+                    kind,
+                });
+            }
+            return result.delivered;
+        }
+        catch (err) {
+            // BEST-EFFORT: a transport hiccup must never surface to the caller. The
+            // notification row is already persisted; the next poll delivers it.
+            this.logger.warn("realtime wakeup deliver threw (non-fatal)", err);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=push-notifier.js.map

package/dist/lib/realtime/push-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-notifier.js","sourceRoot":"","sources":["../../../src/lib/realtime/push-notifier.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,8EAA8E;AAC9E,8DAA8D;AAC9D,+EAA+E;AAC/E,+CAA+C;AAC/C,6EAA6E;AAC7E,+EAA+E;AAC/E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,yDAAyD;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB1C;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAgB;IACtD,MAAM,QAAQ,GAAmB,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IAChD,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAEJ;IACA;IAFnB,YACmB,SAA4B,EAC5B,MAAc;QADd,cAAS,GAAT,SAAS,CAAmB;QAC5B,WAAM,GAAN,MAAM,CAAQ;IAC9B,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAC,KAAwB;QACnC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;QAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CACzC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EACpD,OAAO,EACP,OAAO,CACR,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACtB,sEAAsE;gBACtE,iEAAiE;gBACjE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;oBACjD,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,IAAI;iBACL,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC,SAAS,CAAC;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,oEAAoE;YACpE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,EAAE,GAAG,CAAC,CAAC;YACnE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/lib/realtime/realtime-transport.d.ts

@@ -0,0 +1,2 @@
+export type { RealtimeTransport, DeliveryPolicyResolver, DeliveryTarget, DeliveryResult, Channel, EncryptedBlob, PutResult, SettingStore, } from "./types.js";
+//# sourceMappingURL=realtime-transport.d.ts.map

package/dist/lib/realtime/realtime-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/realtime-transport.ts"],"names":[],"mappings":"AAsBA,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,OAAO,EACP,aAAa,EACb,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/lib/realtime/realtime-transport.js

@@ -0,0 +1,23 @@
+// CONTRACT: stable — coordinate changes.
+//
+// The RealtimeTransport capability interface — THE seam every other workstream
+// and the Skybber client binds to. The interface body lives in types.ts (single
+// source of truth for the frozen type set); this module re-exports it under its
+// own name so consumers can import the contract from a file whose name states
+// what it is, and so the CONTRACT banner sits with the interface.
+//
+// Binding rules for every transport implementor (poll, noop, appsync-events):
+//   - deliver() is BEST-EFFORT and NEVER rolls back a persisted write. It
+//     resolves with a DeliveryResult; it must catch its own transport errors
+//     and surface them as { delivered: false, reason: "transport_error" }.
+//   - The policy fence (the safety floor) runs INSIDE every deliver(), never at
+//     the call site. A transport author MUST call the resolver and honor a
+//     { deliver: false } by NOT sending. PollTransport, NoopRealtimeTransport,
+//     and Skybber's AppSyncEventsTransport all obey this.
+//   - payload is OPAQUE bytes the transport never parses (blind relay). Anything
+//     sensitive is client-side ciphertext; content-free wakeups use
+//     encodeWakeup().
+//   - Implementations MUST NOT durably log connection/delivery metadata as
+//     ordinary operational data (CLAUDE.md rule 7; retention is runtime config).
+export {};
+//# sourceMappingURL=realtime-transport.js.map

package/dist/lib/realtime/realtime-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-transport.js","sourceRoot":"","sources":["../../../src/lib/realtime/realtime-transport.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,2EAA2E;AAC3E,+EAA+E;AAC/E,0DAA0D;AAC1D,iFAAiF;AACjF,oEAAoE;AACpE,sBAAsB;AACtB,2EAA2E;AAC3E,iFAAiF"}

package/dist/lib/realtime/setting-store.d.ts

@@ -0,0 +1,30 @@
+import type { ChangeCursorStore, ChangedSettingMeta, EncryptedBlob, PutResult, SettingStore } from "./types.js";
+export type { SettingStore };
+/**
+ * In-memory `SettingStore` with optimistic-concurrency semantics. Keyed by
+ * `userId \0 namespace`. The server NEVER parses `ciphertext`.
+ *
+ * Optimistic concurrency:
+ *  - First write of a (user, namespace) requires `expectVersion === 0`; a
+ *    non-zero `expectVersion` against an absent record => `not_found`.
+ *  - A write whose `expectVersion` does not equal the stored version =>
+ *    `version_conflict` carrying the current blob for client-side merge.
+ *  - On success the stored version is set to `expectVersion + 1` and
+ *    `updatedAt` is server-assigned from the injectable clock.
+ */
+export declare class InMemorySettingStore implements SettingStore, ChangeCursorStore {
+    private readonly now;
+    private readonly store;
+    constructor(now?: () => Date);
+    private key;
+    get(userId: string, namespace: string): Promise<EncryptedBlob | null>;
+    put(userId: string, namespace: string, blob: EncryptedBlob, expectVersion: number): Promise<PutResult>;
+    /**
+     * Track C — offline backfill. Returns metadata for this user's namespaces whose
+     * `version` advanced strictly past `sinceVersion`. METADATA ONLY: never carries
+     * `ciphertext`. Sorted by ascending `version` so the caller can advance its
+     * cursor to the last entry's `version`.
+     */
+    listChangedSince(userId: string, sinceVersion: number): Promise<ChangedSettingMeta[]>;
+}
+//# sourceMappingURL=setting-store.d.ts.map

package/dist/lib/realtime/setting-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting-store.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/setting-store.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,YAAW,YAAY,EAAE,iBAAiB;IAQ9D,OAAO,CAAC,QAAQ,CAAC,GAAG;IALhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;gBAEyB,GAAG,GAAE,MAAM,IAAuB;IAE/D,OAAO,CAAC,GAAG;IAIL,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIrE,GAAG,CACP,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,EACnB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,CAAC;IAgCrB;;;;;OAKG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAcjC"}

package/dist/lib/realtime/setting-store.js.map

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

package/dist/lib/realtime/types.d.ts

@@ -0,0 +1,200 @@
+import type { NotificationType, AgeTier } from "@prisma/client";
+/**
+ * Coarse class of realtime traffic. Lets policy/transport route and rate-shape.
+ * v1 ships ONLY the user-scoped kinds (`wakeup`, `setting_sync`, `safety`);
+ * `message` and `thread` are taxonomy-reserved but unused (DEFERRED).
+ */
+export type ChannelKind = "wakeup" | "setting_sync" | "safety" | "message" | "thread";
+/** The scope a channel addresses. v1 ships only `"user"`. */
+export type ScopeType = "user" | "conversation" | "thread";
+/**
+ * A push-delivery channel — a content-free routing address, ALWAYS tenant- and
+ * scope-bound and server-verified. The canonical string form is produced ONLY
+ * by `channelName()` and parsed ONLY by `parseChannel()` (and the Skybber
+ * `@skybber/realtime-channels` parser, which must round-trip them).
+ *
+ * FROZEN kind→scopeType map (v1 ships ONLY user-scoped kinds):
+ *   wakeup | setting_sync | safety  -> scopeType "user",  scopeId = recipient userId
+ *   message                         -> scopeType "conversation" (DEFERRED)
+ *   thread                          -> scopeType "thread"        (DEFERRED)
+ */
+export interface Channel {
+    kind: ChannelKind;
+    /** Server-resolved tenant scope. */
+    tenantId: string;
+    scopeType: ScopeType;
+    /** userId (v1) | conversationId | threadId (deferred). */
+    scopeId: string;
+}
+/**
+ * Verified identity. Derived ONLY from Cognito claims (custom:userId,
+ * custom:activeTenantId) — by the in-core handler AND the Skybber authorizer
+ * Lambda — so both call the SAME function. Never an ambient Session, never a
+ * client-asserted path.
+ */
+export interface VerifiedIdentity {
+    userId: string;
+    tenantId: string;
+}
+/** Recipient address for `deliver()`. Both fields server-resolved. */
+export interface DeliveryTarget {
+    userId: string;
+    tenantId: string;
+}
+/**
+ * Result of a `deliver()` attempt. `deliver()` is BEST-EFFORT: it NEVER rejects
+ * in a way that rolls back a persisted write. It resolves with this result;
+ * transports catch their own errors. The policy fence runs INSIDE every
+ * transport's `deliver()`.
+ */
+export type DeliveryResult = {
+    delivered: true;
+} | {
+    delivered: false;
+    reason: "policy_denied" | "no_transport" | "transport_error";
+};
+/**
+ * Input the policy resolver sees. Built by the caller from its own args
+ * (`createNotification` has no Session), enriched with recipient ageTier /
+ * blocked-sender as needed for the floor.
+ */
+export interface DeliveryContext {
+    type: NotificationType;
+    recipientUserId: string;
+    tenantId: string;
+    /** blocked-sender floor input. */
+    senderUserId?: string;
+    /** minor-protection floor input. */
+    recipientAgeTier?: AgeTier;
+    now: Date;
+    quietHours?: QuietHoursConfig | null;
+}
+/** What the resolver decided for ONE delivery attempt. */
+export type DeliveryDecision = {
+    deliver: true;
+} | {
+    deliver: false;
+    reason: "preference" | "quiet_hours" | "blocked_sender" | "floor";
+};
+/**
+ * Quiet-hours window. `start`/`end` are opaque to the contract; the resolver
+ * that produced the context owns their interpretation. (The core resolver
+ * encodes minutes-since-midnight as decimal strings to reproduce the existing
+ * `User.quietHoursStart/End` integer behavior byte-identically.)
+ */
+export interface QuietHoursConfig {
+    enabled: boolean;
+    start: string;
+    end: string;
+}
+/**
+ * The ONLY shape push payloads for wakeup/setting_sync may take. It has NO
+ * free-form field — content-free is a property of the TYPE, not a test
+ * heuristic. WS4/WS5 are FORBIDDEN from constructing arbitrary Uint8Array for
+ * these kinds; they must use `encodeWakeup()`.
+ */
+export interface WakeupEnvelope {
+    v: 1;
+    kind: ChannelKind;
+    /** opaque version pointer for setting_sync (NOT ciphertext). */
+    changeToken?: string;
+}
+/** Encode a wakeup envelope to its canonical content-free byte form. */
+export declare function encodeWakeup(e: WakeupEnvelope): Uint8Array;
+/** Decode a wakeup envelope. Throws on unknown fields or malformed input. */
+export declare function decodeWakeup(b: Uint8Array): WakeupEnvelope;
+/**
+ * Opaque AEAD ciphertext + plaintext sync metadata. The server NEVER reads
+ * `ciphertext`. `version`/`updatedAt` are deliberately plaintext (they leak
+ * only THAT/WHEN a setting changed, not WHAT).
+ */
+export interface EncryptedBlob {
+    /** Base64url AEAD ciphertext of the client's JSON document. */
+    ciphertext: string;
+    /** Monotonic per (userId, namespace). Drives optimistic concurrency. */
+    version: number;
+    /** ISO-8601; server-assigned on write. */
+    updatedAt: string;
+}
+/**
+ * Result of `putSetting` — optimistic-concurrency outcome. Never throws on
+ * conflict; the caller (and ultimately the client) reconciles against
+ * `current`.
+ */
+export type PutResult = {
+    ok: true;
+    stored: EncryptedBlob;
+} | {
+    ok: false;
+    reason: "version_conflict";
+    current: EncryptedBlob;
+} | {
+    ok: false;
+    reason: "not_found";
+    current: null;
+};
+/**
+ * Minimal store port the transports use for blob sync. WS5 supplies
+ * `PrismaEncryptedSettingsStore`; WS1 ships `InMemorySettingStore` so core
+ * runs/tests with zero infra. Holds CIPHERTEXT ONLY.
+ *
+ * FROZEN (§2.5): do NOT add methods here. Offline-backfill (Track C) is layered
+ * as the SEPARATE optional `ChangeCursorStore` capability below so this contract
+ * stays byte-stable for every consumer bound to it.
+ */
+export interface SettingStore {
+    get(userId: string, namespace: string): Promise<EncryptedBlob | null>;
+    put(userId: string, namespace: string, blob: EncryptedBlob, expectVersion: number): Promise<PutResult>;
+}
+/**
+ * Metadata for ONE namespace whose version advanced past a client's cursor.
+ *
+ * SERVER-BLIND: deliberately carries NO `ciphertext`. It leaks only THAT/WHEN a
+ * namespace changed (already-plaintext sync metadata), never WHAT. A client that
+ * sees its namespace here re-pulls the blob over the authenticated GET. The
+ * absence of `ciphertext` is a TYPE-level guarantee, asserted by the tests.
+ */
+export interface ChangedSettingMeta {
+    namespace: string;
+    /** Monotonic per (userId, namespace) — the new high-watermark for this row. */
+    version: number;
+    /** ISO-8601 server-assigned write time. */
+    updatedAt: string;
+}
+/**
+ * OPTIONAL offline-backfill capability (Track C), layered ALONGSIDE the frozen
+ * `SettingStore` rather than baked into it. A store MAY also implement this to
+ * answer "which of my namespaces changed since I was last online?".
+ *
+ * The cursor (`sinceVersion`) is an opaque per-user version high-watermark: the
+ * largest `version` the client has already observed across ALL its namespaces.
+ * `listChangedSince` returns metadata for every namespace whose stored `version`
+ * is strictly greater than that watermark — METADATA ONLY, never `ciphertext`.
+ */
+export interface ChangeCursorStore {
+    listChangedSince(userId: string, sinceVersion: number): Promise<ChangedSettingMeta[]>;
+}
+/** Narrowing helper: does this store also provide the change-cursor capability? */
+export declare function supportsChangeCursor(store: SettingStore): store is SettingStore & ChangeCursorStore;
+/**
+ * The capability seam. Core ships `PollTransport` (default) + `NoopRealtimeTransport`
+ * (CI); a consuming app injects a concrete transport (e.g. Skybber's
+ * `AppSyncEventsTransport`) via `setRealtimeProvider()` WITHOUT core ever
+ * importing an AWS SDK.
+ *
+ * `subscribeInContext` is intentionally NOT part of the v1 freeze (in-context
+ * liveness is messaging-era; adding an optional method later is non-breaking).
+ */
+export interface RealtimeTransport {
+    readonly kind: "poll" | "appsync-events" | "noop";
+    /** Best-effort push. Runs the policy fence (floor) internally, every transport. */
+    deliver(target: DeliveryTarget, channel: Channel, payload: Uint8Array): Promise<DeliveryResult>;
+    getSetting(userId: string, namespace: string): Promise<EncryptedBlob | null>;
+    putSetting(userId: string, namespace: string, blob: EncryptedBlob, expectVersion: number): Promise<PutResult>;
+    shutdown?(): Promise<void>;
+}
+/** The policy port. WS1 ships `CalmDeliveryResolver`; WS3 may layer it. */
+export interface DeliveryPolicyResolver {
+    decide(ctx: DeliveryContext): DeliveryDecision;
+}
+//# sourceMappingURL=types.d.ts.map