@holonograph/client 0.4.0 → 0.5.0

package/README.md

@@ -93,6 +93,37 @@ status, an error code, and any details the lens returned.
 
 Everything is fully typed; the package ships its own type declarations.
 
+## Watching for changes
+
+Pull-side alerting, transport-agnostic. Poll any windowed lens read on a cadence
+and act only on the delta — a steady state is silent (the same "no all-quiet
+pings" discipline the lens applies to its own output). You supply the fetch and
+where the change goes; the client supplies the cadence and change-detection.
+
+- **`watchByKey({ poll, intervalMs, keyOf, onChange })`** — poll a collection and
+  fire `onChange(diff)` only when items are `added` / `removed` / `changed`
+  (matched by `keyOf`). Returns a handle with `.stop()`. The first poll silently
+  seeds the baseline, so you only hear about change since the watch started (pass
+  `emitInitial: true` for a cold-start inventory).
+- **`diffByKey(prev, next, keyOf)`** / **`hasChanges(diff)`** — the underlying
+  keyed diff, if you want change-detection without the loop.
+- **`createPoller({ poll, intervalMs, onResult })`** — the bare cadence loop
+  (non-overlapping; errors isolated to `onError`, never kill the watcher).
+- **`watchReconciliation(...)` / `watchEmission(...)`** — typed sugar over
+  `watchByKey` for the lens's reconciliation + emission reads.
+
+```ts
+import { watchByKey } from '@holonograph/client';
+
+const handle = watchByKey({
+  poll: (signal) => fetchReconciliation({ signal }), // your windowed read
+  intervalMs: 30_000,
+  keyOf: (row) => row.emissionStreamId,
+  onChange: (diff) => notifyOnCall(diff), // added / removed / changed only
+});
+// later: handle.stop();
+```
+
 ## Requirements
 
 This client does nothing on its own — it needs a **running Holonograph lens** to

package/dist/index.d.ts

@@ -1768,6 +1768,9 @@ declare enum ZodFirstPartyTypeKind {
 declare const RunModeSchema: ZodEnum<["production", "test", "eval", "replay", "local_dev"]>;
 type RunMode = TypeOf<typeof RunModeSchema>;
 
+declare const EmissionExpectationSchema: ZodEnum$1<["always", "conditional"]>;
+type EmissionExpectation = TypeOf$1<typeof EmissionExpectationSchema>;
+
 declare const SubstrateSnapshotSchema: ZodObject<{
  lensVersion: ZodString;
  lightSourceIdentifier: ZodString;
@@ -5932,6 +5935,22 @@ declare const LightSnapshotSchema: ZodObject<{
 
  rawResponsePresence: ZodOptional$1<ZodEnum$1<["present", "omitted-by-policy", "pending-attach", "failed-attach"]>>;
 }, "strip", ZodTypeAny$1, {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectOutputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -6110,8 +6129,10 @@ declare const LightSnapshotSchema: ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
+ rawRequestOmitted?: boolean | undefined;
+ rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
+}, {
  rawResponse?: unknown;
- reasoning?: string | undefined;
  toolCalls?: unknown[] | undefined;
  tokens?: {
  input?: number | undefined;
@@ -6120,15 +6141,13 @@ declare const LightSnapshotSchema: ZodObject<{
  cacheWrite?: number | undefined;
  } | undefined;
  latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
  error?: {
  message: string;
  type: string;
  vendorErrorCode?: string | undefined;
  } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
- rawRequestOmitted?: boolean | undefined;
- rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
-}, {
  rawRequest?: objectInputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -6307,22 +6326,6 @@ declare const LightSnapshotSchema: ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
 }>;
@@ -6392,7 +6395,7 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
 
  lensVersion: ZodString;
 
- kind: ZodDefault$1<ZodEnum$1<["evaluation", "availability.transition", "analysis.noise-floor-calibration", "analysis.variance-decomposition", "analysis.lifecycle-transition", "analysis.eval-recommendation", "analysis.conformance-fixture", "analysis.emission-coverage", "analysis.delivery-orphan"]>>;
+ kind: ZodDefault$1<ZodEnum$1<["evaluation", "availability.transition", "analysis.noise-floor-calibration", "analysis.variance-decomposition", "analysis.lifecycle-transition", "analysis.eval-recommendation", "analysis.conformance-fixture", "analysis.emission-coverage", "analysis.delivery-orphan", "analysis.orthogonality-hypothesis"]>>;
 
  light: ZodOptional$1<ZodObject<{
 
@@ -6974,6 +6977,22 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
 
  rawResponsePresence: ZodOptional$1<ZodEnum$1<["present", "omitted-by-policy", "pending-attach", "failed-attach"]>>;
  }, "strip", ZodTypeAny$1, {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectOutputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -7152,8 +7171,10 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
+ rawRequestOmitted?: boolean | undefined;
+ rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
+ }, {
  rawResponse?: unknown;
- reasoning?: string | undefined;
  toolCalls?: unknown[] | undefined;
  tokens?: {
  input?: number | undefined;
@@ -7162,15 +7183,13 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  cacheWrite?: number | undefined;
  } | undefined;
  latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
  error?: {
  message: string;
  type: string;
  vendorErrorCode?: string | undefined;
  } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
- rawRequestOmitted?: boolean | undefined;
- rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
- }, {
  rawRequest?: objectInputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -7349,22 +7368,6 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
  }>>;
@@ -8310,11 +8313,73 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  emissionStreamId: string;
  witnessedAtMs: number;
  }>>;
+
+ orthogonalityHypothesis: ZodOptional$1<ZodObject<{
+
+ draftId: ZodString;
+
+ targetSurfaceId: ZodString;
+
+ targetDimensionId: ZodString;
+
+ candidateColumnId: ZodString;
+
+ proposedHypothesis: ZodString;
+
+ evidence: ZodObject<{
+ scoredEventCount: ZodNumber;
+ sigmaObservedSquared: ZodNumber;
+ sigmaAgentSquared: ZodNumber;
+ sigmaAgentCILower: ZodNumber;
+ }, "strip", ZodTypeAny$1, {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ }, {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ }>;
+
+ approverId: ZodString;
+
+ occurredAt: ZodString;
+ }, "strip", ZodTypeAny$1, {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ }, {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ }>>;
 }, "strip", ZodTypeAny$1, {
  lensVersion: string;
  correlationId: string;
  surfaceId: string;
- kind: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan";
+ kind: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | "analysis.orthogonality-hypothesis";
  occurredAt: string;
  eventId: string;
  substrate?: {
@@ -8328,6 +8393,22 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  } | undefined;
  emissionStreamId?: string | undefined;
  light?: {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectOutputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -8506,22 +8587,6 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
  } | undefined;
@@ -8691,6 +8756,21 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  emissionStreamId: string;
  witnessedAtMs: number;
  } | undefined;
+ orthogonalityHypothesis?: {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ } | undefined;
 }, {
  lensVersion: string;
  correlationId: string;
@@ -8706,9 +8786,25 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  correlationId: string;
  columns: Record<string, string>;
  } | undefined;
- kind?: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | undefined;
+ kind?: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | "analysis.orthogonality-hypothesis" | undefined;
  emissionStreamId?: string | undefined;
  light?: {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectInputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -8887,22 +8983,6 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
  } | undefined;
@@ -9072,11 +9152,26 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  emissionStreamId: string;
  witnessedAtMs: number;
  } | undefined;
