@holonograph/client 0.6.0 → 0.7.0

package/dist/index.js

@@ -4108,7 +4108,7 @@ var JUDGE_CONTEXT_SCOPES = [
  "full_generating_prompt"
 ];
 var JudgeContextScopeSchema = external_exports.enum(JUDGE_CONTEXT_SCOPES);
-external_exports.object({
+var JudgeIdentitySchema = external_exports.object({
 
  rubricHash: external_exports.string().min(1).optional(),
 
@@ -4124,6 +4124,14 @@ function judgeIdentityColumns(identity) {
  if (identity.model !== void 0) columns[JUDGE_MODEL_COLUMN_ID] = identity.model;
  return columns;
 }
+var JudgeLensIdentityObservationSchema = external_exports.object({
+
+ rubricHash: external_exports.array(external_exports.string().min(1)).optional(),
+
+ contextScope: external_exports.array(external_exports.string().min(1)).optional(),
+
+ model: external_exports.array(external_exports.string().min(1)).optional()
+});
 
 var CannedMessageRefSchema = external_exports.string().min(1).max(256);
 var ALL_GATE_FAILURE_ACTIONS = ["retry", "flag", "block"];
@@ -4282,7 +4290,7 @@ external_exports.object({
 
  description: external_exports.string().optional(),
 
- surfaces: external_exports.array(SurfaceDeclarationSchema).min(1),
+ surfaces: external_exports.array(SurfaceDeclarationSchema),
 
  routings: external_exports.array(SurfaceRoutingSchema).optional(),
 
@@ -4290,7 +4298,42 @@ external_exports.object({
 
  systemSurfaces: SystemSurfacesSchema.optional()
 });
+var RESERVED_COLUMN_IDS = new Set([
+
+ "lens_version",
+ "light_source_identifier",
+ "run_mode",
+ "correlation_id",
+ "provenance",
+ "timestamp",
+
+ "light_source_served_model"
+
+]);
 var SERVED_MODEL_COLUMN_ID = "light_source_served_model";
+function normalizeColumnId(colId) {
+ return colId.toLowerCase().replace(/[._-]/g, "");
+}
+var CANONICAL_APPARATUS_FACET_IDS = [
+ ...RESERVED_COLUMN_IDS,
+ JUDGE_RUBRIC_HASH_COLUMN_ID,
+ JUDGE_CONTEXT_SCOPE_COLUMN_ID,
+ JUDGE_MODEL_COLUMN_ID
+];
+var NORMALIZED_APPARATUS_FACETS = new Map(
+ CANONICAL_APPARATUS_FACET_IDS.map((id) => [normalizeColumnId(id), id])
+);
+new Set(
+ [
+ SERVED_MODEL_COLUMN_ID,
+ JUDGE_RUBRIC_HASH_COLUMN_ID,
+ JUDGE_CONTEXT_SCOPE_COLUMN_ID,
+ JUDGE_MODEL_COLUMN_ID
+ ].map(normalizeColumnId)
+);
+function isApparatusFacetSpelling(colId) {
+ return NORMALIZED_APPARATUS_FACETS.has(normalizeColumnId(colId));
+}
 
 var LightSourceRoleSchema = external_exports.enum(["system", "user", "assistant", "tool"]);
 var LightSourceContentBlockSchema = external_exports.discriminatedUnion("kind", [
@@ -4858,7 +4901,9 @@ var NoiseFloorCalibrationSchema = external_exports.object({
 
  perFixtureDimension: external_exports.array(NoiseFloorPerFixtureDimensionSchema),
 
- perDimensionPooled: external_exports.array(NoiseFloorPerDimensionPooledSchema)
+ perDimensionPooled: external_exports.array(NoiseFloorPerDimensionPooledSchema),
+
+ calibratedUnderJudgeIdentity: JudgeLensIdentityObservationSchema.optional()
 });
 var VarianceDecompositionConfidenceIntervalSchema = external_exports.object({
  lower: external_exports.number().min(0),
@@ -4873,6 +4918,110 @@ var VarianceLensVersionEntrySchema = external_exports.object({
 
  meanScore: external_exports.number()
 });
+var FloorFreshnessSchema = external_exports.object({
+ state: external_exports.enum(["fresh", "stale", "undeterminable"]),
+
+ comparedFacets: external_exports.array(external_exports.string()),
+
+ changedFacets: external_exports.array(external_exports.string()),
+
+ ambiguousFacets: external_exports.array(external_exports.string())
+});
+var PhrasingBandRegionSchema = external_exports.object({
+
+ bandMean: external_exports.number().min(0),
+
+ bandMax: external_exports.number().min(0)
+});
+external_exports.object({
+
+ version: external_exports.string().min(1),
+
+ frozenAt: external_exports.string().min(1),
+
+ measuredUnder: external_exports.object({
+ judge: external_exports.string().min(1),
+ rubricVersion: external_exports.string().min(1)
+ }),
+
+ boundaries: external_exports.object({
+
+ ceilingLo: external_exports.number(),
+
+ floorHi: external_exports.number(),
+
+ midMeasuredRange: external_exports.object({ lo: external_exports.number(), hi: external_exports.number() })
+ }),
+ regions: external_exports.object({
+ ceiling: PhrasingBandRegionSchema,
+ mid: PhrasingBandRegionSchema,
+ floor: PhrasingBandRegionSchema
+ })
+});
+var FloorRegionSchema = external_exports.object({
+
+ region: external_exports.enum(["ceiling", "mid", "floor"]),
+
+ calibrationRegion: external_exports.enum(["ceiling", "mid", "floor"]).optional(),
+
+ calibrationScoreCount: external_exports.number().int().min(0).optional(),
+
+ bandMean: external_exports.number().min(0),
+
+ bandMax: external_exports.number().min(0),
+
+ bandExtrapolated: external_exports.boolean(),
+
+ calibrationBandExtrapolated: external_exports.boolean().optional(),
+
+ windowStraddlesBoundary: external_exports.boolean().optional(),
+
+ counterfactualSigmaAgentDelta: external_exports.number().nullable(),
+
+ counterfactualUnavailableReason: external_exports.enum(["no_calibration_scores", "calibration_region_degenerate"]).optional(),
+
+ curveProvenance: external_exports.object({
+ version: external_exports.string(),
+ judge: external_exports.string(),
+ rubricVersion: external_exports.string()
+ })
+});
+var LensCompositeCorrectionSchema = external_exports.object({
+
+ correctedVarianceLens: external_exports.number().min(0),
+
+ reattributedFromResidual: external_exports.number(),
+
+ compositeGroupCount: external_exports.number().int().min(1),
+
+ bracketedFacets: external_exports.array(external_exports.string()),
+
+ bracketedFacetLevels: external_exports.array(external_exports.object({ facet: external_exports.string(), distinctLevels: external_exports.number().int().min(1) })).optional(),
+
+ conservationHolds: external_exports.boolean(),
+
+ partitionRelationship: external_exports.enum([
+ "degenerate",
+ "identical",
+ "judge-refines-version",
+ "version-refines-judge",
+ "cross-cutting"
+ ])
+});
+var ApparatusFacetDriftSchema = external_exports.object({
+ facet: external_exports.string(),
+ basis: external_exports.enum(["reserved-namespace", "declared-control"]),
+
+ control: ControlAttributeSchema.optional()
+});
+var ApparatusResidualContaminationSchema = external_exports.object({
+
+ contaminated: external_exports.boolean(),
+
+ driftedFacets: external_exports.array(ApparatusFacetDriftSchema),
+
+ scope: external_exports.enum(["reserved-only", "contract-resolved"]).optional()
+});
 var VarianceDecompositionSchema = external_exports.object({
  dimensionId: DimensionIdSchema,
 
@@ -4903,7 +5052,17 @@ var VarianceDecompositionSchema = external_exports.object({
 
  sigmaAgentCI: VarianceDecompositionConfidenceIntervalSchema,
 
- caveats: external_exports.array(external_exports.string()).default([])
+ caveats: external_exports.array(external_exports.string()).default([]),
+
+ floorFreshness: FloorFreshnessSchema.optional(),
+
+ floorRegion: FloorRegionSchema.optional(),
+
+ lensCompositeCorrection: LensCompositeCorrectionSchema.optional(),
+
+ apparatusResidualContamination: ApparatusResidualContaminationSchema.optional(),
+
+ decompositionMethodVersion: external_exports.string().optional()
 });
 var LifecycleTransitionStatusSchema = external_exports.enum([
  "draft",
@@ -4952,7 +5111,8 @@ var EvalRecommendationVerdictSchema = external_exports.enum([
  "contaminated",
  "insufficient-n",
  "degenerate",
- "instrument-limited"
+ "instrument-limited",
+ "stale-floor"
 ]);
 var EvalRecommendationCheckSchema = external_exports.object({
  name: external_exports.string().min(1).max(128),
@@ -5368,6 +5528,193 @@ external_exports.object({
 external_exports.enum(["classificationMode"]);
 external_exports.enum(["prefix-match", "absent-defaulted"]);
 
+var RELIABILITY_DISPOSITIONS = ["flagged", "assessed", "not-applicable"];
+var ReliabilityDispositionSchema = external_exports.enum(RELIABILITY_DISPOSITIONS);
+var RELIABILITY_FIRING_STAGES = ["config", "score", "window"];
+var ReliabilityFiringStageSchema = external_exports.enum(RELIABILITY_FIRING_STAGES);
+var ReliabilityCorpusFindingSchema = external_exports.object({
+
+ entryId: external_exports.string().min(1),
+
+ failureMode: external_exports.string().min(1),
+
+ disposition: ReliabilityDispositionSchema,
+
+ remediation: external_exports.string().min(1).nullable(),
+
+ firesAt: ReliabilityFiringStageSchema,
+
+ tier: external_exports.literal("deterministic"),
+
+ evidence: external_exports.record(external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).optional()
+});
+external_exports.object({
+
+ corpusVersion: external_exports.string().min(1),
+
+ corpusHash: external_exports.string().min(1),
+
+ findings: external_exports.array(ReliabilityCorpusFindingSchema)
+});
+var ReliabilityCorpusEntryRateSchema = external_exports.object({
+ entryId: external_exports.string().min(1),
+
+ evaluated: external_exports.number().int().nonnegative(),
+
+ flagged: external_exports.number().int().nonnegative(),
+
+ assessed: external_exports.number().int().nonnegative(),
+
+ notApplicable: external_exports.number().int().nonnegative(),
+
+ firingRateAmongApplicable: external_exports.number().min(0).max(1).nullable()
+});
+var ReliabilityCorpusRatesSchema = external_exports.object({
+ corpusVersion: external_exports.string().min(1),
+ corpusHash: external_exports.string().min(1),
+
+ evaluationCount: external_exports.number().int().nonnegative(),
+ perEntry: external_exports.array(ReliabilityCorpusEntryRateSchema)
+});
+var TraceClaimCheckSchema = external_exports.object({
+
+ tool: external_exports.string().min(1),
+
+ invoked: external_exports.boolean(),
+ disposition: external_exports.enum(["corroborated", "contradicted"])
+});
+var TRACE_CORROBORATION_DISPOSITIONS = [
+ "contradicted",
+ "corroborated",
+ "no-marker-to-check",
+ "not-applicable"
+];
+var TraceCorroborationDispositionSchema = external_exports.enum(TRACE_CORROBORATION_DISPOSITIONS);
+var TraceCorroborationSchema = external_exports.object({
+
+ disposition: TraceCorroborationDispositionSchema,
+
+ tier: external_exports.literal("deterministic"),
+
+ claims: external_exports.array(TraceClaimCheckSchema)
+});
+var MatchTierSchema = external_exports.discriminatedUnion("kind", [
+
+ external_exports.object({ kind: external_exports.literal("exact") }),
+
+ external_exports.object({ kind: external_exports.literal("normalized") }),
+
+ external_exports.object({ kind: external_exports.literal("fuzzy"), threshold: external_exports.number().min(0).max(1) })
+]);
+var GROUNDING_CLAIM_DISPOSITIONS = [
+ "present-in-scope",
+ "truncated-out",
+ "not-found"
+];
+var GroundingClaimDispositionSchema = external_exports.enum(GROUNDING_CLAIM_DISPOSITIONS);
+var GroundingClaimCheckSchema = external_exports.object({
+
+ datum: external_exports.string().min(1),
+ disposition: GroundingClaimDispositionSchema,
+
+ matchTier: MatchTierSchema.optional(),
+
+ charOffset: external_exports.number().int().nonnegative().optional()
+});
+var GROUNDING_COVERAGE_DISPOSITIONS = [
+ "present-in-scope",
+ "truncated-out",
+ "not-found",
+ "no-marker-to-check",
+ "not-applicable"
+];
+var GroundingCoverageDispositionSchema = external_exports.enum(GROUNDING_COVERAGE_DISPOSITIONS);
+var GroundingCoverageSchema = external_exports.object({
+ disposition: GroundingCoverageDispositionSchema,
+
+ tier: external_exports.literal("deterministic"),
+
+ claims: external_exports.array(GroundingClaimCheckSchema)
+});
+var VERDICT_RELIABILITY_TIERS = ["question", "trust", "review"];
+var VerdictReliabilityTierSchema = external_exports.enum(VERDICT_RELIABILITY_TIERS);
+external_exports.object({
+
+ tier: VerdictReliabilityTierSchema,
+
+ drivers: external_exports.array(external_exports.string()),
+
+ trace: TraceCorroborationSchema,
+
+ grounding: GroundingCoverageSchema
+});
+var VerdictReliabilityTierTallySchema = external_exports.object({
+ question: external_exports.number().int().nonnegative(),
+ trust: external_exports.number().int().nonnegative(),
+ review: external_exports.number().int().nonnegative(),
+ total: external_exports.number().int().nonnegative()
+});
+var FlaggedVerdictSchema = external_exports.object({
+
+ eventId: external_exports.string().min(1),
+
+ correlationId: external_exports.string().min(1).optional(),
+
+ occurredAt: external_exports.string().min(1),
+ surfaceId: external_exports.string().min(1),
+ dimensionId: external_exports.string().min(1),
+
+ drivers: external_exports.array(external_exports.string())
+});
+external_exports.object({
+
+ eventCount: external_exports.number().int().nonnegative(),
+
+ tierTally: VerdictReliabilityTierTallySchema,
+
+ flagged: external_exports.array(FlaggedVerdictSchema),
+
+ corpusRates: ReliabilityCorpusRatesSchema
+});
+var ESCALATION_REASONS = ["both-checks-not-applicable"];
+var EscalationReasonSchema = external_exports.enum(ESCALATION_REASONS);
+external_exports.object({
+
+ targetEventId: external_exports.string().min(1),
+ surfaceId: external_exports.string().min(1),
+ dimensionId: external_exports.string().min(1),
+
+ reason: EscalationReasonSchema
+});
+var JudgeVerdictSchema = external_exports.object({
+
+ score: external_exports.number().optional(),
+
+ passed: external_exports.boolean()
+});
+external_exports.object({
+
+ targetEventId: external_exports.string().min(1),
+ surfaceId: external_exports.string().min(1),
+ dimensionId: external_exports.string().min(1),
+
+ blind: external_exports.literal(true),
+
+ firstVerdict: JudgeVerdictSchema,
+
+ secondVerdict: JudgeVerdictSchema,
+
+ secondJudge: JudgeIdentitySchema,
+
+ secondJudgeInstrumentVersion: external_exports.string().min(1)
+});
+external_exports.object({
+ escalatedCount: external_exports.number().int().nonnegative(),
+ agreeCount: external_exports.number().int().nonnegative(),
+ disagreeCount: external_exports.number().int().nonnegative(),
+ agreementRate: external_exports.number().min(0).max(1).nullable()
+});
+
 var HolonographGradeAfterReportError = class extends Error {
  constructor() {
  super(
@@ -6290,12 +6637,22 @@ var HolonographClient = class {
 
  onUnknownColumn;
 
+ onUnknownColumnExplicit;
+
+ unknownColumnDeprecationWarned = false;
+
  declaredColumns;
 
  warnedColumns = new Set();
 
  refreshedColumnsOnce = false;
 
+ onCoverageDivergence;
+
+ coverageDivergenceChecked = false;
+
+ emitNonBlocking;
+
  messages;
 
  contract;
@@ -6330,6 +6687,9 @@ var HolonographClient = class {
  this.lensVersion = options.lensVersion;
  this.substrate = options.substrate;
  this.onUnknownColumn = isHttpOptions(options) ? options.onUnknownColumn ?? "warn" : "ignore";
+ this.onUnknownColumnExplicit = isHttpOptions(options) && options.onUnknownColumn !== void 0;
+ this.onCoverageDivergence = isHttpOptions(options) ? options.onCoverageDivergence ?? "warn" : "ignore";
+ this.emitNonBlocking = isHttpOptions(options) && options.emit?.mode !== void 0 && options.emit.mode !== "sync";
  this.messages = { create: (req) => this.messagesCreate(req) };
  this.contract = { register: (c) => this.registerContract(c) };
  this.availability = { mark: (req, opts) => this.markAvailability(req, opts) };
@@ -6426,14 +6786,31 @@ var HolonographClient = class {
  (k) => k !== SERVED_MODEL_COLUMN_ID && !k.startsWith(JUDGE_RESERVED_COLUMN_NAMESPACE_PREFIX)
  );
  if (keys.length === 0) return;
+ const apparatusSpellArounds = keys.filter((k) => isApparatusFacetSpelling(k));
+ const substrateKeys = keys.filter((k) => !isApparatusFacetSpelling(k));
+ if (apparatusSpellArounds.length > 0) {
+ if (this.onUnknownColumn === "throw") {
+ throw new Error(
+ `Holonograph: substrate column(s) collide with apparatus-owned lens identity: ${apparatusSpellArounds.join(", ")}. These normalize to columns the apparatus stamps itself (read the 'judge.*' / 'light_source_served_model' columns) \u2014 remove them from your substrate. (onUnknownColumn: 'throw')`
+ );
+ }
+ const toWarn2 = apparatusSpellArounds.filter((k) => !this.warnedColumns.has(k));
+ if (toWarn2.length > 0) {
+ for (const k of toWarn2) this.warnedColumns.add(k);
+ console.warn(
+ `Holonograph: substrate column(s) collide with apparatus-owned lens identity: ${toWarn2.join(", ")}. The apparatus stamps its own identity ('judge.*', 'light_source_served_model'); a substrate look-alike is not read as an axis \u2014 read the apparatus-stamped columns instead. (onUnknownColumn: 'throw' to block, 'ignore' to silence.)`
+ );
+ }
+ }
+ if (substrateKeys.length === 0) return;
  const declared = await this.fetchDeclaredColumns();
  if (declared === null || declared.size === 0) return;
- let unknown = keys.filter((k) => !declared.has(k));
+ let unknown = substrateKeys.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));
+ unknown = substrateKeys.filter((k) => !refreshed.has(k));
  }
  if (unknown.length === 0) return;
  if (this.onUnknownColumn === "throw") {
@@ -6447,6 +6824,42 @@ var HolonographClient = class {
  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.)`
  );
+ if (!this.onUnknownColumnExplicit && !this.unknownColumnDeprecationWarned) {
+ this.unknownColumnDeprecationWarned = true;
+ console.warn(
+ `Holonograph: DEPRECATION \u2014 the default onUnknownColumn will change from 'warn' to 'throw' in the next @holonograph/client major, so an undeclared substrate column will be REJECTED rather than logged. Declare your columns on the surface contract, or set onUnknownColumn: 'warn' explicitly to keep warn-and-continue. (This notice fires once.)`
+ );
+ }
+ }
+
+ async maybeSurfaceCoverageDivergence() {
+ const getEmission = this.transport.getEmission?.bind(this.transport);
+ if (this.onCoverageDivergence === "ignore" || this.emitNonBlocking || // never block the fast-resolve emit modes
+ this.coverageDivergenceChecked || getEmission === void 0) {
+ return;
+ }
+ this.coverageDivergenceChecked = true;
+ const audit = await getEmission().catch(() => void 0);
+ if (audit === void 0) return;
+ const undeclared = [];
+ const missing = [];
+ const apparatus = [];
+ for (const surface of audit.surfaces) {
+ for (const col of surface.undeclaredObserved) undeclared.push(`${surface.surfaceId}.${col}`);
+ for (const row of surface.columns) {
+ if (row.verdict === "missing") missing.push(`${surface.surfaceId}.${row.columnId}`);
+ }
+ for (const col of surface.apparatusObserved) apparatus.push(`${surface.surfaceId}.${col}`);
+ }
+ if (undeclared.length === 0 && missing.length === 0) return;
+ const parts = [];
+ if (undeclared.length > 0) parts.push(`emitted-but-undeclared: ${undeclared.join(", ")}`);
+ if (missing.length > 0) {
+ parts.push(`declared-but-never-emitted (missing): ${missing.join(", ")}`);
+ }
+ console.warn(
+ `Holonograph: declared-vs-emitted coverage divergence \u2014 ${parts.join("; ")}. See GET /holonograph/emission for the full audit` + (apparatus.length > 0 ? ` (apparatus columns observed: ${apparatus.join(", ")})` : "") + `. (onCoverageDivergence: 'ignore' to silence.)`
+ );
  }
  async registerContract(contract) {
  if (typeof this.transport.postContract !== "function") {
@@ -6550,6 +6963,7 @@ var HolonographClient = class {
  });
  await this.validateSubstrateColumns(event.substrate?.columns);
  await this.transport.appendEvent(event);
+ await this.maybeSurfaceCoverageDivergence();
  if (callResult.observerRecords && callResult.observerRecords.length > 0) {
  const siblingCohortTags = baseCohortTags;
  for (const observerRecord of callResult.observerRecords) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holonograph/client",
-  "version": "0.6.0",
+  "version": "0.7.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",