@unifyplane/logsdk 1.0.0

package/src/core/message_constraints.ts

@@ -0,0 +1,66 @@
+const MESSAGE_MAX_LENGTH = 512;
+const BASE64_MIN_LENGTH = 80;
+
+function isJsonObjectOrArray(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return false;
+  }
+
+  const startsWithBrace = trimmed.startsWith("{") && trimmed.endsWith("}");
+  const startsWithBracket = trimmed.startsWith("[") && trimmed.endsWith("]");
+
+  if (!startsWithBrace && !startsWithBracket) {
+    return false;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === "object" && parsed !== null;
+  } catch {
+    return false;
+  }
+}
+
+function looksLikeBase64Blob(value: string): boolean {
+  const trimmed = value.trim();
+  if (trimmed.length < BASE64_MIN_LENGTH) {
+    return false;
+  }
+
+  if (/\s/.test(trimmed)) {
+    return false;
+  }
+
+  if (/^[A-Za-z0-9+/=_-]+$/.test(trimmed)) {
+    return true;
+  }
+
+  return /[A-Za-z0-9+/=_-]{80,}/.test(trimmed);
+}
+
+export function assertValidMessage(message: unknown): string {
+  if (typeof message !== "string") {
+    throw new Error("Message must be a string.");
+  }
+
+  if (message.length === 0) {
+    throw new Error("Message must not be empty.");
+  }
+
+  if (message.length > MESSAGE_MAX_LENGTH) {
+    throw new Error(`Message exceeds maximum length of ${MESSAGE_MAX_LENGTH}.`);
+  }
+
+  if (isJsonObjectOrArray(message)) {
+    throw new Error("Message must not be a JSON object or array.");
+  }
+
+  if (looksLikeBase64Blob(message)) {
+    throw new Error("Message must not contain base64-like payloads.");
+  }
+
+  return message;
+}
+
+export { MESSAGE_MAX_LENGTH };

package/src/core/outcomes.ts

@@ -0,0 +1,5 @@
+export const OK = "OK" as const;
+export const DEGRADED = "DEGRADED" as const;
+export const FAILED = "FAILED" as const;
+
+export type Outcome = typeof OK | typeof DEGRADED | typeof FAILED;

package/src/core/record_builder.ts

@@ -0,0 +1,269 @@
+/// <reference path="../crypto-shim.d.ts" />
+import { createHash, randomUUID } from "crypto";
+import { getContextHash, getContextVersion, JsonValue } from "./context";
+import { monotonicNow } from "./clock";
+import { assertValidMessage, MESSAGE_MAX_LENGTH } from "./message_constraints";
+import type { StepRecord } from "./types";
+
+const RECORD_VERSION = "log.step.v1";
+const HASH_ALGORITHM = "sha256";
+export const message_constraints = {
+  maxLength: MESSAGE_MAX_LENGTH,
+  validate: assertValidMessage,
+};
+
+export type EvidenceRef = string;
+
+export type SystemOwnership = {
+  institution: string;
+  system_name: string;
+  system_type: string;
+  environment: string;
+  system_version: string;
+  instance_id?: string;
+};
+
+export type StepRecordOverrides = {
+  record_id?: string;
+  timestamp_utc?: string;
+  monotonic_time?: number;
+  message_code?: string;
+  evidence_refs?: EvidenceRef[];
+  trace_id?: string;
+  span_id?: string;
+  parent_step_id?: string;
+  surface_type?: string;
+  surface_name?: string;
+  surface_instance?: string;
+  source_file?: string;
+  source_module?: string;
+  source_function?: string;
+  source_line?: number;
+};
+
+export function buildStepRecord(
+  message: string,
+  sequence: number,
+  system: SystemOwnership,
+  overrides: StepRecordOverrides = {}
+): StepRecord {
+  const validatedMessage = message_constraints.validate(message);
+  validateSequence(sequence);
+  validateSystemOwnership(system);
+
+  const contextHash = getContextHash();
+  const contextVersion = getContextVersion();
+
+  const recordId = overrides.record_id ?? createRecordId();
+  const timestampUtc = overrides.timestamp_utc ?? new Date().toISOString();
+  const monotonicTime = overrides.monotonic_time ?? monotonicNow();
+
+  const baseRecord: Omit<StepRecord, "record_hash" | "hash_algorithm"> = {
+    record_version: RECORD_VERSION,
+    record_id: recordId,
+    sequence,
+    timestamp_utc: timestampUtc,
+    monotonic_time: monotonicTime,
+    institution: system.institution,
+    system_name: system.system_name,
+    system_type: system.system_type,
+    environment: system.environment,
+    system_version: system.system_version,
+    message: validatedMessage,
+    context_hash: contextHash,
+    context_version: contextVersion,
+  };
+
+  setOptionalField(baseRecord, "instance_id", system.instance_id);
+  setOptionalField(baseRecord, "trace_id", overrides.trace_id);
+  setOptionalField(baseRecord, "span_id", overrides.span_id);
+  setOptionalField(baseRecord, "parent_step_id", overrides.parent_step_id);
+  setOptionalField(baseRecord, "surface_type", overrides.surface_type);
+  setOptionalField(baseRecord, "surface_name", overrides.surface_name);
+  setOptionalField(baseRecord, "surface_instance", overrides.surface_instance);
+  setOptionalField(baseRecord, "source_file", overrides.source_file);
+  setOptionalField(baseRecord, "source_module", overrides.source_module);
+  setOptionalField(baseRecord, "source_function", overrides.source_function);
+  setOptionalField(baseRecord, "source_line", overrides.source_line);
+  setOptionalField(baseRecord, "message_code", overrides.message_code);
+  setOptionalField(baseRecord, "evidence_refs", overrides.evidence_refs);
+
+  const canonical = stableStringify(
+    normalizeJsonValueOrdered(canonicalizeForHash(baseRecord), "$")
+  );
+  const recordHash = createHash(HASH_ALGORITHM).update(canonical).digest("hex");
+
+  const record: StepRecord = {
+    ...baseRecord,
+    record_hash: recordHash,
+    hash_algorithm: HASH_ALGORITHM,
+  };
+
+  return deepFreeze(record);
+}
+
+function validateSequence(sequence: number): void {
+  if (!Number.isInteger(sequence) || sequence < 0) {
+    throw new Error("Sequence must be a non-negative integer");
+  }
+}
+
+function validateSystemOwnership(system: SystemOwnership): void {
+  const requiredFields: Array<keyof SystemOwnership> = [
+    "institution",
+    "system_name",
+    "system_type",
+    "environment",
+    "system_version",
+  ];
+
+  for (const field of requiredFields) {
+    const value = system[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(`Missing required system field: ${field}`);
+    }
+  }
+
+  if (system.instance_id !== undefined && typeof system.instance_id !== "string") {
+    throw new Error("instance_id must be a string when provided");
+  }
+}
+
+function createRecordId(): string {
+  return typeof randomUUID === "function"
+    ? randomUUID()
+    : createHash("sha256")
+        .update(`${Date.now()}-${Math.random()}`)
+        .digest("hex");
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  if (Object.isFrozen(value)) {
+    return value;
+  }
+
+  Object.freeze(value);
+
+  for (const key of Object.keys(value as object)) {
+    const child = (value as Record<string, unknown>)[key];
+    deepFreeze(child);
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      deepFreeze(item);
+    }
+  }
+
+  return value;
+}
+
+function canonicalizeForHash(
+  record: Omit<StepRecord, "record_hash" | "hash_algorithm">
+): JsonValue {
+  const ordered: Record<string, JsonValue> = {};
+  for (const field of HASH_FIELD_ORDER) {
+    const value = record[field];
+    if (value !== undefined) {
+      ordered[field] = normalizeJsonValueOrdered(value, `${String(field)}`);
+    }
+  }
+  return ordered;
+}
+
+function normalizeJsonValueOrdered(value: unknown, path: string): JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item, index) =>
+      normalizeJsonValueOrdered(item, `${path}[${index}]`)
+    );
+  }
+
+  if (typeof value === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      throw new Error(`Unsupported object at ${path}`);
+    }
+
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, JsonValue> = {};
+    const keys = Object.keys(obj);
+
+    for (const key of keys) {
+      const next = obj[key];
+      if (next === undefined) {
+        throw new Error(`Undefined value at ${path}.${key}`);
+      }
+      result[key] = normalizeJsonValueOrdered(next, `${path}.${key}`);
+    }
+
+    return result;
+  }
+
+  throw new Error(`Unsupported type at ${path}`);
+}
+
+function stableStringify(value: JsonValue): string {
+  return JSON.stringify(value);
+}
+
+function setOptionalField<K extends keyof Omit<StepRecord, "record_hash" | "hash_algorithm">>(
+  record: Omit<StepRecord, "record_hash" | "hash_algorithm">,
+  key: K,
+  value: Omit<StepRecord, "record_hash" | "hash_algorithm">[K]
+): void {
+  if (value !== undefined) {
+    (record as Record<string, unknown>)[key] = value as JsonValue;
+  }
+}
+
+const HASH_FIELD_ORDER: Array<
+  keyof Omit<StepRecord, "record_hash" | "hash_algorithm">
+> = [
+  "record_version",
+  "record_id",
+  "sequence",
+  "timestamp_utc",
+  "monotonic_time",
+  "institution",
+  "system_name",
+  "system_type",
+  "environment",
+  "system_version",
+  "instance_id",
+  "trace_id",
+  "span_id",
+  "parent_step_id",
+  "surface_type",
+  "surface_name",
+  "surface_instance",
+  "source_file",
+  "source_module",
+  "source_function",
+  "source_line",
+  "message",
+  "message_code",
+  "context_hash",
+  "context_version",
+  "evidence_refs",
+];

package/src/core/spool.ts

@@ -0,0 +1,41 @@
+/// <reference path="../fs-shim.d.ts" />
+
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+import type { StepRecord } from "./types";
+
+const DEFAULT_SPOOL_NAME = "logsdk-emergency-spool.ndjson";
+
+function getSpoolPath(): string {
+  return (
+    process.env.LOGSDK_EMERGENCY_SPOOL_PATH ??
+    path.join(os.tmpdir(), DEFAULT_SPOOL_NAME)
+  );
+}
+
+export function getEmergencySpoolPath(): string {
+  return getSpoolPath();
+}
+
+export async function writeEmergencySpool(record: StepRecord): Promise<void> {
+  const spoolPath = getSpoolPath();
+  const payload = `${JSON.stringify(record)}\n`;
+  const handle = await fs.open(spoolPath, "a");
+
+  try {
+    const result = await handle.write(payload, undefined, "utf8");
+
+    if (!result || typeof result.bytesWritten !== "number") {
+      throw new Error("Emergency spool write did not report bytes.");
+    }
+
+    if (result.bytesWritten !== payload.length) {
+      throw new Error("Emergency spool partial write detected.");
+    }
+
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,56 @@
+// Internal core types for LogSDK v1.0
+// Types only: no runtime logic.
+
+export type SinkClass = "authoritative" | "observability";
+
+export type FanoutOutcome = "OK" | "DEGRADED" | "FAILED";
+
+export interface StepRecord {
+  // 1. Identity & Versioning
+  record_version: "log.step.v1";
+  record_id: string;
+  sequence: number;
+
+  // 2. Time (Dual Clock)
+  timestamp_utc: string;
+  monotonic_time: number;
+
+  // 3. System Ownership (Evidence Boundary)
+  institution: string;
+  system_name: string;
+  system_type: string;
+  environment: string;
+  system_version: string;
+  instance_id?: string;
+
+  // 4. Execution Correlation (Derived Automatically)
+  trace_id?: string;
+  span_id?: string;
+  parent_step_id?: string;
+
+  // 5. Execution Surface (Where This Happened)
+  surface_type?: string;
+  surface_name?: string;
+  surface_instance?: string;
+
+  // 6. Source Location (Best-Effort, Factual)
+  source_file?: string;
+  source_module?: string;
+  source_function?: string;
+  source_line?: number;
+
+  // 7. Step Message (The Only Human Input)
+  message: string;
+  message_code?: string;
+
+  // 8. Context Capsule Reference (Frozen Once)
+  context_hash: string;
+  context_version: string;
+
+  // 9. Evidence References (Optional, Structured)
+  evidence_refs?: string[];
+
+  // 10. Integrity
+  record_hash: string;
+  hash_algorithm: string;
+}

package/src/crypto-shim.d.ts

@@ -0,0 +1,9 @@
+declare module "crypto" {
+  export type Hash = {
+    update(data: string): Hash;
+    digest(encoding: "hex" | string): string;
+  };
+
+  export function createHash(algorithm: string): Hash;
+  export function randomUUID(): string;
+}

package/src/fs-shim.d.ts

@@ -0,0 +1,15 @@
+declare module "fs" {
+  export type FileHandle = {
+    write(
+      data: string,
+      position?: number,
+      encoding?: string
+    ): Promise<{ bytesWritten: number }>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+  };
+
+  export const promises: {
+    open(path: string, flags: string): Promise<FileHandle>;
+  };
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+import { initContext } from "./core/context";
+import { createIdGenerator } from "./core/ids";
+import { buildStepRecord, SystemOwnership } from "./core/record_builder";
+import { assertValidMessage } from "./core/message_constraints";
+import { fanout } from "./core/fanout";
+import { assertApiSurface } from "./validate/api_surface_guard";
+import { assertStepRecord } from "./validate/schema_guard";
+import {
+  AUTHORITATIVE_FAILURE_SWALLOWED,
+  CONTEXT_INJECTION_VIOLATION,
+  PAYLOAD_EMBEDDING_VIOLATION,
+  NonComplianceError,
+} from "./validate/noncompliance";
+import type { StepRecord } from "./core/types";
+
+type SinkClass = "authoritative" | "observability";
+
+type Sink = {
+  emit(record: Readonly<StepRecord>): void | Promise<void>;
+  flush?(): void | Promise<void>;
+};
+
+type SinkEntry = {
+  sink: Sink;
+  sinkClass: SinkClass;
+};
+
+export type LogSDKConfig = {
+  context: unknown;
+  system: SystemOwnership;
+  sinks: ReadonlyArray<SinkEntry>;
+};
+
+export type LogApi = {
+  step(message: string): Promise<void>;
+  flush?: () => Promise<void>;
+};
+
+export type { SystemOwnership };
+
+export function initLogSDK(config: LogSDKConfig): LogApi {
+  initContext(config.context);
+
+  const idGenerator = createIdGenerator(config.system.instance_id);
+  const sinks = [...config.sinks];
+
+  const api: LogApi = {
+    async step(message: string): Promise<void> {
+      if (typeof message !== "string") {
+        if (message && typeof message === "object") {
+          throw new NonComplianceError(
+            CONTEXT_INJECTION_VIOLATION,
+            "Per-step context injection is not allowed."
+          );
+        }
+
+        throw new NonComplianceError(
+          PAYLOAD_EMBEDDING_VIOLATION,
+          "Message must be a string."
+        );
+      }
+
+      try {
+        assertValidMessage(message);
+      } catch (error) {
+        throw new NonComplianceError(
+          PAYLOAD_EMBEDDING_VIOLATION,
+          error instanceof Error ? error.message : "Invalid message content."
+        );
+      }
+
+      const record = buildStepRecord(message, idGenerator.nextSequence(), config.system, {
+        record_id: idGenerator.nextRecordId(),
+      });
+
+      assertStepRecord(record);
+
+      const outcome = await fanout(record, sinks);
+      if (outcome === "FAILED") {
+        throw new NonComplianceError(
+          AUTHORITATIVE_FAILURE_SWALLOWED,
+          "Authoritative sink failed to emit."
+        );
+      }
+    },
+    async flush(): Promise<void> {
+      for (const entry of sinks) {
+        if (entry.sink.flush) {
+          await entry.sink.flush();
+        }
+      }
+    },
+  };
+
+  assertApiSurface(api);
+  return api;
+}
+
+export function createLogger(config: LogSDKConfig): LogApi {
+  return initLogSDK(config);
+}
+
+export { fileNdjsonSink } from "./sinks/file_ndjson";
+
+
+export { authoritativeNdjsonSink } from "./sinks/file_ndjson";
+

package/src/node-test-shim.d.ts

@@ -0,0 +1 @@
+export {};

package/src/perf_hooks-shim.d.ts

@@ -0,0 +1,7 @@
+declare module "perf_hooks" {
+  export type Performance = {
+    now(): number;
+  };
+
+  export const performance: Performance;
+}

package/src/process-shim.d.ts

@@ -0,0 +1 @@
+export {};

package/src/sinks/file_ndjson.ts

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+import type { StepRecord } from "../core/types";
+
+type SinkClass = "authoritative" | "observability";
+
+type Sink = {
+  emit(record: Readonly<StepRecord>): void | Promise<void>;
+  flush?(): void | Promise<void>;
+};
+
+type SinkEntry = {
+  sink: Sink;
+  sinkClass: SinkClass;
+};
+
+export function fileNdjsonSink(pathOrOptions: string | { path: string }): SinkEntry {
+  const p = typeof pathOrOptions === "string" ? pathOrOptions : pathOrOptions.path;
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const sink: Sink = {
+    emit(record: Readonly<StepRecord>): void {
+      fs.appendFileSync(p, JSON.stringify(record) + "\n", { encoding: "utf8" });
+    },
+  };
+  return { sink, sinkClass: "observability" };
+}
+export function authoritativeNdjsonSink(pathOrOptions: string | { path: string }): SinkEntry {
+  const p = typeof pathOrOptions === "string" ? pathOrOptions : pathOrOptions.path;
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const sink: Sink = {
+    emit(record: Readonly<StepRecord>): void {
+      fs.appendFileSync(p, JSON.stringify(record) + "\n", { encoding: "utf8" });
+    },
+  };
+  return { sink, sinkClass: "authoritative" };
+}

package/src/sinks/file_ndjson_sink.ts

@@ -0,0 +1,45 @@
+/// <reference path="../fs-shim.d.ts" />
+
+import { promises as fs } from "fs";
+import type { StepRecord } from "../core/types";
+
+export interface FileNdjsonSink {
+  emit(record: StepRecord): Promise<void>;
+  close(): Promise<void>;
+}
+
+export function createFileNdjsonSink(filePath: string): FileNdjsonSink {
+  let closed = false;
+
+  return {
+    async emit(record: StepRecord): Promise<void> {
+      if (closed) {
+        throw new Error("File NDJSON sink is closed.");
+      }
+
+      const line = JSON.stringify(record);
+      const payload = `${line}\n`;
+      const handle = await fs.open(filePath, "a");
+
+      try {
+        const result = await handle.write(payload, undefined, "utf8");
+        if (!result || typeof result.bytesWritten !== "number") {
+          throw new Error("File NDJSON sink write did not report bytes.");
+        }
+
+        if (result.bytesWritten !== payload.length) {
+          throw new Error("File NDJSON sink partial write detected.");
+        }
+        await handle.sync();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`File NDJSON sink write failed: ${message}`);
+      } finally {
+        await handle.close();
+      }
+    },
+    async close(): Promise<void> {
+      closed = true;
+    },
+  };
+}

package/src/sinks/sink_types.ts

@@ -0,0 +1,15 @@
+import type { StepRecord as CoreStepRecord } from "../core/types";
+
+export type StepRecord = Readonly<CoreStepRecord>;
+
+export type SinkClass = "authoritative" | "observability";
+
+export interface Sink<TRecord = StepRecord> {
+  emit(record: Readonly<TRecord>): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+export interface SinkEntry<TRecord = StepRecord> {
+  sink: Sink<TRecord>;
+  sinkClass: SinkClass;
+}