@plasius/analytics 1.3.3 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, h as SemanticJourneyOutcome, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-B7L9phdM.cjs';
2
- export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-B7L9phdM.cjs';
1
+ import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SemanticJourneyOutcome, h as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-DhAg1PSO.cjs';
2
+ export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-DhAg1PSO.cjs';
3
3
  import * as react from 'react';
4
4
  import { ReactNode } from 'react';
5
5
 
@@ -302,6 +302,104 @@ declare class SemanticJourneyAggregateStore {
302
302
  private sortedCounters;
303
303
  }
304
304
 
305
+ /** Opt-in aggregate wire version with explicitly registered finite views. */
306
+ declare const SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION: "2.1-aggregate";
307
+ /** Maximum accepted aggregate request size; hosts must also bound body reads. */
308
+ declare const SEMANTIC_JOURNEY_AGGREGATE_MAX_BYTES: number;
309
+ /** A reviewed application producer, never a runtime-constructed identity. */
310
+ interface SemanticJourneyAggregateBinding {
311
+ readonly source: string;
312
+ readonly channel: "frontend" | "backend";
313
+ readonly runtime: "browser" | "server";
314
+ }
315
+ /** Per-event independent views listing only existing finite enum attributes. */
316
+ interface SemanticJourneyAggregatePolicyOptions {
317
+ readonly bindings: readonly SemanticJourneyAggregateBinding[];
318
+ readonly projections?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
319
+ }
320
+ /** Validated, immutable contract shared by producers and the receiving service. */
321
+ interface SemanticJourneyAggregatePolicy {
322
+ readonly catalogue: SemanticJourneyCatalog;
323
+ readonly bindings: readonly SemanticJourneyAggregateBinding[];
324
+ readonly projections: NonNullable<SemanticJourneyAggregatePolicyOptions["projections"]>;
325
+ }
326
+ /** One independent view count; totals must never be summed across views. */
327
+ interface SemanticJourneyProjectedAggregateCounter extends SemanticJourneyAggregateCounter {
328
+ readonly view: string;
329
+ readonly dimensions: Readonly<Record<string, string>>;
330
+ }
331
+ /** An aggregate packet with no event-level evidence or private causal IDs. */
332
+ interface SemanticJourneyProjectedAggregateBatch extends Omit<SemanticJourneyAggregateBatch, "schemaVersion" | "counters"> {
333
+ readonly schemaVersion: typeof SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION;
334
+ readonly counters: readonly SemanticJourneyProjectedAggregateCounter[];
335
+ }
336
+ /** The two strict supported wire shapes; unrestricted legacy events are absent. */
337
+ type SemanticJourneyWireAggregateBatch = SemanticJourneyAggregateBatch | SemanticJourneyProjectedAggregateBatch;
338
+ /** Checks provenance, not just structural resemblance to a reviewed policy. */
339
+ declare function isSemanticJourneyAggregatePolicy(value: unknown): value is SemanticJourneyAggregatePolicy;
340
+ /** Compile immutable views and producer bindings from a strict event catalogue. */
341
+ declare function defineSemanticJourneyAggregatePolicy(catalogue: SemanticJourneyCatalog, options: SemanticJourneyAggregatePolicyOptions): SemanticJourneyAggregatePolicy;
342
+ /** Project only reviewed enums, never context, target, numeric values or IDs. */
343
+ declare function projectSemanticJourneyAggregateCounters(policy: SemanticJourneyAggregatePolicy, input: SemanticJourneyEventInput, increment?: number): readonly SemanticJourneyProjectedAggregateCounter[];
344
+ /** Stable view key, usable only after strict validation or projection. */
345
+ declare function semanticJourneyAggregateCounterKey(counter: SemanticJourneyAggregateCounter | SemanticJourneyProjectedAggregateCounter): string;
346
+ /** Generate a fail-closed wire validator from the producer's reviewed policy. */
347
+ declare function createSemanticJourneyAggregateValidator(policy: SemanticJourneyAggregatePolicy): (value: unknown) => value is SemanticJourneyWireAggregateBatch;
348
+
349
+ /** Host-owned limits for pending aggregate rows, independent of local stories. */
350
+ interface ProjectedSemanticJourneyAggregateStoreOptions extends SemanticJourneyAggregateBinding {
351
+ readonly policy: SemanticJourneyAggregatePolicy;
352
+ readonly maxPendingCounters?: number;
353
+ readonly maxPendingBytes?: number;
354
+ /** Batch ceiling, checked against every approved row before any capture. */
355
+ readonly maxBatchBytes?: number;
356
+ readonly maxAgeMs?: number;
357
+ readonly now?: () => number;
358
+ }
359
+ /**
360
+ * Holds a bounded set of independent aggregate views by original observation
361
+ * hour. One immutable retry snapshot is retained; no event IDs enter this store.
362
+ */
363
+ declare class ProjectedSemanticJourneyAggregateStore {
364
+ private readonly options;
365
+ private readonly maxCounters;
366
+ private readonly maxBytes;
367
+ private readonly maxBatchBytes;
368
+ private readonly minimumBatchBytes;
369
+ private readonly maxAge;
370
+ private readonly counters;
371
+ private pendingBytes;
372
+ private dropped;
373
+ private coalesced;
374
+ private diagnosticHour;
375
+ private diagnosticExpiry;
376
+ private pending;
377
+ constructor(options: ProjectedSemanticJourneyAggregateStoreOptions);
378
+ /** Return false on capacity pressure; never retain a partial set of views. */
379
+ recordEvent(input: SemanticJourneyEventInput, observedAt: number, increment?: number): boolean;
380
+ recordDropped(increment?: number): void;
381
+ recordCoalesced(increment?: number): void;
382
+ /** Read-only bounded diagnostics; never a persistence interface. */
383
+ snapshot(): Readonly<{
384
+ dropped: number;
385
+ coalesced: number;
386
+ pendingCounters: number;
387
+ pendingBytes: number;
388
+ counters: readonly SemanticJourneyProjectedAggregateCounter[];
389
+ }>;
390
+ createBatch(options: CreateSemanticJourneyAggregateBatchOptions): SemanticJourneyProjectedAggregateBatch | null;
391
+ /** Check retry eligibility without extending the original snapshot's expiry. */
392
+ isPendingBatch(batch: SemanticJourneyProjectedAggregateBatch, now: number): boolean;
393
+ /** Only the exact issued snapshot may subtract counts, and only once. */
394
+ acknowledge(batch: SemanticJourneyProjectedAggregateBatch): void;
395
+ /** Discard aggregates and in-flight snapshot ownership; never flush. */
396
+ clear(): void;
397
+ private now;
398
+ private diagnostic;
399
+ private prune;
400
+ private sorted;
401
+ }
402
+
305
403
  /** Bounded aggregate request passed to an injectable transport. */