+ orthogonalityHypothesis?: {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ } | undefined;
 }>, {
  lensVersion: string;
  correlationId: string;
  surfaceId: string;
- kind: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan";
+ kind: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | "analysis.orthogonality-hypothesis";
  occurredAt: string;
  eventId: string;
  substrate?: {
@@ -9090,6 +9185,22 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  } | undefined;
  emissionStreamId?: string | undefined;
  light?: {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectOutputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -9268,22 +9379,6 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
  } | undefined;
@@ -9453,6 +9548,21 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  emissionStreamId: string;
  witnessedAtMs: number;
  } | undefined;
+ orthogonalityHypothesis?: {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ } | undefined;
 }, {
  lensVersion: string;
  correlationId: string;
@@ -9468,9 +9578,25 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  correlationId: string;
  columns: Record<string, string>;
  } | undefined;
- kind?: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | undefined;
+ kind?: "evaluation" | "availability.transition" | "analysis.noise-floor-calibration" | "analysis.variance-decomposition" | "analysis.lifecycle-transition" | "analysis.eval-recommendation" | "analysis.conformance-fixture" | "analysis.emission-coverage" | "analysis.delivery-orphan" | "analysis.orthogonality-hypothesis" | undefined;
  emissionStreamId?: string | undefined;
  light?: {
+ rawResponse?: unknown;
+ toolCalls?: unknown[] | undefined;
+ tokens?: {
+ input?: number | undefined;
+ output?: number | undefined;
+ cacheRead?: number | undefined;
+ cacheWrite?: number | undefined;
+ } | undefined;
+ latencyMs?: number | undefined;
+ reasoning?: string | undefined;
+ vendorMetadata?: Record<string, unknown> | undefined;
+ error?: {
+ message: string;
+ type: string;
+ vendorErrorCode?: string | undefined;
+ } | undefined;
  rawRequest?: objectInputType<{
  surfaceId: ZodString;
  correlationId: ZodOptional$1<ZodString>;
@@ -9649,22 +9775,6 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  strict: ZodOptional$1<ZodBoolean>;
  stream: ZodOptional$1<ZodBoolean>;
  }, ZodTypeAny$1, "passthrough"> | undefined;
- rawResponse?: unknown;
- reasoning?: string | undefined;
- toolCalls?: unknown[] | undefined;
- tokens?: {
- input?: number | undefined;
- output?: number | undefined;
- cacheRead?: number | undefined;
- cacheWrite?: number | undefined;
- } | undefined;
- latencyMs?: number | undefined;
- error?: {
- message: string;
- type: string;
- vendorErrorCode?: string | undefined;
- } | undefined;
- vendorMetadata?: Record<string, unknown> | undefined;
  rawRequestOmitted?: boolean | undefined;
  rawResponsePresence?: "present" | "omitted-by-policy" | "pending-attach" | "failed-attach" | undefined;
  } | undefined;
@@ -9834,6 +9944,21 @@ declare const EvaluationEventSchema: ZodEffects$1<ZodObject<{
  emissionStreamId: string;
  witnessedAtMs: number;
  } | undefined;
+ orthogonalityHypothesis?: {
+ approverId: string;
+ occurredAt: string;
+ draftId: string;
+ targetSurfaceId: string;
+ targetDimensionId: string;
+ candidateColumnId: string;
+ proposedHypothesis: string;
+ evidence: {
+ scoredEventCount: number;
+ sigmaObservedSquared: number;
+ sigmaAgentSquared: number;
+ sigmaAgentCILower: number;
+ };
+ } | undefined;
 }>;
 type EvaluationEvent = TypeOf$1<typeof EvaluationEventSchema>;
 
@@ -10074,6 +10199,7 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  output?: unknown;
  isError?: boolean | undefined;
  })[];
+ ok: true;
  tokens: {
  input: number;
  output: number;
@@ -10081,14 +10207,13 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  cacheWrite?: number | undefined;
  };
  latencyMs: number;
- ok: true;
  rawResponse?: unknown;
- reasoning?: string | undefined;
  toolCalls?: {
  toolUseId: string;
  toolName: string;
  input?: unknown;
  }[] | undefined;
+ reasoning?: string | undefined;
  vendorMetadata?: Record<string, unknown> | undefined;
  stopReason?: "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | "refusal" | "other" | undefined;
 }, {
@@ -10107,6 +10232,7 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  output?: unknown;
  isError?: boolean | undefined;
  })[];
+ ok: true;
  tokens: {
  input: number;
  output: number;
@@ -10114,14 +10240,13 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  cacheWrite?: number | undefined;
  };
  latencyMs: number;
- ok: true;
  rawResponse?: unknown;
- reasoning?: string | undefined;
  toolCalls?: {
  toolUseId: string;
  toolName: string;
  input?: unknown;
  }[] | undefined;
+ reasoning?: string | undefined;
  vendorMetadata?: Record<string, unknown> | undefined;
  stopReason?: "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | "refusal" | "other" | undefined;
 }>, ZodObject<{
@@ -10152,6 +10277,7 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
 
  vendorMetadata: ZodOptional$1<ZodRecord<ZodString, ZodUnknown>>;
 }, "strip", ZodTypeAny$1, {
+ ok: false;
  latencyMs: number;
  error: {
  message: string;
@@ -10159,10 +10285,10 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  retryable: boolean;
  vendorErrorCode?: string | undefined;
  };
- ok: false;
  rawResponse?: unknown;
  vendorMetadata?: Record<string, unknown> | undefined;
 }, {
+ ok: false;
  latencyMs: number;
  error: {
  message: string;
@@ -10170,7 +10296,6 @@ declare const LightSourceResultSchema: ZodDiscriminatedUnion<"ok", [ZodObject<{
  retryable: boolean;
  vendorErrorCode?: string | undefined;
  };
- ok: false;
  rawResponse?: unknown;
  vendorMetadata?: Record<string, unknown> | undefined;
 }>]>;
@@ -11049,6 +11174,92 @@ declare const LensAvailabilityMarkResponseSchema: ZodObject<{
 }>;
 type LensAvailabilityMarkResponse = TypeOf$1<typeof LensAvailabilityMarkResponseSchema>;
 
+interface LensReadWindow {
+ readonly since?: string;
+ readonly until?: string;
+}
+
+interface ReconciliationQuery extends LensReadWindow {
+ readonly emissionStreamId?: string;
+}
+
+interface EmissionAuditQuery extends LensReadWindow {
+ readonly surfaceId?: string;
+}
+
+interface EmitterReconciliation {
+ readonly emissionStreamId: string;
+
+ readonly persisted: number;
+
+ readonly dark: number;
+
+ readonly total: number;
+
+ readonly completeness: number;
+
+ readonly darkEventIds: readonly string[];
+}
+
+interface ReconciliationSummary {
+ readonly emitterCount: number;
+ readonly totalPersisted: number;
+ readonly totalDark: number;
+
+ readonly overallCompleteness: number;
+}
+
+interface ReconciliationReport {
+ readonly emitters: readonly EmitterReconciliation[];
+ readonly summary: ReconciliationSummary;
+}
+
+interface ReconciliationResponse extends ReconciliationReport {
+ readonly since?: string;
+ readonly until?: string;
+}
+
+type ColumnEmissionVerdict = 'no-data' | 'ok' | 'partial' | 'expectation-mismatch' | 'missing' | 'present' | 'absent';
+interface ColumnEmissionByDay {
+
+ readonly date: string;
+
+ readonly populated: number;
+
+ readonly total: number;
+}
+interface ColumnEmissionRow {
+ readonly columnId: string;
+
+ readonly emissionExpectation: EmissionExpectation;
+
+ readonly populated: number;
+
+ readonly total: number;
+
+ readonly verdict: ColumnEmissionVerdict;
+
+ readonly byDay: readonly ColumnEmissionByDay[];
+
+ readonly firstEmittedAt: string | null;
+ readonly lastEmittedAt: string | null;
+}
+interface SurfaceColumnEmission {
+ readonly surfaceId: string;
+
+ readonly total: number;
+
+ readonly columns: readonly ColumnEmissionRow[];
+
+ readonly undeclaredObserved: readonly string[];
+}
+
+interface EmissionAuditResponse {
+ readonly since?: string;
+ readonly until?: string;
+ readonly surfaces: readonly SurfaceColumnEmission[];
+}
+
 interface HolonographCallHandle {
 
  result: MediatorCallResult | GateExecutionResult;
@@ -11223,6 +11434,10 @@ interface Transport {
 
  getContract?(): Promise<ContractRegisterResponse>;
 
+ getReconciliation?(query?: ReconciliationQuery): Promise<ReconciliationResponse>;
+
+ getEmission?(query?: EmissionAuditQuery): Promise<EmissionAuditResponse>;
+
  markAvailability?(req: LensAvailabilityMarkRequest): Promise<LensAvailabilityMarkResponse>;
 }
 
@@ -11265,12 +11480,112 @@ declare class HttpTransport implements Transport {
  shutdown(): Promise<void>;
  postContract(contract: SurfaceContract): Promise<ContractRegisterResponse>;
  getContract(): Promise<ContractRegisterResponse>;
+ getReconciliation(query?: ReconciliationQuery): Promise<ReconciliationResponse>;
+ getEmission(query?: EmissionAuditQuery): Promise<EmissionAuditResponse>;
  markAvailability(req: LensAvailabilityMarkRequest): Promise<LensAvailabilityMarkResponse>;
  private post;
 
  private get;
 }
 
+interface KeyedDiff<T> {
+
+ added: T[];
+
+ removed: T[];
+
+ changed: {
+ key: string;
+ prev: T;
+ next: T;
+ }[];
+
+ unchanged: T[];
+}
+
+declare function hasChanges<T>(diff: KeyedDiff<T>): boolean;
+
+declare function diffByKey<T>(prev: readonly T[], next: readonly T[], keyOf: (item: T) => string, opts?: {
+ equals?: (a: T, b: T) => boolean;
+}): KeyedDiff<T>;
+
+interface PollerHandle {
+
+ stop(): void;
+}
+interface PollerOptions<T> {
+
+ poll: (signal: AbortSignal) => Promise<T>;
+
+ intervalMs: number;
+
+ onResult: (result: T) => void | Promise<void>;
+
+ onError?: (err: unknown) => void;
+
+ signal?: AbortSignal;
+
+ immediate?: boolean;
+}
+
+declare function createPoller<T>(opts: PollerOptions<T>): PollerHandle;
+interface WatchByKeyOptions<T> {
+
+ poll: (signal: AbortSignal) => Promise<readonly T[]>;
+
+ intervalMs: number;
+
+ keyOf: (item: T) => string;
+
+ onChange: (diff: KeyedDiff<T>) => void | Promise<void>;
+
+ equals?: (a: T, b: T) => boolean;
+
+ onError?: (err: unknown) => void;
+
+ signal?: AbortSignal;
+
+ emitInitial?: boolean;
+}
+
+declare function watchByKey<T>(opts: WatchByKeyOptions<T>): PollerHandle;
+
+interface ReconciliationReader {
+ getReconciliation(query?: ReconciliationQuery): Promise<ReconciliationResponse>;
+}
+
+interface EmissionReader {
+ getEmission(query?: EmissionAuditQuery): Promise<EmissionAuditResponse>;
+}
+interface CommonWatchOptions {
+ intervalMs: number;
+ onError?: (err: unknown) => void;
+ signal?: AbortSignal;
+ emitInitial?: boolean;
+}
+interface WatchReconciliationOptions extends CommonWatchOptions {
+ reader: ReconciliationReader;
+
+ query?: ReconciliationQuery;
+
+ onChange: (diff: KeyedDiff<EmitterReconciliation>) => void | Promise<void>;
+
+ equals?: (a: EmitterReconciliation, b: EmitterReconciliation) => boolean;
+}
+
+declare function watchReconciliation(opts: WatchReconciliationOptions): PollerHandle;
+interface WatchEmissionOptions extends CommonWatchOptions {
+ reader: EmissionReader;
+
+ query?: EmissionAuditQuery;
+
+ onChange: (diff: KeyedDiff<SurfaceColumnEmission>) => void | Promise<void>;
+
+ equals?: (a: SurfaceColumnEmission, b: SurfaceColumnEmission) => boolean;
+}
+
+declare function watchEmission(opts: WatchEmissionOptions): PollerHandle;
+
 interface HolonographClientOptions {
 
  endpoint: string;
@@ -11315,5 +11630,5 @@ interface HolonographClient {
 
 declare const HolonographClient: new (options: HolonographClientOptions) => HolonographClient;
 
-export { HolonographClient, HolonographGradeAfterReportError, HolonographHttpError, HolonographMarkerPairingWarningError, HolonographNoObserversError, HolonographObserverNotFoundError, HttpTransport };
-export type { AvailabilityMarkOptions, CompletenessWindow, ContractRegisterResponse, ContractSurfaceSummary, EmitChannel, EmitChannelCompleteness, EmitMode, EmitOptions, ExtremeSustainedLoadEvent, HolonographCallHandle, HolonographClientOptions, HolonographMessageRequest as HolonographMessageRequest, HolonographMessageResponse as HolonographMessageResponse, HttpTransportOptions, MediatorCallRequest, OtlpEmitConfig, SurfaceOutcomeReport };
+export { HolonographClient, HolonographGradeAfterReportError, HolonographHttpError, HolonographMarkerPairingWarningError, HolonographNoObserversError, HolonographObserverNotFoundError, HttpTransport, createPoller, diffByKey, hasChanges, watchByKey, watchEmission, watchReconciliation };
+export type { AvailabilityMarkOptions, CompletenessWindow, ContractRegisterResponse, ContractSurfaceSummary, EmissionReader, EmitChannel, EmitChannelCompleteness, EmitMode, EmitOptions, ExtremeSustainedLoadEvent, HolonographCallHandle, HolonographClientOptions, HolonographMessageRequest as HolonographMessageRequest, HolonographMessageResponse as HolonographMessageResponse, HttpTransportOptions, KeyedDiff, MediatorCallRequest, OtlpEmitConfig, PollerHandle, PollerOptions, ReconciliationReader, SurfaceOutcomeReport, WatchByKeyOptions, WatchEmissionOptions, WatchReconciliationOptions };

package/dist/index.js

@@ -4064,7 +4064,9 @@ var SYSTEM_ROLE_SURFACE_IDS = {
 
  conformanceClerk: "system:conformance-clerk",
 
- blastRadiusJudge: "system:blast-radius-judging"
+ blastRadiusJudge: "system:blast-radius-judging",
+
+ orthogonalityHypothesisDrafter: "system:orthogonality-hypothesis-drafting"
 };
 var PLATFORM_SYSTEM_ROLE_SURFACES = [
  {
@@ -4081,6 +4083,11 @@ var PLATFORM_SYSTEM_ROLE_SURFACES = [
  role: "judge",
  surfaceId: SYSTEM_ROLE_SURFACE_IDS.blastRadiusJudge,
  label: "blast-radius-judge"
+ },
+ {
+ role: "clerk",
+ surfaceId: SYSTEM_ROLE_SURFACE_IDS.orthogonalityHypothesisDrafter,
+ label: "orthogonality-hypothesis-drafter"
  }
 ];
 new Set(
@@ -4771,7 +4778,9 @@ var EvaluationEventKindSchema = external_exports.enum([
 
  "analysis.emission-coverage",
 
- "analysis.delivery-orphan"
+ "analysis.delivery-orphan",
+
+ "analysis.orthogonality-hypothesis"
 ]);
 var AvailabilityTransitionDirectionSchema = external_exports.enum([
  "reachable->unreachable",
@@ -4947,6 +4956,29 @@ var ConformanceFixtureRecordSchema = external_exports.object({
 
  sourceSurfaceId: external_exports.string().min(1).optional()
 });
+var OrthogonalityHypothesisRecordSchema = external_exports.object({
+
+ draftId: external_exports.string().min(1),
+
+ targetSurfaceId: external_exports.string().min(1),
+
+ targetDimensionId: external_exports.string().min(1),
+
+ candidateColumnId: external_exports.string().min(1),
+
+ proposedHypothesis: external_exports.string().min(1),
+
+ evidence: external_exports.object({
+ scoredEventCount: external_exports.number().int().nonnegative(),
+ sigmaObservedSquared: external_exports.number().nonnegative(),
+ sigmaAgentSquared: external_exports.number().nonnegative(),
+ sigmaAgentCILower: external_exports.number().nonnegative()
+ }),
+
+ approverId: external_exports.string().min(1),
+
+ occurredAt: external_exports.string().min(1)
+});
 var EmissionCoverageSchema = external_exports.object({
 
  streamId: external_exports.string().min(1),
@@ -5005,37 +5037,42 @@ var EvaluationEventSchema = external_exports.object({
 
  emissionCoverage: EmissionCoverageSchema.optional(),
 
- deliveryOrphan: DeliveryOrphanSchema.optional()
+ deliveryOrphan: DeliveryOrphanSchema.optional(),
+
+ orthogonalityHypothesis: OrthogonalityHypothesisRecordSchema.optional()
 }).refine(
  (e) => {
  if (e.kind === "evaluation") {
- return e.light !== void 0 && e.substrate !== void 0 && e.surface !== void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.light !== void 0 && e.substrate !== void 0 && e.surface !== void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "availability.transition") {
- return e.availability !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.availability !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.noise-floor-calibration") {
- return e.noiseFloorCalibration !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.noiseFloorCalibration !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.variance-decomposition") {
- return e.varianceDecomposition !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.varianceDecomposition !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.lifecycle-transition") {
- return e.lifecycleTransition !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.lifecycleTransition !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.eval-recommendation") {
- return e.evalRecommendation !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.evalRecommendation !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.conformanceFixtureRecord === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.conformance-fixture") {
- return e.conformanceFixtureRecord !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0;
+ return e.conformanceFixtureRecord !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.emissionCoverage === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
  }
  if (e.kind === "analysis.emission-coverage") {
- return e.emissionCoverage !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.deliveryOrphan === void 0;
+ return e.emissionCoverage !== void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.deliveryOrphan === void 0 && e.orthogonalityHypothesis === void 0;
+ }
+ if (e.kind === "analysis.delivery-orphan") {
+ return e.deliveryOrphan !== void 0 && e.emissionCoverage === void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0 && e.orthogonalityHypothesis === void 0;
  }
- return e.deliveryOrphan !== void 0 && e.emissionCoverage === void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0;
+ return e.orthogonalityHypothesis !== void 0 && e.deliveryOrphan === void 0 && e.emissionCoverage === void 0 && e.light === void 0 && e.substrate === void 0 && e.surface === void 0 && e.availability === void 0 && e.noiseFloorCalibration === void 0 && e.varianceDecomposition === void 0 && e.lifecycleTransition === void 0 && e.evalRecommendation === void 0 && e.conformanceFixtureRecord === void 0;
  },
  {
- message: "EvaluationEvent shape invariant: each kind requires exactly its corresponding payload and forbids the others. kind='evaluation' \u2192 light+substrate+surface; kind='availability.transition' \u2192 availability; kind='analysis.noise-floor-calibration' \u2192 noiseFloorCalibration; kind='analysis.variance-decomposition' \u2192 varianceDecomposition; kind='analysis.lifecycle-transition' \u2192 lifecycleTransition; kind='analysis.eval-recommendation' \u2192 evalRecommendation; kind='analysis.conformance-fixture' \u2192 conformanceFixtureRecord; kind='analysis.emission-coverage' \u2192 emissionCoverage; kind='analysis.delivery-orphan' \u2192 deliveryOrphan."
+ message: "EvaluationEvent shape invariant: each kind requires exactly its corresponding payload and forbids the others. kind='evaluation' \u2192 light+substrate+surface; kind='availability.transition' \u2192 availability; kind='analysis.noise-floor-calibration' \u2192 noiseFloorCalibration; kind='analysis.variance-decomposition' \u2192 varianceDecomposition; kind='analysis.lifecycle-transition' \u2192 lifecycleTransition; kind='analysis.eval-recommendation' \u2192 evalRecommendation; kind='analysis.conformance-fixture' \u2192 conformanceFixtureRecord; kind='analysis.emission-coverage' \u2192 emissionCoverage; kind='analysis.delivery-orphan' \u2192 deliveryOrphan; kind='analysis.orthogonality-hypothesis' \u2192 orthogonalityHypothesis."
  }
 );
 function newEventId(occurredAt = new Date()) {
@@ -5578,8 +5615,10 @@ var EvaluationEventEmitter = class {
  }, opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
  this.stopSentinelInterval = this.emitsSentinels ? schedule(() => {
  this.sentinelTick();
- }, opts.sentinelIntervalMs ?? DEFAULT_SENTINEL_INTERVAL_MS) : () => {
- };
+ }, opts.sentinelIntervalMs ?? DEFAULT_SENTINEL_INTERVAL_MS) : (
+
+ () => void 0
+ );
  }
 
  enqueue(event) {
@@ -6068,6 +6107,18 @@ var HttpTransport = class {
  async getContract() {
  return this.get("/holonograph/contract");
  }
+ async getReconciliation(query = {}) {
+ const { since, until, emissionStreamId } = query;
+ return this.get(
+ `/holonograph/reconciliation${toQueryString({ since, until, emissionStreamId })}`
+ );
+ }
+ async getEmission(query = {}) {
+ const { since, until, surfaceId } = query;
+ return this.get(
+ `/holonograph/emission${toQueryString({ since, until, surfaceId })}`
+ );
+ }
  async markAvailability(req) {
  return this.post("/lens/availability/mark", req);
  }
@@ -6175,6 +6226,14 @@ function lightSnapshotFromResult(result) {
  }
  return snapshot;
 }
+function toQueryString(query) {
+ const params = new URLSearchParams();
+ for (const [k, v] of Object.entries(query)) {
+ if (v !== void 0) params.set(k, v);
+ }
+ const s = params.toString();
+ return s.length > 0 ? `?${s}` : "";
+}
 
 function isHttpOptions(opts) {
  return "endpoint" in opts;
@@ -6524,6 +6583,128 @@ var HolonographClient = class {
  }
 };
 
+function hasChanges(diff) {
+ return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+function structuralEquals(a, b) {
+ if (a === b) return true;
+ try {
+ return JSON.stringify(a) === JSON.stringify(b);
+ } catch {
+ return false;
+ }
+}
+function diffByKey(prev, next, keyOf, opts = {}) {
+ const equals = opts.equals ?? structuralEquals;
+ const prevByKey = new Map();
+ for (const item of prev) prevByKey.set(keyOf(item), item);
+ const nextByKey = new Map();
+ for (const item of next) nextByKey.set(keyOf(item), item);
+ const diff = { added: [], removed: [], changed: [], unchanged: [] };
+ for (const [key, nextItem] of nextByKey) {
+ const prevItem = prevByKey.get(key);
+ if (prevItem === void 0) {
+ diff.added.push(nextItem);
+ } else if (equals(prevItem, nextItem)) {
+ diff.unchanged.push(nextItem);
+ } else {
+ diff.changed.push({ key, prev: prevItem, next: nextItem });
+ }
+ }
+ for (const [key, prevItem] of prevByKey) {
+ if (!nextByKey.has(key)) diff.removed.push(prevItem);
+ }
+ return diff;
+}
+
+function createPoller(opts) {
+ const { poll, intervalMs, onResult, onError, signal, immediate = true } = opts;
+ let timer;
+ const controller = new AbortController();
+ const stopped = () => controller.signal.aborted;
+ const stop = () => {
+ if (stopped()) return;
+ if (timer !== void 0) clearTimeout(timer);
+ controller.abort();
+ };
+ if (signal !== void 0) {
+ if (signal.aborted) {
+ stop();
+ return { stop };
+ }
+ signal.addEventListener("abort", stop, { once: true });
+ }
+ const scheduleNext = () => {
+ if (stopped()) return;
+ timer = setTimeout(() => void tick(), intervalMs);
+ };
+ const tick = async () => {
+ if (stopped()) return;
+ try {
+ const result = await poll(controller.signal);
+ if (stopped()) return;
+ await onResult(result);
+ } catch (err) {
+ if (!stopped()) onError?.(err);
+ }
+ scheduleNext();
+ };
+ if (immediate) void tick();
+ else scheduleNext();
+ return { stop };
+}
+function watchByKey(opts) {
+ const { poll, intervalMs, keyOf, onChange, equals, onError, signal, emitInitial = false } = opts;
+ const diffOpts = equals !== void 0 ? { equals } : {};
+ let baseline;
+ return createPoller({
+ poll,
+ intervalMs,
+ ...onError !== void 0 ? { onError } : {},
+ ...signal !== void 0 ? { signal } : {},
+ onResult: async (next) => {
+ if (baseline === void 0) {
+ baseline = next;
+ if (emitInitial) {
+ const diff2 = diffByKey([], next, keyOf, diffOpts);
+ if (hasChanges(diff2)) await onChange(diff2);
+ }
+ return;
+ }
+ const diff = diffByKey(baseline, next, keyOf, diffOpts);
+ baseline = next;
+ if (hasChanges(diff)) await onChange(diff);
+ }
+ });
+}
+
+function watchReconciliation(opts) {
+ const { reader, query, intervalMs, onChange, equals, onError, signal, emitInitial } = opts;
+ return watchByKey({
+ intervalMs,
+ onChange,
+ keyOf: (e) => e.emissionStreamId,
+ poll: async () => (await reader.getReconciliation(query)).emitters,
+ ...equals !== void 0 ? { equals } : {},
+ ...onError !== void 0 ? { onError } : {},
+ ...signal !== void 0 ? { signal } : {},
+ ...emitInitial !== void 0 ? { emitInitial } : {}
+ });
+}
+function watchEmission(opts) {
+ const { reader, query, intervalMs, onChange, equals, onError, signal, emitInitial } = opts;
+ return watchByKey({
+ intervalMs,
+ onChange,
+ keyOf: (s) => s.surfaceId,
+ poll: async () => (await reader.getEmission(query)).surfaces,
+ ...equals !== void 0 ? { equals } : {},
+ ...onError !== void 0 ? { onError } : {},
+ ...signal !== void 0 ? { signal } : {},
+ ...emitInitial !== void 0 ? { emitInitial } : {}
+ });
+}
+
 var HolonographClient2 = HolonographClient;
 
-export { HolonographClient2 as HolonographClient, HolonographGradeAfterReportError, HolonographHttpError, HolonographMarkerPairingWarningError, HolonographNoObserversError, HolonographObserverNotFoundError, HttpTransport };
+export { HolonographClient2 as HolonographClient, HolonographGradeAfterReportError, HolonographHttpError, HolonographMarkerPairingWarningError, HolonographNoObserversError, HolonographObserverNotFoundError, HttpTransport, createPoller, diffByKey, hasChanges, watchByKey, watchEmission, watchReconciliation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holonograph/client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript HTTP client for a Holonograph lens. Send messages through the lens and report scored outcomes back to it.",
   "license": "MIT",
   "type": "module",