@holonograph/client 0.1.0 → 0.3.0

package/dist/index.js

@@ -4008,6 +4008,8 @@ var ALL_VISIBILITIES = ["transparent", "announced", "opaque"];
 var VisibilityAttributeSchema = external_exports.enum(ALL_VISIBILITIES);
 var ALL_SUBSTRATE_COLUMN_SEMANTICS = ["deployment-state", "diagnostic"];
 var SubstrateColumnSemanticSchema = external_exports.enum(ALL_SUBSTRATE_COLUMN_SEMANTICS);
+var ALL_EMISSION_EXPECTATIONS = ["always", "conditional"];
+var EmissionExpectationSchema = external_exports.enum(ALL_EMISSION_EXPECTATIONS);
 var SubstrateColumnSchema = external_exports.object({
  id: external_exports.string().min(1).max(128),
  control: ControlAttributeSchema,
@@ -4016,7 +4018,9 @@ var SubstrateColumnSchema = external_exports.object({
 
  semantic: SubstrateColumnSemanticSchema.default("deployment-state"),
 
- values: external_exports.array(external_exports.string().min(1)).min(1).optional()
+ values: external_exports.array(external_exports.string().min(1)).min(1).optional(),
+
+ emissionExpectation: EmissionExpectationSchema.optional()
 });
 var SubstrateSnapshotSchema = external_exports.object({
  lensVersion: LensVersionIdSchema,
@@ -4585,7 +4589,9 @@ external_exports.object({
 
  tools: external_exports.array(CapabilityToolDefSchema).default([]),
 
- proseRules: external_exports.array(external_exports.string().min(1)).default([])
+ proseRules: external_exports.array(external_exports.string().min(1)).default([]),
+
+ availableColumns: external_exports.array(external_exports.string().min(1)).optional()
 });
 external_exports.object({
 
@@ -4685,7 +4691,9 @@ var LightSnapshotSchema = external_exports.object({
 
  vendorMetadata: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
 
- rawRequestOmitted: external_exports.boolean().optional()
+ rawRequestOmitted: external_exports.boolean().optional(),
+
+ rawResponsePresence: external_exports.enum(["present", "omitted-by-policy", "pending-attach", "failed-attach"]).optional()
 });
 var DimensionResultSchema = external_exports.object({
  dimensionId: DimensionIdSchema,
@@ -4759,7 +4767,9 @@ var EvaluationEventKindSchema = external_exports.enum([
 
  "analysis.eval-recommendation",
 
- "analysis.conformance-fixture"
+ "analysis.conformance-fixture",
+
+ "analysis.emission-coverage"
 ]);
 var AvailabilityTransitionDirectionSchema = external_exports.enum([
  "reachable->unreachable",
@@ -4935,6 +4945,18 @@ var ConformanceFixtureRecordSchema = external_exports.object({
 
  sourceSurfaceId: external_exports.string().min(1).optional()
 });
+var EmissionCoverageSchema = external_exports.object({
+
+ streamId: external_exports.string().min(1),
+
+ observedOrdinals: external_exports.array(external_exports.number().int().nonnegative()),
+
+ sentinelHighWater: external_exports.number().int().nonnegative().nullable(),
+
+ finalSeen: external_exports.boolean(),
+
+ observedAtMs: external_exports.number().int().nonnegative()
+});
 var EvaluationEventSchema = external_exports.object({
 
  eventId: external_exports.string().min(1),
@@ -4965,31 +4987,36 @@ var EvaluationEventSchema = external_exports.object({
 
  evalRecommendation: EvalRecommendationSchema.optional(),
 
- conformanceFixtureRecord: ConformanceFixtureRecordSchema.optional()
+ conformanceFixtureRecord: ConformanceFixtureRecordSchema.optional(),
+
+ emissionCoverage: EmissionCoverageSchema.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;
+ 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;
  }
  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;
+ 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;
  }
  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;
+ 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;
  }
  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;
+ 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;
  }
  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;
+ 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;
  }
  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;
+ 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.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;
+ 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.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."
+ 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."
  }
 );
 function newEventId(occurredAt = new Date()) {
@@ -5304,6 +5331,596 @@ var InProcessTransport = class {
  }
 };
 
+var BoundedEmitBuffer = class {
+ capacity;
+ items = [];
+ _offeredTotal = 0;
+ _droppedTotal = 0;
+
+ constructor(capacity) {
+ if (!Number.isInteger(capacity) || capacity < 1) {
+ throw new RangeError(
+ `BoundedEmitBuffer capacity must be a positive integer, got ${String(capacity)}`
+ );
+ }
+ this.capacity = capacity;
+ }
+
+ offer(item) {
+ this._offeredTotal += 1;
+ if (this.items.length >= this.capacity) {
+ this._droppedTotal += 1;
+ return false;
+ }
+ this.items.push(item);
+ return true;
+ }
+
+ drain() {
+ if (this.items.length === 0) return [];
+ const out = this.items;
+ this.items = [];
+ return out;
+ }
+
+ get size() {
+ return this.items.length;
+ }
+
+ get maxSize() {
+ return this.capacity;
+ }
+
+ get offeredTotal() {
+ return this._offeredTotal;
+ }
+
+ get droppedTotal() {
+ return this._droppedTotal;
+ }
+};
+
+var CompletenessAccounting = class {
+ constructor(lensVersion, config, hooks = {}) {
+ this.lensVersion = lensVersion;
+ this.config = config;
+ this.hooks = hooks;
+ }
+ lensVersion;
+ config;
+ hooks;
+ windowStartMs = null;
+ offered = 0;
+ dropped = 0;
+ delivered = 0;
+ failed = 0;
+
+ channels = new Map();
+
+ sustainedSinceMs = null;
+
+ alerted = false;
+
+ recordOffer(nowMs, accepted) {
+ this.openWindowIfNeeded(nowMs);
+ this.offered += 1;
+ if (!accepted) this.dropped += 1;
+ }
+
+ recordFlush(nowMs, channel, delivered, failed) {
+ this.openWindowIfNeeded(nowMs);
+ this.delivered += delivered;
+ this.failed += failed;
+ const entry = this.channels.get(channel) ?? { attempted: 0, delivered: 0, failed: 0 };
+ entry.attempted += delivered + failed;
+ entry.delivered += delivered;
+ entry.failed += failed;
+ this.channels.set(channel, entry);
+ }
+
+ maybeRollover(nowMs) {
+ if (this.windowStartMs === null) return;
+ if (nowMs - this.windowStartMs < this.config.windowMs) return;
+ this.finalize(this.windowStartMs + this.config.windowMs);
+ }
+
+ snapshot(nowMs) {
+ if (this.windowStartMs === null) return null;
+ return this.buildWindow(this.windowStartMs, nowMs);
+ }
+
+ flushOpenWindow(nowMs) {
+ if (this.windowStartMs === null) return;
+ this.finalize(Math.max(nowMs, this.windowStartMs));
+ }
+ openWindowIfNeeded(nowMs) {
+ this.windowStartMs ??= nowMs;
+ }
+ finalize(windowEndMs) {
+ const start = this.windowStartMs;
+ if (start === null) return;
+ const window = this.buildWindow(start, windowEndMs);
+ this.windowStartMs = null;
+ this.offered = 0;
+ this.dropped = 0;
+ this.delivered = 0;
+ this.failed = 0;
+ this.channels.clear();
+ this.hooks.onWindow?.(window);
+ this.evaluateSustainedLoad(window);
+ }
+ buildWindow(startMs, endMs) {
+ const completenessLowerBound = this.offered === 0 ? 1 : (this.offered - this.dropped) / this.offered;
+ const channels = {};
+ for (const [channel, entry] of this.channels) {
+ channels[channel] = { ...entry };
+ }
+ return {
+ lensVersion: this.lensVersion,
+ windowStartMs: startMs,
+ windowEndMs: endMs,
+ offered: this.offered,
+ dropped: this.dropped,
+ delivered: this.delivered,
+ failed: this.failed,
+ channels,
+ completenessLowerBound,
+ biasFlag: this.dropped > 0
+ };
+ }
+ evaluateSustainedLoad(window) {
+ const rate = window.offered === 0 ? 0 : window.dropped / window.offered;
+ if (rate >= this.config.dropRateThreshold && window.dropped > 0) {
+ this.sustainedSinceMs ??= window.windowStartMs;
+ const sustainedForMs = window.windowEndMs - this.sustainedSinceMs;
+ if (sustainedForMs >= this.config.sustainedForMs && !this.alerted) {
+ this.alerted = true;
+ this.hooks.onExtremeSustainedLoad?.({
+ lensVersion: this.lensVersion,
+ sinceMs: this.sustainedSinceMs,
+ firedAtMs: window.windowEndMs,
+ sustainedForMs,
+ dropRate: rate,
+ dropRateThreshold: this.config.dropRateThreshold
+ });
+ }
+ } else {
+ this.sustainedSinceMs = null;
+ this.alerted = false;
+ }
+ }
+};
+
+var DEFAULT_BUFFER_SIZE = 2048;
+var DEFAULT_FLUSH_INTERVAL_MS = 1e3;
+var DEFAULT_WINDOW_MS = 1e4;
+var DEFAULT_DROP_RATE_THRESHOLD = 0.01;
+var DEFAULT_SUSTAINED_FOR_MS = 6e4;
+var DEFAULT_SENTINEL_INTERVAL_MS = 3e4;
+var streamIdFallbackCounter = 0;
+function generateStreamId(nowMs) {
+ const cryptoObj = globalThis.crypto;
+ if (typeof cryptoObj?.randomUUID === "function") return cryptoObj.randomUUID();
+ streamIdFallbackCounter += 1;
+ return `stream-${String(nowMs)}-${String(streamIdFallbackCounter)}`;
+}
+function defaultScheduleInterval(fn, ms) {
+ const handle = setInterval(fn, ms);
+ handle.unref?.();
+ return () => {
+ clearInterval(handle);
+ };
+}
+var EvaluationEventEmitter = class {
+ buffer;
+ flushTargets;
+
+ sentinelTargets;
+ accounting;
+ now;
+ onFlushError;
+ stopInterval;
+ stopSentinelInterval;
+
+ streamId;
+ nextSeq = 0;
+
+ lastSeq = -1;
+
+ inFlight = null;
+ stopped = false;
+ constructor(opts) {
+ this.buffer = new BoundedEmitBuffer(opts.bufferSize ?? DEFAULT_BUFFER_SIZE);
+ if (opts.flushTargets.length === 0) {
+ throw new Error("EvaluationEventEmitter requires at least one flush target");
+ }
+ this.flushTargets = [...opts.flushTargets];
+ this.sentinelTargets = this.flushTargets.filter((t) => typeof t.emitSentinel === "function");
+ this.now = opts.now ?? Date.now;
+ this.streamId = opts.streamId ?? generateStreamId(this.now());
+ this.onFlushError = opts.onFlushError ?? ((error) => {
+ console.warn("[holonograph] emit flush error:", error);
+ });
+ const config = {
+ windowMs: opts.windowMs ?? DEFAULT_WINDOW_MS,
+ dropRateThreshold: opts.extremeSustainedLoad?.dropRateThreshold ?? DEFAULT_DROP_RATE_THRESHOLD,
+ sustainedForMs: opts.extremeSustainedLoad?.sustainedForMs ?? DEFAULT_SUSTAINED_FOR_MS
+ };
+ this.accounting = new CompletenessAccounting(opts.lensVersion, config, {
+ ...opts.onWindow !== void 0 ? { onWindow: opts.onWindow } : {},
+ ...opts.onExtremeSustainedLoad !== void 0 ? { onExtremeSustainedLoad: opts.onExtremeSustainedLoad } : {}
+ });
+ const schedule = opts.scheduleInterval ?? defaultScheduleInterval;
+ this.stopInterval = schedule(() => {
+ this.tick();
+ }, opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
+ this.stopSentinelInterval = schedule(() => {
+ this.sentinelTick();
+ }, opts.sentinelIntervalMs ?? DEFAULT_SENTINEL_INTERVAL_MS);
+ }
+
+ enqueue(event) {
+ const nowMs = this.now();
+ const seq = this.nextSeq;
+ this.nextSeq += 1;
+ this.lastSeq = seq;
+ const accepted = this.buffer.offer({ event, seq, streamId: this.streamId });
+ this.accounting.recordOffer(nowMs, accepted);
+ this.accounting.maybeRollover(nowMs);
+ return event.eventId;
+ }
+
+ tick() {
+ void this.flushNow();
+ this.accounting.maybeRollover(this.now());
+ }
+
+ sentinelTick() {
+ if (this.lastSeq < 0) return;
+ void this.emitSentinelNow(false);
+ }
+
+ async emitSentinelNow(final) {
+ if (this.sentinelTargets.length === 0) return;
+ const sentinel = { streamId: this.streamId, seq: this.lastSeq, final };
+ await Promise.all(
+ this.sentinelTargets.map(
+ (t) => (t.emitSentinel?.(sentinel) ?? Promise.resolve()).catch((error) => {
+ this.onFlushError(error);
+ })
+ )
+ );
+ }
+
+ flushNow() {
+ if (this.inFlight) return this.inFlight;
+ const batch = this.buffer.drain();
+ if (batch.length === 0) return Promise.resolve();
+ const flush = this.doFlush(batch).finally(() => {
+ this.inFlight = null;
+ });
+ this.inFlight = flush;
+ return flush;
+ }
+ async doFlush(batch) {
+ await Promise.all(this.flushTargets.map((target) => this.flushToTarget(target, batch)));
+ }
+ async flushToTarget(target, batch) {
+ const channel = target.channel;
+ try {
+ const result = await target.flushBatch(batch);
+ this.accounting.recordFlush(this.now(), channel, result.delivered, result.failed);
+ for (const error of result.errors) this.onFlushError(error);
+ } catch (error) {
+ this.accounting.recordFlush(this.now(), channel, 0, batch.length);
+ this.onFlushError(error);
+ }
+ }
+
+ snapshotWindow() {
+ return this.accounting.snapshot(this.now());
+ }
+
+ async shutdown() {
+ if (this.stopped) return;
+ this.stopped = true;
+ this.stopInterval();
+ this.stopSentinelInterval();
+ while (this.buffer.size > 0 || this.inFlight) {
+ await this.flushNow();
+ }
+ if (this.lastSeq >= 0) await this.emitSentinelNow(true);
+ await Promise.all(this.flushTargets.map((t) => t.shutdown?.() ?? Promise.resolve()));
+ this.accounting.flushOpenWindow(this.now());
+ }
+};
+
+var HttpEventFlushTarget = class {
+
+ constructor(postEvent) {
+ this.postEvent = postEvent;
+ }
+ postEvent;
+
+ channel = "http";
+ async flushBatch(items) {
+ let delivered = 0;
+ let failed = 0;
+ const errors = [];
+ for (const item of items) {
+ try {
+ await this.postEvent(item.event);
+ delivered += 1;
+ } catch (error) {
+ failed += 1;
+ errors.push(error);
+ }
+ }
+ return { delivered, failed, errors };
+ }
+};
+
+var EVALUATION_SPAN_NAME = "holonograph.evaluation";
+var DIMENSION_EVENT_NAME = "holonograph.dimension";
+var SENTINEL_SPAN_NAME = "holonograph.session.sentinel";
+var SPAN_ATTR = {
+ eventId: "holonograph.event.id",
+ correlationId: "holonograph.correlation_id",
+ surfaceId: "holonograph.surface.id",
+ fixtureId: "holonograph.surface.fixture_id",
+ passed: "holonograph.surface.passed",
+ cohortTags: "holonograph.surface.cohort_tags",
+ lensVersion: "holonograph.lens.version",
+ lightSourceId: "holonograph.light_source.id",
+ runMode: "holonograph.run_mode",
+ provenance: "holonograph.provenance",
+ latencyMs: "holonograph.light.latency_ms",
+ tokensInput: "holonograph.light.tokens.input",
+ tokensOutput: "holonograph.light.tokens.output",
+ ok: "holonograph.light.ok",
+
+ rawResponseLocation: "holonograph.raw_response.location",
+
+ substratePrefix: "holonograph.substrate.",
+ dimensionId: "holonograph.dimension.id",
+ dimensionPassed: "holonograph.dimension.passed",
+ dimensionScore: "holonograph.dimension.score",
+
+ emissionSeq: "holonograph.emission.seq",
+ emissionStream: "holonograph.emission.stream",
+
+ emissionFinal: "holonograph.emission.final"
+};
+function buildEvaluationSpanData(event, emission, options) {
+ const light = event.light;
+ const surface = event.surface;
+ const substrate = event.substrate;
+ const startTimeMs = Date.parse(event.occurredAt);
+ const latencyMs = typeof light?.latencyMs === "number" ? light.latencyMs : 0;
+ const endTimeMs = startTimeMs + latencyMs;
+ const isError = light?.error !== void 0;
+ const attributes = {
+ [SPAN_ATTR.eventId]: event.eventId,
+ [SPAN_ATTR.correlationId]: event.correlationId,
+ [SPAN_ATTR.surfaceId]: event.surfaceId,
+ [SPAN_ATTR.lensVersion]: event.lensVersion,
+ [SPAN_ATTR.ok]: !isError,
+
+ [SPAN_ATTR.rawResponseLocation]: options?.rawResponseLocation ?? "store"
+ };
+ if (surface !== void 0) {
+ attributes[SPAN_ATTR.fixtureId] = surface.fixtureId;
+ attributes[SPAN_ATTR.passed] = surface.passed;
+ attributes[SPAN_ATTR.cohortTags] = [...surface.cohortTags];
+ }
+ if (substrate !== void 0) {
+ attributes[SPAN_ATTR.lightSourceId] = substrate.lightSourceIdentifier;
+ attributes[SPAN_ATTR.runMode] = substrate.runMode;
+ attributes[SPAN_ATTR.provenance] = substrate.provenance;
+ for (const [key, value] of Object.entries(substrate.columns)) {
+ attributes[`${SPAN_ATTR.substratePrefix}${key}`] = value;
+ }
+ }
+ if (typeof light?.latencyMs === "number") attributes[SPAN_ATTR.latencyMs] = light.latencyMs;
+ if (light?.tokens?.input !== void 0) attributes[SPAN_ATTR.tokensInput] = light.tokens.input;
+ if (light?.tokens?.output !== void 0) attributes[SPAN_ATTR.tokensOutput] = light.tokens.output;
+ if (emission !== void 0) {
+ attributes[SPAN_ATTR.emissionSeq] = emission.seq;
+ attributes[SPAN_ATTR.emissionStream] = emission.streamId;
+ }
+ const dimensionEvents = (surface?.dimensions ?? []).map((d) => {
+ const attrs = {
+ [SPAN_ATTR.dimensionId]: d.dimensionId,
+ [SPAN_ATTR.dimensionPassed]: d.passed
+ };
+ if (d.score !== void 0) attrs[SPAN_ATTR.dimensionScore] = d.score;
+ return { name: DIMENSION_EVENT_NAME, attributes: attrs };
+ });
+ return {
+ name: EVALUATION_SPAN_NAME,
+ startTimeMs,
+ endTimeMs,
+ attributes,
+ dimensionEvents,
+ isError,
+ errorMessage: light?.error?.message
+ };
+}
+function writeEvaluationSpan(tracer, event, otel, emission, options) {
+ const data = buildEvaluationSpanData(event, emission, options);
+ const span = tracer.startSpan(data.name, {
+ startTime: data.startTimeMs,
+ kind: otel.SpanKindClient,
+ attributes: data.attributes
+ });
+ for (const ev of data.dimensionEvents) span.addEvent(ev.name, ev.attributes);
+ if (data.isError) {
+ span.setStatus(
+ data.errorMessage !== void 0 ? { code: otel.statusError, message: data.errorMessage } : { code: otel.statusError }
+ );
+ } else {
+ span.setStatus({ code: otel.statusOk });
+ }
+ span.end(data.endTimeMs);
+}
+function writeSentinelSpan(tracer, sentinel, otel) {
+ const span = tracer.startSpan(SENTINEL_SPAN_NAME, {
+ kind: otel.SpanKindClient,
+ attributes: {
+ [SPAN_ATTR.emissionStream]: sentinel.streamId,
+ [SPAN_ATTR.emissionSeq]: sentinel.seq,
+ [SPAN_ATTR.emissionFinal]: sentinel.final
+ }
+ });
+ span.setStatus({ code: otel.statusOk });
+ span.end();
+}
+
+function reconcileBatchDelivery(batchSize, delivered, exportFailed) {
+ const shed = Math.max(0, batchSize - delivered - exportFailed);
+ return { delivered, failed: exportFailed + shed };
+}
+var CountingExporter = class {
+ constructor(inner, tally, successCode) {
+ this.inner = inner;
+ this.tally = tally;
+ this.successCode = successCode;
+ }
+ inner;
+ tally;
+ successCode;
+ export(spans, resultCallback) {
+ this.inner.export(spans, (result) => {
+ if (result.code === this.successCode) {
+ this.tally.delivered += spans.length;
+ } else {
+ this.tally.failed += spans.length;
+ if (result.error) this.tally.errors.push(result.error);
+ }
+ resultCallback(result);
+ });
+ }
+ shutdown() {
+ return this.inner.shutdown();
+ }
+ forceFlush() {
+ return this.inner.forceFlush?.() ?? Promise.resolve();
+ }
+};
+var OtlpEventFlushTarget = class {
+ channel = "otlp";
+ options;
+ tally = { delivered: 0, failed: 0, errors: [] };
+ provider;
+ tracer;
+ otel;
+ initPromise;
+
+ opLock = Promise.resolve();
+ constructor(options) {
+ this.options = options;
+ }
+
+ serialize(fn) {
+ const run = this.opLock.then(fn, fn);
+ this.opLock = run.then(
+ () => void 0,
+ () => void 0
+ );
+ return run;
+ }
+ flushBatch(items) {
+ return this.serialize(() => this.doFlushBatch(items));
+ }
+ async doFlushBatch(items) {
+ await this.ensureInit();
+ const tracer = this.tracer;
+ const otel = this.otel;
+ const provider = this.provider;
+ if (!tracer || !otel || !provider) {
+ return {
+ delivered: 0,
+ failed: items.length,
+ errors: [new Error("OTLP target not initialized")]
+ };
+ }
+ const beforeDelivered = this.tally.delivered;
+ const beforeFailed = this.tally.failed;
+ const beforeErrors = this.tally.errors.length;
+ const spanOptions = {
+ rawResponseLocation: this.options.rawResponseLocation ?? "store"
+ };
+ for (const item of items) {
+ writeEvaluationSpan(
+ tracer,
+ item.event,
+ otel,
+ { seq: item.seq, streamId: item.streamId },
+ spanOptions
+ );
+ }
+ await provider.forceFlush();
+ const delivered = this.tally.delivered - beforeDelivered;
+ const exportFailed = this.tally.failed - beforeFailed;
+ const reconciled = reconcileBatchDelivery(items.length, delivered, exportFailed);
+ return { ...reconciled, errors: this.tally.errors.slice(beforeErrors) };
+ }
+
+ emitSentinel(sentinel) {
+ return this.serialize(async () => {
+ await this.ensureInit();
+ if (!this.tracer || !this.otel || !this.provider) return;
+ writeSentinelSpan(this.tracer, sentinel, this.otel);
+ await this.provider.forceFlush();
+ });
+ }
+ async shutdown() {
+ if (this.provider) await this.provider.shutdown();
+ }
+
+ ensureInit() {
+ this.initPromise ??= this.doInit();
+ return this.initPromise;
+ }
+ async doInit() {
+ const [api, sdk, resources, core] = await Promise.all([
+ import('@opentelemetry/api'),
+ import('@opentelemetry/sdk-trace-base'),
+ import('@opentelemetry/resources'),
+ import('@opentelemetry/core')
+ ]);
+ let exporter;
+ if (this.options.exporter) {
+ exporter = this.options.exporter;
+ } else {
+ const otlp = await import('@opentelemetry/exporter-trace-otlp-http');
+ const exporterConfig = {};
+ if (this.options.endpoint !== void 0) exporterConfig.url = this.options.endpoint;
+ if (this.options.headers !== void 0) exporterConfig.headers = this.options.headers;
+ exporter = new otlp.OTLPTraceExporter(exporterConfig);
+ }
+ const counting = new CountingExporter(exporter, this.tally, core.ExportResultCode.SUCCESS);
+ const resource = resources.resourceFromAttributes({
+ "service.name": "holonograph-client",
+ "holonograph.lens.version": this.options.lensVersion
+ });
+ this.provider = new sdk.BasicTracerProvider({
+ resource,
+ spanProcessors: [
+ new sdk.BatchSpanProcessor(counting, {
+ maxQueueSize: this.options.maxQueueSize ?? 4096
+ })
+ ]
+ });
+ this.tracer = this.provider.getTracer("holonograph-client");
+ this.otel = {
+ SpanKindClient: api.SpanKind.CLIENT,
+ statusOk: api.SpanStatusCode.OK,
+ statusError: api.SpanStatusCode.ERROR
+ };
+ }
+};
+
 var HolonographHttpError = class extends Error {
  constructor(status, code, message, details) {
  super(message);
@@ -5321,11 +5938,46 @@ var HttpTransport = class {
  token;
  fetchImpl;
  runMode;
+
+ emitter;
  constructor(opts) {
  this.endpoint = opts.endpoint.replace(/\/$/, "");
  this.token = opts.token;
  this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
  this.runMode = opts.runMode;
+ const e = opts.emit;
+ const mode = e?.mode;
+ if (e !== void 0 && (mode === "buffered" || mode === "otlp" || mode === "dual")) {
+ const lensVersion = opts.lensVersion ?? "unknown";
+ const flushTargets = [];
+ if (mode === "buffered" || mode === "dual") {
+ flushTargets.push(new HttpEventFlushTarget((event) => this.postEvent(event)));
+ }
+ if (mode === "otlp" || mode === "dual") {
+ const otlpOpts = { lensVersion };
+ if (e.otlp?.endpoint !== void 0) otlpOpts.endpoint = e.otlp.endpoint;
+ if (e.otlp?.headers !== void 0) otlpOpts.headers = e.otlp.headers;
+ otlpOpts.maxQueueSize = e.otlp?.maxQueueSize ?? (e.bufferSize ?? 2048) * 2;
+ otlpOpts.rawResponseLocation = mode === "dual" ? "http-channel" : "store";
+ flushTargets.push(new OtlpEventFlushTarget(otlpOpts));
+ }
+ const emitterOpts = { flushTargets, lensVersion };
+ 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;
+ if (e.windowMs !== void 0) emitterOpts.windowMs = e.windowMs;
+ if (e.extremeSustainedLoad !== void 0) {
+ emitterOpts.extremeSustainedLoad = e.extremeSustainedLoad;
+ }
+ if (e.onWindow !== void 0) emitterOpts.onWindow = e.onWindow;
+ if (e.onExtremeSustainedLoad !== void 0) {
+ emitterOpts.onExtremeSustainedLoad = e.onExtremeSustainedLoad;
+ }
+ if (e.onFlushError !== void 0) emitterOpts.onFlushError = e.onFlushError;
+ this.emitter = new EvaluationEventEmitter(emitterOpts);
+ } else {
+ this.emitter = void 0;
+ }
  }
  async dispatch(req) {
  const wire = await this.post(
@@ -5360,12 +6012,30 @@ var HttpTransport = class {
  return result;
  }
  async appendEvent(event) {
+ if (this.emitter) {
+ return this.emitter.enqueue(event);
+ }
  const result = await this.post("/lens/events", event, event.correlationId);
  return result.eventId;
  }
+
+ async postEvent(event) {
+ await this.post("/lens/events", event, event.correlationId);
+ }
+
+ completenessWindow() {
+ return this.emitter?.snapshotWindow() ?? null;
+ }
+
+ async shutdown() {
+ if (this.emitter) await this.emitter.shutdown();
+ }
  async postContract(contract) {
  return this.post("/holonograph/contract", contract);
  }
+ async getContract() {
+ return this.get("/holonograph/contract");
+ }
  async markAvailability(req) {
  return this.post("/lens/availability/mark", req);
  }
@@ -5413,6 +6083,45 @@ var HttpTransport = class {
  }
  return parsed;
  }
+
+ async get(path) {
+ const url = `${this.endpoint}${path}`;
+ const headers = { "content-type": "application/json" };
+ if (this.token !== void 0) headers.authorization = `Bearer ${this.token}`;
+ if (this.runMode !== void 0) headers["x-holonograph-run-mode"] = this.runMode;
+ let response;
+ try {
+ response = await this.fetchImpl(url, { method: "GET", headers });
+ } catch (cause) {
+ throw new HolonographHttpError(
+ 0,
+ "transport_error",
+ `the lens fetch failed: ${cause.message}`,
+ { cause: String(cause) }
+ );
+ }
+ const text = await response.text();
+ let parsed;
+ try {
+ parsed = text.length ? JSON.parse(text) : {};
+ } catch {
+ throw new HolonographHttpError(
+ response.status,
+ "parse_error",
+ `the lens returned non-JSON (status ${String(response.status)}): ${text.slice(0, 200)}`
+ );
+ }
+ if (!response.ok) {
+ const envelope = parsed;
+ throw new HolonographHttpError(
+ response.status,
+ envelope.code ?? "server_error",
+ envelope.error ?? `the lens returned ${String(response.status)}`,
+ envelope.details
+ );
+ }
+ return parsed;
+ }
 };
 function lightSnapshotFromResult(result) {
  const snapshot = {
@@ -5446,9 +6155,18 @@ function flattenSystemBlocks(blocks) {
 var HolonographClient = class {
  transport;
  inProcessTransport;
+ httpTransport;
  lensVersion;
  substrate;
 
+ onUnknownColumn;
+
+ declaredColumns;
+
+ warnedColumns = new Set();
+
+ refreshedColumnsOnce = false;
+
  messages;
 
  contract;
@@ -5457,12 +6175,17 @@ var HolonographClient = class {
  constructor(options) {
  if (isHttpOptions(options)) {
  const httpOpts = {
- endpoint: options.endpoint
+ endpoint: options.endpoint,
+
+ lensVersion: options.lensVersion
  };
  if (options.token !== void 0) httpOpts.token = options.token;
  if (options.fetch !== void 0) httpOpts.fetch = options.fetch;
  if (options.runMode !== void 0) httpOpts.runMode = options.runMode;
- this.transport = new HttpTransport(httpOpts);
+ if (options.emit !== void 0) httpOpts.emit = options.emit;
+ const t = new HttpTransport(httpOpts);
+ this.transport = t;
+ this.httpTransport = t;
  this.inProcessTransport = void 0;
  } else {
  const inProcOpts = {
@@ -5473,9 +6196,11 @@ var HolonographClient = class {
  const t = new InProcessTransport(inProcOpts);
  this.transport = t;
  this.inProcessTransport = t;
+ this.httpTransport = void 0;
  }
  this.lensVersion = options.lensVersion;
  this.substrate = options.substrate;
+ this.onUnknownColumn = isHttpOptions(options) ? options.onUnknownColumn ?? "warn" : "ignore";
  this.messages = { create: (req) => this.messagesCreate(req) };
  this.contract = { register: (c) => this.registerContract(c) };
  this.availability = { mark: (req, opts) => this.markAvailability(req, opts) };
@@ -5531,6 +6256,60 @@ var HolonographClient = class {
  return this.inProcessTransport ? this.inProcessTransport.topology : null;
  }
 
+ completenessWindow() {
+ return this.httpTransport?.completenessWindow() ?? null;
+ }
+
+ async shutdown() {
+ if (this.httpTransport) await this.httpTransport.shutdown();
+ }
+
+ fetchDeclaredColumns(force = false) {
+ const getContract = this.transport.getContract?.bind(this.transport);
+ if (getContract === void 0) return Promise.resolve(null);
+ if (this.declaredColumns === void 0 || force) {
+ this.declaredColumns = getContract().then(
+ (c) => {
+ const union = new Set();
+ for (const surface of c.surfaces) {
+ for (const id of surface.substrateColumnIds ?? []) union.add(id);
+ }
+ return union;
+ },
+ () => null
+ );
+ }
+ return this.declaredColumns;
+ }
+
+ async validateSubstrateColumns(columns) {
+ if (columns === void 0 || this.onUnknownColumn === "ignore" || this.transport.getContract === void 0) {
+ return;
+ }
+ const keys = Object.keys(columns);
+ if (keys.length === 0) return;
+ const declared = await this.fetchDeclaredColumns();
+ if (declared === null || declared.size === 0) return;
+ let unknown = keys.filter((k) => !declared.has(k));
+ if (unknown.length > 0 && !this.refreshedColumnsOnce) {
+ this.refreshedColumnsOnce = true;
+ const refreshed = await this.fetchDeclaredColumns(true);
+ if (refreshed === null || refreshed.size === 0) return;
+ unknown = keys.filter((k) => !refreshed.has(k));
+ }
+ if (unknown.length === 0) return;
+ if (this.onUnknownColumn === "throw") {
+ throw new Error(
+ `Holonograph: substrate column(s) declared in no surface contract: ${unknown.join(", ")}. Declare them on the surface contract or fix the typo. (onUnknownColumn: 'throw')`
+ );
+ }
+ const toWarn = unknown.filter((k) => !this.warnedColumns.has(k));
+ if (toWarn.length === 0) return;
+ for (const k of toWarn) this.warnedColumns.add(k);
+ console.warn(
+ `Holonograph: substrate column(s) declared in no surface contract: ${toWarn.join(", ")}. They are still emitted, but the lens won't recognize them \u2014 declare them on the contract or fix the typo. (onUnknownColumn: 'throw' to block, 'ignore' to silence.)`
+ );
+ }
  async registerContract(contract) {
  if (typeof this.transport.postContract !== "function") {
  throw new Error(
@@ -5627,6 +6406,7 @@ var HolonographClient = class {
  substrate: { ...this.substrate, lightSourceIdentifier: callResult.record.lightSourceId },
  surface
  });
+ await this.validateSubstrateColumns(event.substrate?.columns);
  await this.transport.appendEvent(event);
  if (callResult.observerRecords && callResult.observerRecords.length > 0) {
  const siblingCohortTags = baseCohortTags;