@holonograph/client 0.3.0 → 0.5.0

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(
@@ -4769,7 +4776,11 @@ var EvaluationEventKindSchema = external_exports.enum([
 
  "analysis.conformance-fixture",
 
- "analysis.emission-coverage"
+ "analysis.emission-coverage",
+
+ "analysis.delivery-orphan",
+
+ "analysis.orthogonality-hypothesis"
 ]);
 var AvailabilityTransitionDirectionSchema = external_exports.enum([
  "reachable->unreachable",
@@ -4945,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),
@@ -4957,6 +4991,16 @@ var EmissionCoverageSchema = external_exports.object({
 
  observedAtMs: external_exports.number().int().nonnegative()
 });
+var DeliveryOrphanSchema = external_exports.object({
+
+ darkEventId: external_exports.string().min(1),
+
+ emissionStreamId: external_exports.string().min(1),
+
+ surfaceId: external_exports.string().min(1),
+
+ witnessedAtMs: external_exports.number().int().nonnegative()
+});
 var EvaluationEventSchema = external_exports.object({
 
  eventId: external_exports.string().min(1),
@@ -4967,6 +5011,8 @@ var EvaluationEventSchema = external_exports.object({
 
  correlationId: CorrelationIdSchema,
 
+ emissionStreamId: external_exports.string().min(1).optional(),
+
  lensVersion: external_exports.string().min(1),
 
  kind: EvaluationEventKindSchema.default("evaluation"),
@@ -4989,34 +5035,44 @@ var EvaluationEventSchema = external_exports.object({
 
  conformanceFixtureRecord: ConformanceFixtureRecordSchema.optional(),
 
- emissionCoverage: EmissionCoverageSchema.optional()
+ emissionCoverage: EmissionCoverageSchema.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;
+ 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;
+ 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;
+ 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;
+ 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;
+ 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;
+ 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;
+ 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 && 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.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."
+ 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()) {
@@ -5527,6 +5583,8 @@ var EvaluationEventEmitter = class {
 
  lastSeq = -1;
 
+ emitsSentinels;
+
  inFlight = null;
  stopped = false;
  constructor(opts) {
@@ -5538,6 +5596,7 @@ var EvaluationEventEmitter = class {
  this.sentinelTargets = this.flushTargets.filter((t) => typeof t.emitSentinel === "function");
  this.now = opts.now ?? Date.now;
  this.streamId = opts.streamId ?? generateStreamId(this.now());
+ this.emitsSentinels = opts.deployment !== "serverless";
  this.onFlushError = opts.onFlushError ?? ((error) => {
  console.warn("[holonograph] emit flush error:", error);
  });
@@ -5554,9 +5613,12 @@ var EvaluationEventEmitter = class {
  this.stopInterval = schedule(() => {
  this.tick();
  }, opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
- this.stopSentinelInterval = schedule(() => {
+ this.stopSentinelInterval = this.emitsSentinels ? schedule(() => {
  this.sentinelTick();
- }, opts.sentinelIntervalMs ?? DEFAULT_SENTINEL_INTERVAL_MS);
+ }, opts.sentinelIntervalMs ?? DEFAULT_SENTINEL_INTERVAL_MS) : (
+
+ () => void 0
+ );
  }
 
  enqueue(event) {
@@ -5564,7 +5626,8 @@ var EvaluationEventEmitter = class {
  const seq = this.nextSeq;
  this.nextSeq += 1;
  this.lastSeq = seq;
- const accepted = this.buffer.offer({ event, seq, streamId: this.streamId });
+ const stamped = event.emissionStreamId === void 0 ? { ...event, emissionStreamId: this.streamId } : event;
+ const accepted = this.buffer.offer({ event: stamped, seq, streamId: this.streamId });
  this.accounting.recordOffer(nowMs, accepted);
  this.accounting.maybeRollover(nowMs);
  return event.eventId;
@@ -5581,6 +5644,7 @@ var EvaluationEventEmitter = class {
  }
 
  async emitSentinelNow(final) {
+ if (!this.emitsSentinels) return;
  if (this.sentinelTargets.length === 0) return;
  const sentinel = { streamId: this.streamId, seq: this.lastSeq, final };
  await Promise.all(
@@ -5961,7 +6025,14 @@ var HttpTransport = class {
  otlpOpts.rawResponseLocation = mode === "dual" ? "http-channel" : "store";
  flushTargets.push(new OtlpEventFlushTarget(otlpOpts));
  }
+ if (e.deployment === "serverless" && e.streamId === void 0) {
+ throw new Error(
+ "emit.deployment 'serverless' requires a stable emit.streamId (e.g. the function name) \u2014 a per-request id would make streamCount track calls, not emitters. Completeness for a serverless emitter comes from reconciliation over that stable stream."
+ );
+ }
  const emitterOpts = { flushTargets, lensVersion };
+ if (e.deployment !== void 0) emitterOpts.deployment = e.deployment;
+ if (e.streamId !== void 0) emitterOpts.streamId = e.streamId;
  if (e.bufferSize !== void 0) emitterOpts.bufferSize = e.bufferSize;
  if (e.flushIntervalMs !== void 0) emitterOpts.flushIntervalMs = e.flushIntervalMs;
  if (e.sentinelIntervalMs !== void 0) emitterOpts.sentinelIntervalMs = e.sentinelIntervalMs;
@@ -6036,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);
  }
@@ -6143,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;
@@ -6492,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.3.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",