306
404
  interface SemanticJourneyAggregateTransportRequest {
307
405
  readonly endpoint: string;
@@ -462,6 +560,8 @@ interface SemanticJourneyRequestLink {
462
560
  /** Configuration for a local-private semantic journey producer. */
463
561
  interface SemanticJourneyClientConfig {
464
562
  readonly catalogue: SemanticJourneyCatalog;
563
+ /** Opt in to reviewed 2.1 views; omitted retains strict 2.0 aggregate output. */
564
+ readonly aggregatePolicy?: SemanticJourneyAggregatePolicy;
465
565
  readonly source: string;
466
566
  readonly channel?: AnalyticsChannel;
467
567
  readonly runtime?: AnalyticsRuntime;
@@ -542,4 +642,4 @@ interface TrackInteractionDetails extends Omit<LocalSpaceAnalyticsEvent, "compon
542
642
  }
543
643
  declare function useComponentInteractionTracker(component: string, baseContext?: AnalyticsContext): (action: string, details?: TrackInteractionDetails) => void;
544
644
 
545
- export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
645
+ export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, ProjectedSemanticJourneyAggregateStore, type ProjectedSemanticJourneyAggregateStoreOptions, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_MAX_BYTES, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateBinding, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregatePolicy, type SemanticJourneyAggregatePolicyOptions, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyProjectedAggregateBatch, type SemanticJourneyProjectedAggregateCounter, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type SemanticJourneyWireAggregateBatch, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyAggregateValidator, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyAggregatePolicy, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticJourneyAggregatePolicy, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, projectSemanticJourneyAggregateCounters, reconstructSemanticJourney, semanticJourneyAggregateCounterKey, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, h as SemanticJourneyOutcome, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-B7L9phdM.js';
2
- export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-B7L9phdM.js';
1
+ import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SemanticJourneyOutcome, h as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-DhAg1PSO.js';
2
+ export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-DhAg1PSO.js';
3
3
  import * as react from 'react';
4
4
  import { ReactNode } from 'react';
5
5
 
@@ -302,6 +302,104 @@ declare class SemanticJourneyAggregateStore {
302
302
  private sortedCounters;
303
303
  }
304
304
 
305
+ /** Opt-in aggregate wire version with explicitly registered finite views. */
306
+ declare const SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION: "2.1-aggregate";
307
+ /** Maximum accepted aggregate request size; hosts must also bound body reads. */
308
+ declare const SEMANTIC_JOURNEY_AGGREGATE_MAX_BYTES: number;
309
+ /** A reviewed application producer, never a runtime-constructed identity. */
310
+ interface SemanticJourneyAggregateBinding {
311
+ readonly source: string;
312
+ readonly channel: "frontend" | "backend";
313
+ readonly runtime: "browser" | "server";
314
+ }
315
+ /** Per-event independent views listing only existing finite enum attributes. */
316
+ interface SemanticJourneyAggregatePolicyOptions {
317
+ readonly bindings: readonly SemanticJourneyAggregateBinding[];
318
+ readonly projections?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
319
+ }
320
+ /** Validated, immutable contract shared by producers and the receiving service. */
321
+ interface SemanticJourneyAggregatePolicy {
322
+ readonly catalogue: SemanticJourneyCatalog;
323
+ readonly bindings: readonly SemanticJourneyAggregateBinding[];
324
+ readonly projections: NonNullable<SemanticJourneyAggregatePolicyOptions["projections"]>;
325
+ }
326
+ /** One independent view count; totals must never be summed across views. */
327
+ interface SemanticJourneyProjectedAggregateCounter extends SemanticJourneyAggregateCounter {
328
+ readonly view: string;
329
+ readonly dimensions: Readonly<Record<string, string>>;
330
+ }
331
+ /** An aggregate packet with no event-level evidence or private causal IDs. */
332
+ interface SemanticJourneyProjectedAggregateBatch extends Omit<SemanticJourneyAggregateBatch, "schemaVersion" | "counters"> {
333
+ readonly schemaVersion: typeof SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION;
334
+ readonly counters: readonly SemanticJourneyProjectedAggregateCounter[];
335
+ }
336
+ /** The two strict supported wire shapes; unrestricted legacy events are absent. */
337
+ type SemanticJourneyWireAggregateBatch = SemanticJourneyAggregateBatch | SemanticJourneyProjectedAggregateBatch;
338
+ /** Checks provenance, not just structural resemblance to a reviewed policy. */
339
+ declare function isSemanticJourneyAggregatePolicy(value: unknown): value is SemanticJourneyAggregatePolicy;
340
+ /** Compile immutable views and producer bindings from a strict event catalogue. */
341
+ declare function defineSemanticJourneyAggregatePolicy(catalogue: SemanticJourneyCatalog, options: SemanticJourneyAggregatePolicyOptions): SemanticJourneyAggregatePolicy;
342
+ /** Project only reviewed enums, never context, target, numeric values or IDs. */
343
+ declare function projectSemanticJourneyAggregateCounters(policy: SemanticJourneyAggregatePolicy, input: SemanticJourneyEventInput, increment?: number): readonly SemanticJourneyProjectedAggregateCounter[];
344
+ /** Stable view key, usable only after strict validation or projection. */
345
+ declare function semanticJourneyAggregateCounterKey(counter: SemanticJourneyAggregateCounter | SemanticJourneyProjectedAggregateCounter): string;
346
+ /** Generate a fail-closed wire validator from the producer's reviewed policy. */
347
+ declare function createSemanticJourneyAggregateValidator(policy: SemanticJourneyAggregatePolicy): (value: unknown) => value is SemanticJourneyWireAggregateBatch;
348
+
349
+ /** Host-owned limits for pending aggregate rows, independent of local stories. */
350
+ interface ProjectedSemanticJourneyAggregateStoreOptions extends SemanticJourneyAggregateBinding {
351
+ readonly policy: SemanticJourneyAggregatePolicy;
352
+ readonly maxPendingCounters?: number;
353
+ readonly maxPendingBytes?: number;
354
+ /** Batch ceiling, checked against every approved row before any capture. */
355
+ readonly maxBatchBytes?: number;
356
+ readonly maxAgeMs?: number;
357
+ readonly now?: () => number;
358
+ }
359
+ /**
360
+ * Holds a bounded set of independent aggregate views by original observation
361
+ * hour. One immutable retry snapshot is retained; no event IDs enter this store.
362
+ */
363
+ declare class ProjectedSemanticJourneyAggregateStore {
364
+ private readonly options;
365
+ private readonly maxCounters;
366
+ private readonly maxBytes;
367
+ private readonly maxBatchBytes;
368
+ private readonly minimumBatchBytes;
369
+ private readonly maxAge;
370
+ private readonly counters;
371
+ private pendingBytes;
372
+ private dropped;
373
+ private coalesced;
374
+ private diagnosticHour;
375
+ private diagnosticExpiry;
376
+ private pending;
377
+ constructor(options: ProjectedSemanticJourneyAggregateStoreOptions);
378
+ /** Return false on capacity pressure; never retain a partial set of views. */
379
+ recordEvent(input: SemanticJourneyEventInput, observedAt: number, increment?: number): boolean;
380
+ recordDropped(increment?: number): void;
381
+ recordCoalesced(increment?: number): void;
382
+ /** Read-only bounded diagnostics; never a persistence interface. */
383
+ snapshot(): Readonly<{
384
+ dropped: number;
385
+ coalesced: number;
386
+ pendingCounters: number;
387
+ pendingBytes: number;
388
+ counters: readonly SemanticJourneyProjectedAggregateCounter[];
389
+ }>;
390
+ createBatch(options: CreateSemanticJourneyAggregateBatchOptions): SemanticJourneyProjectedAggregateBatch | null;
391
+ /** Check retry eligibility without extending the original snapshot's expiry. */
392
+ isPendingBatch(batch: SemanticJourneyProjectedAggregateBatch, now: number): boolean;
393
+ /** Only the exact issued snapshot may subtract counts, and only once. */
394
+ acknowledge(batch: SemanticJourneyProjectedAggregateBatch): void;
395
+ /** Discard aggregates and in-flight snapshot ownership; never flush. */
396
+ clear(): void;
397
+ private now;
398
+ private diagnostic;
399
+ private prune;
400
+ private sorted;
401
+ }
402
+
305
403
  /** Bounded aggregate request passed to an injectable transport. */
306
404
  interface SemanticJourneyAggregateTransportRequest {
307
405
  readonly endpoint: string;
@@ -462,6 +560,8 @@ interface SemanticJourneyRequestLink {
462
560
  /** Configuration for a local-private semantic journey producer. */
463
561
  interface SemanticJourneyClientConfig {
464
562
  readonly catalogue: SemanticJourneyCatalog;
563
+ /** Opt in to reviewed 2.1 views; omitted retains strict 2.0 aggregate output. */
564
+ readonly aggregatePolicy?: SemanticJourneyAggregatePolicy;
465
565
  readonly source: string;
466
566
  readonly channel?: AnalyticsChannel;
467
567
  readonly runtime?: AnalyticsRuntime;
@@ -542,4 +642,4 @@ interface TrackInteractionDetails extends Omit<LocalSpaceAnalyticsEvent, "compon
542
642
  }
543
643
  declare function useComponentInteractionTracker(component: string, baseContext?: AnalyticsContext): (action: string, details?: TrackInteractionDetails) => void;
544
644
 
545
- export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
645
+ export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, ProjectedSemanticJourneyAggregateStore, type ProjectedSemanticJourneyAggregateStoreOptions, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_MAX_BYTES, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_PROJECTED_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateBinding, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregatePolicy, type SemanticJourneyAggregatePolicyOptions, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyProjectedAggregateBatch, type SemanticJourneyProjectedAggregateCounter, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type SemanticJourneyWireAggregateBatch, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyAggregateValidator, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyAggregatePolicy, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticJourneyAggregatePolicy, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, projectSemanticJourneyAggregateCounters, reconstructSemanticJourney, semanticJourneyAggregateCounterKey, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };