@unifyplane/logsdk 0.1.4 → 0.1.6

package/dist/validate/schema_guard.js

@@ -0,0 +1,151 @@
+import { assertValidMessage } from "../core/message_constraints.js";
+import { CANONICAL_SCHEMA_VIOLATION, CONTEXT_INJECTION_VIOLATION, NO_AUTHORITATIVE_SINK, PAYLOAD_EMBEDDING_VIOLATION, NonComplianceError, } from "./noncompliance.js";
+const REQUIRED_FIELDS = [
+    "record_version",
+    "record_id",
+    "sequence",
+    "timestamp_utc",
+    "monotonic_time",
+    "institution",
+    "system_name",
+    "system_type",
+    "environment",
+    "system_version",
+    "message",
+    "context_hash",
+    "context_version",
+    "record_hash",
+    "hash_algorithm",
+];
+const OPTIONAL_FIELDS = [
+    "instance_id",
+    "trace_id",
+    "span_id",
+    "parent_step_id",
+    "surface_type",
+    "surface_name",
+    "surface_instance",
+    "source_file",
+    "source_module",
+    "source_function",
+    "source_line",
+    "message_code",
+    "evidence_refs",
+];
+const ALLOWED_FIELDS = new Set([...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]);
+const CONTEXT_FIELDS = ["context", "context_blob", "context_data", "context_value"];
+// Explicit type assertion for string keys from Object.keys(schema.properties)
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "Step record must be a plain object.");
+    }
+    return value;
+}
+export function assertStepRecord(record) {
+    const candidate = asRecord(record);
+    if (!Object.isFrozen(candidate)) {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "Step record must be immutable at emission time.");
+    }
+    for (const forbidden of CONTEXT_FIELDS) {
+        if (forbidden in candidate) {
+            throw new NonComplianceError(CONTEXT_INJECTION_VIOLATION, "Context must not be embedded in the step record.");
+        }
+    }
+    for (const key of Object.keys(candidate)) {
+        if (!ALLOWED_FIELDS.has(key)) {
+            throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `Unexpected field in step record: ${key}.`);
+        }
+    }
+    for (const field of REQUIRED_FIELDS) {
+        if (!(field in candidate)) {
+            throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `Missing required field: ${field}.`);
+        }
+    }
+    assertStringField(candidate, "record_version");
+    assertStringField(candidate, "record_id");
+    assertIntegerField(candidate, "sequence");
+    assertStringField(candidate, "timestamp_utc");
+    assertNumberField(candidate, "monotonic_time");
+    assertStringField(candidate, "institution");
+    assertStringField(candidate, "system_name");
+    assertStringField(candidate, "system_type");
+    assertStringField(candidate, "environment");
+    assertStringField(candidate, "system_version");
+    assertStringField(candidate, "context_hash");
+    assertStringField(candidate, "context_version");
+    assertStringField(candidate, "record_hash");
+    assertStringField(candidate, "hash_algorithm");
+    if (candidate.record_version !== "log.step.v1") {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "record_version must be log.step.v1.");
+    }
+    try {
+        assertValidMessage(candidate.message);
+    }
+    catch (error) {
+        throw new NonComplianceError(PAYLOAD_EMBEDDING_VIOLATION, error instanceof Error ? error.message : "Invalid message content.");
+    }
+    if (typeof candidate.timestamp_utc === "string") {
+        const parsed = Date.parse(candidate.timestamp_utc);
+        if (Number.isNaN(parsed)) {
+            throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "timestamp_utc must be a valid ISO-8601 string.");
+        }
+    }
+    assertOptionalStringField(candidate, "instance_id");
+    assertOptionalStringField(candidate, "trace_id");
+    assertOptionalStringField(candidate, "span_id");
+    assertOptionalStringField(candidate, "parent_step_id");
+    assertOptionalStringField(candidate, "surface_type");
+    assertOptionalStringField(candidate, "surface_name");
+    assertOptionalStringField(candidate, "surface_instance");
+    assertOptionalStringField(candidate, "source_file");
+    assertOptionalStringField(candidate, "source_module");
+    assertOptionalStringField(candidate, "source_function");
+    assertOptionalStringField(candidate, "message_code");
+    if ("source_line" in candidate && candidate.source_line !== undefined) {
+        assertNumberField(candidate, "source_line");
+    }
+    if ("evidence_refs" in candidate && candidate.evidence_refs !== undefined) {
+        if (!Array.isArray(candidate.evidence_refs)) {
+            throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "evidence_refs must be an array of strings.");
+        }
+        for (const ref of candidate.evidence_refs) {
+            if (typeof ref !== "string" || ref.length === 0) {
+                throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, "evidence_refs must contain non-empty strings.");
+            }
+        }
+    }
+}
+// Explicit type assertion for string keys from Object.keys(schema.properties)
+export function assertHasAuthoritativeSink(sinks) {
+    const hasAuthoritative = sinks.some((entry) => entry.sinkClass === "authoritative");
+    if (!hasAuthoritative) {
+        throw new NonComplianceError(NO_AUTHORITATIVE_SINK, "At least one authoritative sink is required.");
+    }
+}
+function assertStringField(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `${field} must be a non-empty string.`);
+    }
+}
+function assertOptionalStringField(record, field) {
+    if (field in record && record[field] !== undefined) {
+        const value = record[field];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `${field} must be a non-empty string when provided.`);
+        }
+    }
+}
+function assertNumberField(record, field) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `${field} must be a finite number.`);
+    }
+}
+function assertIntegerField(record, field) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new NonComplianceError(CANONICAL_SCHEMA_VIOLATION, `${field} must be a non-negative integer.`);
+    }
+}
+//# sourceMappingURL=schema_guard.js.map

package/dist/validate/schema_guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_guard.js","sourceRoot":"","sources":["../../src/validate/schema_guard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@unifyplane/logsdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
 
   "exports": {
     ".": {

package/src/core/fanout.ts

@@ -6,9 +6,14 @@ export type FanoutOutcome = "OK" | "DEGRADED" | "FAILED";
 
 export async function fanout(
   record: StepRecord,
-  sinks: ReadonlyArray<SinkEntry>
+  sinks: ReadonlyArray<SinkEntry>,
+  options?: { mode?: "authoritative" | "non-authoritative" }
 ): Promise<FanoutOutcome> {
-  assertHasAuthoritativeSink(sinks);
+  const mode = options?.mode ?? "authoritative";
+
+  if (mode === "authoritative") {
+    assertHasAuthoritativeSink(sinks);
+  }
   const frozenRecord = Object.isFrozen(record) ? record : Object.freeze(record);
   let outcome: FanoutOutcome = "OK";
   let spooled = false;
@@ -17,7 +22,7 @@ export async function fanout(
     try {
       await entry.sink.emit(frozenRecord);
     } catch {
-      if (entry.sinkClass === "authoritative") {
+      if (mode === "authoritative" && entry.sinkClass === "authoritative") {
         if (!spooled) {
           try {
             await writeEmergencySpool(frozenRecord);

package/src/index.ts

@@ -29,6 +29,12 @@ export type LogSDKConfig = {
   context: unknown;
   system: SystemOwnership;
   sinks: ReadonlyArray<SinkEntry>;
+  /**
+   * Execution mode of the logger.
+   * - "authoritative" (default): requires at least one authoritative sink
+   * - "non-authoritative": allows orchestration-only runtimes (CLI, planners)
+   */
+  mode?: "authoritative" | "non-authoritative";
 };
 
 export type LogApi = {
@@ -75,7 +81,9 @@ export function initLogSDK(config: LogSDKConfig): LogApi {
 
       assertStepRecord(record);
 
-      const outcome = await fanout(record, sinks);
+      const outcome = await fanout(record, sinks, {
+        mode: config.mode ?? "authoritative",
+      });
       if (outcome === "FAILED") {
         throw new NonComplianceError(
           AUTHORITATIVE_FAILURE_SWALLOWED,

package/src/sinks/index.ts

@@ -1,14 +1,18 @@
 
 
+
 import { createStdoutSink } from "./stdout_sink.js";
 import { createFileNdjsonSink } from "./file_ndjson_sink.js";
-export { StdoutSink, createStdoutSink } from "./stdout_sink.js";
-export { FileNdjsonSink, createFileNdjsonSink } from "./file_ndjson_sink.js";
+// ---- Sink factories (authoritative API) ----
+export { createStdoutSink } from "./stdout_sink.js";
+export { createFileNdjsonSink } from "./file_ndjson_sink.js";
+
+// ---- Optional class exports (ESM only) ----
+export { StdoutSink } from "./stdout_sink.js";
+export { FileNdjsonSink } from "./file_ndjson_sink.js";
 
-// CJS interop: expose sink factories via default export
+// ---- CJS interop (single, stable surface) ----
 export default {
   createStdoutSink,
   createFileNdjsonSink
 };
-// Public sink exports
-// These are execution substrates and part of LogSDK's supported API.