@holonograph/client 0.1.0 → 0.2.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({
 
@@ -5366,6 +5372,9 @@ var HttpTransport = class {
  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 +5422,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 = {
@@ -5449,6 +5497,14 @@ var HolonographClient = class {
  lensVersion;
  substrate;
 
+ onUnknownColumn;
+
+ declaredColumns;
+
+ warnedColumns = new Set();
+
+ refreshedColumnsOnce = false;
+
  messages;
 
  contract;
@@ -5476,6 +5532,7 @@ var HolonographClient = class {
  }
  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 +5588,52 @@ var HolonographClient = class {
  return this.inProcessTransport ? this.inProcessTransport.topology : null;
  }
 
+ 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 +5730,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holonograph/client",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -18,15 +18,7 @@
   "engines": {
     "node": ">=18"
   },
-  "keywords": [
-    "holonograph",
-    "llm",
-    "evaluation",
-    "observability",
-    "sdk",
-    "client",
-    "typescript"
-  ],
+  "keywords": ["holonograph", "llm", "evaluation", "observability", "sdk", "client", "typescript"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/holonograph/client.git"