@ultdai/pulse 0.1.0 → 0.2.0

package/README.md

@@ -7,25 +7,32 @@ npm install @ultdai/pulse
 ```
 
 ```ts
-import { CloudflareSdkConfigurationCache, UnlimitedClient } from '@ultdai/pulse'
+import {
+  CloudflareSdkConfigurationCache,
+  CloudflareSessionDecisionCache,
+  UnlimitedClient,
+} from '@ultdai/pulse'
 
 export interface Env { ULTD_API_TOKEN: string }
 
+let client: UnlimitedClient | undefined
+
 export default {
-  async fetch(request: Request, env: Env) {
+  async fetch(request: Request, env: Env, context: ExecutionContext) {
     const session = getPlaybackSession(request) // stabilní ID a čas vzniku v Unixových milisekundách
-    const client = new UnlimitedClient({
+    client ??= new UnlimitedClient({
       apiToken: env.ULTD_API_TOKEN,
       baseUrl: 'https://api.ultd.tivio.studio',
       cache: new CloudflareSdkConfigurationCache(caches.default),
+      sessionCache: new CloudflareSessionDecisionCache(caches.default),
       source: 'stream-worker',
     })
-    await client.emit({
+    context.waitUntil(client.emit({
       occurredAtMs: Date.now(),
       organizationId: 'tivio',
       pulse: {
-        type: 'stream.segment.requested',
-        version: 3,
+        type: 'playback.session.playing',
+        version: 1,
         id: session.id,
         payload: {
           sessionStartedAtMs: session.startedAtMs,
@@ -33,7 +40,7 @@ export default {
           ...(session.channelId ? { channelId: session.channelId } : {}),
         },
       },
-    })
+    }).catch((error) => console.error('ULTD pulse failed', error)))
     return new Response('ok')
   },
 }
@@ -41,6 +48,8 @@ export default {
 
 Klíč patří do serverového secretu, nikdy do klientského JavaScriptu. Konstruktor bez neprázdného `apiToken` skončí chybou ještě před síťovým voláním. Unlimited ověřuje klíč znovu na `GET /v1/sdk-config` i `POST /v1/pulses`; neplatný klíč nemůže zapsat puls.
 
-SDK dynamicky načítá seznam PulseTypes, jejich schémata, povolení sběru a sampling politiku při prvním `emit()`. Neznámý typ nebo nevalidní `pulse.payload` SDK odmítne lokálně. Vypnutý nebo nevzorkovaný puls neodešle. `occurredAtMs` a playback v3 `sessionStartedAtMs` jsou Unixové časy v milisekundách. Playback v2 se starším ISO polem `sessionStartedAt` zůstává podporován. Konfigurace má krátkou platnost a po jejím vypršení se obnovuje; pokud obnovení selže, puls se neodešle. Cloudflare cache je volitelná; bez ní SDK používá paměť instance.
+SDK dynamicky načítá seznam PulseTypes, jejich schémata, povolení sběru a sampling politiku při prvním `emit()`. Neznámý typ nebo nevalidní `pulse.payload` SDK odmítne lokálně. Vypnutý nebo nevzorkovaný puls neodešle. `occurredAtMs` a `sessionStartedAtMs` jsou Unixové časy v milisekundách. Konfigurace má krátkou platnost a po jejím vypršení se obnovuje; pokud obnovení selže, puls se neodešle. Cloudflare cache je volitelná; bez ní SDK používá paměť instance.
+
+U `playback.session.playing@1` SDK při prvním volání pro session odešle idempotentní `playback.session.started@1`. API vrátí rozhodnutí, zda se session dále měří. Vybraná session pak odešle heartbeat nejdříve po 60 sekundách nebo při změně videa; ostatní volání skončí lokálně. Po ztrátě cache SDK zopakuje start se stejným ID a obnoví původní rozhodnutí. Pevné ID session a čas začátku musí dodávat producent. API a Durable Object opakovaný start rozpoznají; cache je pouze optimalizace.
 
 SDK obsahuje interní kontrakty přibalené při buildu z monorepa. Aplikace instaluje jen `@ultdai/pulse` a jeho běžnou závislost `zod`; `@ultdai/contracts` se samostatně nevydává. Samotné zveřejnění SDK neposkytuje oprávnění k API.

package/dist/contracts/index.d.ts

@@ -156,6 +156,14 @@ export declare const PulseTypeDefinitionSchema: z.ZodObject<{
         reliable: "reliable";
     }>;
     id: z.ZodString;
+    lifecycle: z.ZodOptional<z.ZodObject<{
+        groupId: z.ZodString;
+        phase: z.ZodEnum<{
+            observe: "observe";
+            start: "start";
+        }>;
+        intervalMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
     sampling: z.ZodOptional<z.ZodObject<{
@@ -170,6 +178,7 @@ export declare const PulseTypeDefinitionSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const SignalReducerSchema: z.ZodEnum<{
     "distinct-per-window": "distinct-per-window";
+    lifecycle: "lifecycle";
     presence: "presence";
 }>;
 export declare const SignalTypeDefinitionSchema: z.ZodObject<{
@@ -179,6 +188,13 @@ export declare const SignalTypeDefinitionSchema: z.ZodObject<{
         version: z.ZodNumber;
     }, z.core.$strict>>;
     dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lifecycle: z.ZodOptional<z.ZodObject<{
+        intervalMs: z.ZodNumber;
+        scopeFields: z.ZodArray<z.ZodString>;
+        targetSampledPerScopeShard: z.ZodNumber;
+        timeoutMs: z.ZodNumber;
+        windowMs: z.ZodNumber;
+    }, z.core.$strict>>;
     partitionKey: z.ZodOptional<z.ZodString>;
     presence: z.ZodOptional<z.ZodObject<{
         immutableDimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -188,6 +204,7 @@ export declare const SignalTypeDefinitionSchema: z.ZodObject<{
     }, z.core.$strict>>;
     reducer: z.ZodEnum<{
         "distinct-per-window": "distinct-per-window";
+        lifecycle: "lifecycle";
         presence: "presence";
     }>;
     shardCount: z.ZodNumber;
@@ -282,8 +299,98 @@ export declare const RoutedMetricPulseSchema: z.ZodObject<{
         windowStartAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const LifecyclePulseTargetSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    groupId: z.ZodString;
+    intervalMs: z.ZodNumber;
+    organizationId: z.ZodString;
+    ownerId: z.ZodString;
+    phase: z.ZodEnum<{
+        observe: "observe";
+        start: "start";
+    }>;
+    refs: z.ZodArray<z.ZodObject<{
+        signalId: z.ZodString;
+        dimension: z.ZodString;
+    }, z.core.$strict>>;
+    scopeId: z.ZodString;
+    sessionStartedAt: z.ZodString;
+    shardCount: z.ZodNumber;
+    shardIndex: z.ZodNumber;
+    targetSampledPerScopeShard: z.ZodNumber;
+    timeoutMs: z.ZodNumber;
+    windowMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const RoutedLifecyclePulseSchema: z.ZodObject<{
+    pulse: z.ZodObject<{
+        data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        eventId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        organizationId: z.ZodString;
+        sampling: z.ZodDefault<z.ZodObject<{
+            applied: z.ZodBoolean;
+            appliedKeepProbability: z.ZodNumber;
+            effectiveKeepProbability: z.ZodNumber;
+            ingressApplied: z.ZodBoolean;
+            ingressKeepProbability: z.ZodNumber;
+            ingressMethod: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+            method: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            policyId: z.ZodNullable<z.ZodString>;
+            policyRevision: z.ZodNullable<z.ZodNumber>;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+        source: z.ZodString;
+        subject: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        type: z.ZodString;
+        typeVersion: z.ZodNumber;
+        occurredAt: z.ZodString;
+        receivedAt: z.ZodString;
+    }, z.core.$strict>;
+    target: z.ZodObject<{
+        generation: z.ZodNumber;
+        groupId: z.ZodString;
+        intervalMs: z.ZodNumber;
+        organizationId: z.ZodString;
+        ownerId: z.ZodString;
+        phase: z.ZodEnum<{
+            observe: "observe";
+            start: "start";
+        }>;
+        refs: z.ZodArray<z.ZodObject<{
+            signalId: z.ZodString;
+            dimension: z.ZodString;
+        }, z.core.$strict>>;
+        scopeId: z.ZodString;
+        sessionStartedAt: z.ZodString;
+        shardCount: z.ZodNumber;
+        shardIndex: z.ZodNumber;
+        targetSampledPerScopeShard: z.ZodNumber;
+        timeoutMs: z.ZodNumber;
+        windowMs: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const LifecycleDecisionSchema: z.ZodObject<{
+    accepted: z.ZodBoolean;
+    nextHeartbeatAtMs: z.ZodNumber;
+    probability: z.ZodNumber;
+    selected: z.ZodBoolean;
+}, z.core.$strict>;
 export declare const MetricSnapshotSchema: z.ZodObject<{
     estimatedCount: z.ZodNumber;
+    varianceEstimate: z.ZodOptional<z.ZodNumber>;
     generation: z.ZodNumber;
     kind: z.ZodEnum<{
         "distinct-per-window": "distinct-per-window";
@@ -322,6 +429,14 @@ export declare const SdkPulseTypeSchema: z.ZodObject<{
             reliable: "reliable";
         }>;
         id: z.ZodString;
+        lifecycle: z.ZodOptional<z.ZodObject<{
+            groupId: z.ZodString;
+            phase: z.ZodEnum<{
+                observe: "observe";
+                start: "start";
+            }>;
+            intervalMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
         payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
         sampling: z.ZodOptional<z.ZodObject<{
@@ -359,6 +474,14 @@ export declare const SdkConfigurationSchema: z.ZodObject<{
                 reliable: "reliable";
             }>;
             id: z.ZodString;
+            lifecycle: z.ZodOptional<z.ZodObject<{
+                groupId: z.ZodString;
+                phase: z.ZodEnum<{
+                    observe: "observe";
+                    start: "start";
+                }>;
+                intervalMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
             payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
             sampling: z.ZodOptional<z.ZodObject<{
@@ -395,6 +518,7 @@ export declare const LivePulseTargetSchema: z.ZodObject<{
     organizationId: z.ZodString;
     reducer: z.ZodEnum<{
         "distinct-per-window": "distinct-per-window";
+        lifecycle: "lifecycle";
         presence: "presence";
     }>;
     shardId: z.ZodString;
@@ -447,6 +571,7 @@ export declare const RoutedLivePulseSchema: z.ZodObject<{
         organizationId: z.ZodString;
         reducer: z.ZodEnum<{
             "distinct-per-window": "distinct-per-window";
+            lifecycle: "lifecycle";
             presence: "presence";
         }>;
         shardId: z.ZodString;
@@ -542,3 +667,6 @@ export type LiveShardSnapshot = z.infer<typeof LiveShardSnapshotSchema>;
 export type MetricPulseTarget = z.infer<typeof MetricPulseTargetSchema>;
 export type MetricSnapshot = z.infer<typeof MetricSnapshotSchema>;
 export type RoutedMetricPulse = z.infer<typeof RoutedMetricPulseSchema>;
+export type RoutedLifecyclePulse = z.infer<typeof RoutedLifecyclePulseSchema>;
+export type LifecyclePulseTarget = z.infer<typeof LifecyclePulseTargetSchema>;
+export type LifecycleDecision = z.infer<typeof LifecycleDecisionSchema>;

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import type { PulseSubmission } from './contracts/index.js';
 import type { SdkConfigurationCache } from './configurationCache.js';
+import type { SessionDecisionCache } from './sessionDecisionCache.js';
 export { CloudflareSdkConfigurationCache, MemorySdkConfigurationCache } from './configurationCache.js';
 export type { CachedSdkConfiguration, SdkConfigurationCache } from './configurationCache.js';
+export { CloudflareSessionDecisionCache, MemorySessionDecisionCache } from './sessionDecisionCache.js';
+export type { SessionDecision, SessionDecisionCache } from './sessionDecisionCache.js';
 export { CloudflareSamplingPolicyCache, MemorySamplingPolicyCache } from './cache.js';
 export type { CacheApiLike, SamplingPolicyCache } from './cache.js';
 export type SdkPulseInput = Omit<PulseSubmission, 'source' | 'sampling' | 'pulse'> & {
@@ -14,6 +17,7 @@ export interface UnlimitedClientOptions {
     baseUrl: string;
     source: string;
     cache?: SdkConfigurationCache;
+    sessionCache?: SessionDecisionCache;
     fetch?: typeof fetch;
     now?: () => Date;
     randomUUID?: () => string;
@@ -23,12 +27,18 @@ export interface EmitResult {
     disabled?: boolean;
     pulseId: string;
     sampledOut: boolean;
+    selected?: boolean;
+    throttled?: boolean;
+    probability?: number;
+    nextHeartbeatAtMs?: number;
 }
 export declare class UnlimitedClient {
     private readonly apiToken;
     private readonly baseUrl;
     private readonly source;
     private readonly cache;
+    private readonly sessionCache;
+    private readonly sessionMemory;
     private readonly fetcher;
     private readonly now;
     private readonly randomUUID;
@@ -39,5 +49,8 @@ export declare class UnlimitedClient {
     private install;
     private refresh;
     private configuration;
+    private decisionKey;
+    private getDecision;
+    private putDecision;
     emit(input: SdkPulseInput): Promise<EmitResult>;
 }

package/dist/index.js

@@ -178,6 +178,11 @@ var PulseDeliverySchema = z2.enum(["live", "reliable"]);
 var PulseTypeDefinitionSchema = z2.object({
   delivery: PulseDeliverySchema,
   id: z2.string().trim().min(1).max(100),
+  lifecycle: z2.object({
+    groupId: z2.string().trim().min(1).max(100),
+    phase: z2.enum(["start", "observe"]),
+    intervalMs: z2.number().int().min(1e3).max(864e5).optional()
+  }).strict().optional(),
   payloadSchema: z2.record(z2.string(), z2.unknown()),
   requiresExplicitId: z2.boolean().optional(),
   sampling: z2.object({
@@ -196,8 +201,11 @@ var PulseTypeDefinitionSchema = z2.object({
   if (definition.sampling?.unit === "pulse" && definition.sampling.keyField !== null) {
     context.addIssue({ code: "custom", path: ["sampling", "keyField"], message: "Pulse sampling must not define keyField." });
   }
+  if (definition.lifecycle && (definition.samplingAllowed || !definition.requiresExplicitId || definition.delivery !== "live" || definition.lifecycle.phase === "observe" !== Boolean(definition.lifecycle.intervalMs))) {
+    context.addIssue({ code: "custom", path: ["lifecycle"], message: "Lifecycle pulses need explicit IDs, live delivery, and an interval only for observations." });
+  }
 });
-var SignalReducerSchema = z2.enum(["presence", "distinct-per-window"]);
+var SignalReducerSchema = z2.enum(["presence", "distinct-per-window", "lifecycle"]);
 var SignalTypeDefinitionSchema = z2.object({
   id: z2.string().trim().min(1).max(100),
   inputPulseTypes: z2.array(z2.object({
@@ -205,6 +213,13 @@ var SignalTypeDefinitionSchema = z2.object({
     version: z2.number().int().positive()
   }).strict()).min(1),
   dimensions: z2.array(z2.string().trim().min(1).max(100)).optional(),
+  lifecycle: z2.object({
+    intervalMs: z2.number().int().min(1e3).max(864e5),
+    scopeFields: z2.array(z2.string().trim().min(1).max(100)).min(1),
+    targetSampledPerScopeShard: z2.number().int().positive(),
+    timeoutMs: z2.number().int().min(1e3).max(864e5),
+    windowMs: z2.number().int().min(1e3).max(864e5)
+  }).strict().optional(),
   partitionKey: z2.string().trim().min(1).max(200).optional(),
   presence: z2.object({
     immutableDimensions: z2.array(z2.string().trim().min(1).max(100)).optional(),
@@ -228,6 +243,9 @@ var SignalTypeDefinitionSchema = z2.object({
   if (definition.reducer === "distinct-per-window" && !definition.windowMs) {
     context.addIssue({ code: "custom", path: ["windowMs"], message: "Windowed distinct needs a window." });
   }
+  if (definition.reducer === "lifecycle" && (!definition.lifecycle || !definition.partitionKey || !definition.dimensions?.length)) {
+    context.addIssue({ code: "custom", path: ["lifecycle"], message: "Lifecycle needs a configuration, partition key and dimensions." });
+  }
   const schedule = definition.shardSchedule ?? [];
   if (schedule.length > 0 && (!definition.partitionKey || !definition.dimensions?.length)) {
     context.addIssue({ code: "custom", path: ["partitionKey"], message: "Scheduled routing needs partitionKey and dimensions." });
@@ -235,9 +253,10 @@ var SignalTypeDefinitionSchema = z2.object({
   if (schedule.length > 0 && definition.reducer === "presence" && !definition.presence?.startedAtField) {
     context.addIssue({ code: "custom", path: ["presence", "startedAtField"], message: "Scheduled presence needs a stable start time." });
   }
-  if (definition.windowMs) {
+  const scheduledWindowMs = definition.windowMs ?? definition.lifecycle?.windowMs;
+  if (scheduledWindowMs) {
     for (let index = 0; index < schedule.length; index += 1) {
-      if (Date.parse(schedule[index].effectiveFrom) % definition.windowMs !== 0) {
+      if (Date.parse(schedule[index].effectiveFrom) % scheduledWindowMs !== 0) {
         context.addIssue({ code: "custom", path: ["shardSchedule", index], message: "Window generation must start on a window boundary." });
       }
     }
@@ -282,8 +301,39 @@ var RoutedMetricPulseSchema = z2.object({
   pulse: RawPulseSchema,
   target: MetricPulseTargetSchema
 }).strict();
+var LifecyclePulseTargetSchema = z2.object({
+  generation: z2.number().int().positive(),
+  groupId: z2.string().trim().min(1).max(100),
+  intervalMs: z2.number().int().positive(),
+  organizationId: z2.string().trim().min(1).max(100),
+  ownerId: z2.string().trim().min(1).max(500),
+  phase: z2.enum(["start", "observe"]),
+  refs: z2.array(MetricSignalRefSchema).min(1),
+  scopeId: z2.string().trim().min(1).max(500),
+  sessionStartedAt: isoDateTime,
+  shardCount: z2.number().int().min(1).max(65536),
+  shardIndex: z2.number().int().nonnegative(),
+  targetSampledPerScopeShard: z2.number().int().positive(),
+  timeoutMs: z2.number().int().positive(),
+  windowMs: z2.number().int().positive()
+}).strict().superRefine((target, context) => {
+  if (target.shardIndex >= target.shardCount) {
+    context.addIssue({ code: "custom", path: ["shardIndex"], message: "Shard index exceeds shard count." });
+  }
+});
+var RoutedLifecyclePulseSchema = z2.object({
+  pulse: RawPulseSchema,
+  target: LifecyclePulseTargetSchema
+}).strict();
+var LifecycleDecisionSchema = z2.object({
+  accepted: z2.boolean(),
+  nextHeartbeatAtMs: z2.number().int().nonnegative(),
+  probability: z2.number().positive().max(1),
+  selected: z2.boolean()
+}).strict();
 var MetricSnapshotSchema = z2.object({
   estimatedCount: z2.number().finite().nonnegative(),
+  varianceEstimate: z2.number().finite().nonnegative().optional(),
   generation: z2.number().int().positive(),
   kind: z2.enum(["presence", "distinct-per-window"]),
   observedAt: isoDateTime,
@@ -435,6 +485,47 @@ var CloudflareSdkConfigurationCache = class {
   }
 };
 
+// src/sessionDecisionCache.ts
+var MemorySessionDecisionCache = class {
+  constructor(maxEntries = 1e4) {
+    this.maxEntries = maxEntries;
+  }
+  maxEntries;
+  values = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.values.get(key);
+  }
+  async set(key, decision) {
+    this.values.delete(key);
+    this.values.set(key, decision);
+    if (this.values.size > this.maxEntries) this.values.delete(this.values.keys().next().value);
+  }
+};
+var CloudflareSessionDecisionCache = class {
+  constructor(cache, namespace = "https://session-decision-cache.ultd.invalid") {
+    this.cache = cache;
+    this.namespace = namespace;
+  }
+  cache;
+  namespace;
+  request(key) {
+    return new Request(`${this.namespace}/${key}`);
+  }
+  async get(key) {
+    const response = await this.cache.match(this.request(key));
+    if (!response) return void 0;
+    const value = await response.json();
+    if (typeof value.expiresAtMs !== "number" || typeof value.nextHeartbeatAtMs !== "number" || typeof value.probability !== "number" || value.probability <= 0 || value.probability > 1 || typeof value.selected !== "boolean") return void 0;
+    return value;
+  }
+  async set(key, decision) {
+    const seconds = Math.max(1, Math.floor((decision.expiresAtMs - Date.now()) / 1e3));
+    await this.cache.put(this.request(key), new Response(JSON.stringify(decision), {
+      headers: { "cache-control": `public, max-age=${seconds}`, "content-type": "application/json" }
+    }));
+  }
+};
+
 // src/cache.ts
 var MemorySamplingPolicyCache = class {
   policies = /* @__PURE__ */ new Map();
@@ -499,6 +590,8 @@ var UnlimitedClient = class {
   baseUrl;
   source;
   cache;
+  sessionCache;
+  sessionMemory = new MemorySessionDecisionCache();
   fetcher;
   now;
   randomUUID;
@@ -516,6 +609,7 @@ var UnlimitedClient = class {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.source = options.source;
     this.cache = options.cache ?? new MemorySdkConfigurationCache();
+    this.sessionCache = options.sessionCache ?? this.sessionMemory;
     this.fetcher = options.fetch ?? fetch;
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.randomUUID = options.randomUUID ?? (() => crypto.randomUUID());
@@ -584,6 +678,28 @@ var UnlimitedClient = class {
     });
     return this.refreshing;
   }
+  async decisionKey(groupId, organizationId, sessionId) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(
+      `${await this.cacheKey}\0${groupId}\0${organizationId}\0${sessionId}`
+    ));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  async getDecision(key) {
+    const memory = await this.sessionMemory.get(key);
+    if (memory && memory.expiresAtMs > this.now().getTime()) return memory;
+    const cached = await this.sessionCache.get(key).catch(() => void 0);
+    if (cached && cached.expiresAtMs > this.now().getTime()) {
+      await this.sessionMemory.set(key, cached);
+      return cached;
+    }
+    return void 0;
+  }
+  async putDecision(key, decision) {
+    await this.sessionMemory.set(key, decision);
+    if (this.sessionCache !== this.sessionMemory) {
+      await this.sessionCache.set(key, decision).catch(() => void 0);
+    }
+  }
   async emit(input) {
     const loaded = await this.configuration();
     const type = loaded.types.get(typeKey(input.pulse.type, input.pulse.version));
@@ -602,9 +718,36 @@ var UnlimitedClient = class {
     if (!type.entry.enabled) {
       return { accepted: false, disabled: true, pulseId: id, sampledOut: false };
     }
+    const lifecycle = type.entry.definition.lifecycle;
+    const decisionKey = lifecycle ? await this.decisionKey(lifecycle.groupId, input.organizationId, id) : void 0;
+    if (lifecycle?.phase === "observe" && decisionKey) {
+      const decision = await this.getDecision(decisionKey);
+      if (!decision) {
+        const start = [...loaded.types.values()].find((candidate) => candidate.entry.definition.lifecycle?.groupId === lifecycle.groupId && candidate.entry.definition.lifecycle.phase === "start");
+        if (!start) throw new Error(`Lifecycle group ${lifecycle.groupId} has no start PulseType.`);
+        return this.emit({
+          ...input,
+          pulse: { ...input.pulse, type: start.entry.definition.id, version: start.entry.definition.version }
+        });
+      }
+      if (decision && !decision.selected) {
+        return { accepted: false, pulseId: id, sampledOut: true, selected: false, probability: decision.probability };
+      }
+      if (decision && this.now().getTime() < decision.nextHeartbeatAtMs && decision.lastVideoId === payload.videoId) {
+        return {
+          accepted: false,
+          pulseId: id,
+          sampledOut: false,
+          throttled: true,
+          selected: true,
+          probability: decision.probability,
+          nextHeartbeatAtMs: decision.nextHeartbeatAtMs
+        };
+      }
+    }
     const policy = type.entry.samplingPolicy;
     let sampling = NoSamplingContext;
-    if (policy) {
+    if (policy && !lifecycle) {
       sampling = {
         applied: policy.keepProbability < 1,
         appliedKeepProbability: policy.keepProbability,
@@ -639,6 +782,26 @@ var UnlimitedClient = class {
     });
     if (!response.ok) throw new Error(`Pulse request failed with ${response.status}.`);
     const body = await response.json();
+    if (lifecycle && decisionKey) {
+      if (typeof body.selected !== "boolean" || typeof body.probability !== "number" || body.probability <= 0 || body.probability > 1 || typeof body.nextHeartbeatAtMs !== "number") {
+        throw new Error("Lifecycle response did not contain a valid session decision.");
+      }
+      await this.putDecision(decisionKey, {
+        selected: body.selected,
+        probability: body.probability,
+        nextHeartbeatAtMs: body.nextHeartbeatAtMs,
+        lastVideoId: body.selected && typeof payload.videoId === "string" ? payload.videoId : void 0,
+        expiresAtMs: this.now().getTime() + 24 * 60 * 60 * 1e3
+      });
+      return {
+        accepted: body.accepted !== false,
+        pulseId: id,
+        sampledOut: lifecycle.phase === "observe" && !body.selected,
+        selected: body.selected,
+        probability: body.probability,
+        nextHeartbeatAtMs: body.nextHeartbeatAtMs
+      };
+    }
     return {
       accepted: body.accepted !== false,
       ...body.disabled === true ? { disabled: true } : {},
@@ -650,7 +813,9 @@ var UnlimitedClient = class {
 export {
   CloudflareSamplingPolicyCache,
   CloudflareSdkConfigurationCache,
+  CloudflareSessionDecisionCache,
   MemorySamplingPolicyCache,
   MemorySdkConfigurationCache,
+  MemorySessionDecisionCache,
   UnlimitedClient
 };

package/dist/sessionDecisionCache.d.ts

@@ -0,0 +1,28 @@
+import type { CacheApiLike } from './cache.js';
+export interface SessionDecision {
+    expiresAtMs: number;
+    lastVideoId?: string;
+    nextHeartbeatAtMs: number;
+    probability: number;
+    selected: boolean;
+}
+export interface SessionDecisionCache {
+    get(key: string): Promise<SessionDecision | undefined>;
+    set(key: string, decision: SessionDecision): Promise<void>;
+}
+export declare class MemorySessionDecisionCache implements SessionDecisionCache {
+    private readonly maxEntries;
+    private readonly values;
+    constructor(maxEntries?: number);
+    get(key: string): Promise<SessionDecision | undefined>;
+    set(key: string, decision: SessionDecision): Promise<void>;
+}
+/** Optional L2 cache; the Durable Object remains authoritative on a miss. */
+export declare class CloudflareSessionDecisionCache implements SessionDecisionCache {
+    private readonly cache;
+    private readonly namespace;
+    constructor(cache: CacheApiLike, namespace?: string);
+    private request;
+    get(key: string): Promise<SessionDecision | undefined>;
+    set(key: string, decision: SessionDecision): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultdai/pulse",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },