@unifyplane/logsdk 0.1.0

package/src/index.ts

@@ -0,0 +1,105 @@
+import { initContext } from "./core/context.js";
+import { createIdGenerator } from "./core/ids.js";
+import { buildStepRecord, SystemOwnership } from "./core/record_builder.js";
+import { assertValidMessage } from "./core/message_constraints.js";
+import { fanout } from "./core/fanout.js";
+import { assertApiSurface } from "./validate/api_surface_guard.js";
+import { assertStepRecord } from "./validate/schema_guard.js";
+import {
+  AUTHORITATIVE_FAILURE_SWALLOWED,
+  CONTEXT_INJECTION_VIOLATION,
+  PAYLOAD_EMBEDDING_VIOLATION,
+  NonComplianceError,
+} from "./validate/noncompliance.js";
+import type { StepRecord } from "./core/types.js";
+
+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.js";
+
+export { authoritativeNdjsonSink } from "./sinks/file_ndjson.js";

package/src/sinks/file_ndjson.ts

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+import type { StepRecord } from "../core/types.js";
+
+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.js";
+
+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.js";
+
+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;
+}

package/src/sinks/stdout_sink.ts

@@ -0,0 +1,20 @@
+/// <reference path="../process-shim.d.ts" />
+
+import type { StepRecord } from "../core/types.js";
+
+export interface StdoutSink {
+  emit(record: StepRecord): Promise<void>;
+}
+
+export function createStdoutSink(): StdoutSink {
+  return {
+    async emit(record: StepRecord): Promise<void> {
+      try {
+        const line = JSON.stringify(record);
+        process.stdout.write(`${line}\n`);
+      } catch {
+        // Best-effort only: never throw.
+      }
+    },
+  };
+}

package/src/validate/api_surface_guard.ts

@@ -0,0 +1,106 @@
+import {
+  API_SURFACE_VIOLATION,
+  NonComplianceError,
+} from "./noncompliance.js";
+
+const ALLOWED_SCOPES = ["request", "job", "component"] as const;
+
+type AllowedScope = (typeof ALLOWED_SCOPES)[number];
+
+const FORBIDDEN_NAMES = new Set([
+  "withContext",
+  "ctx",
+  "meta",
+  "attributes",
+  "tags",
+  "labels",
+  "log",
+  "emit",
+  "metric",
+  "span",
+]);
+
+function assertFunction(value: unknown, name: string, arity: number): void {
+  if (typeof value !== "function") {
+    throw new NonComplianceError(
+      API_SURFACE_VIOLATION,
+      `${name} must be a function.`
+    );
+  }
+
+  if ((value as Function).length !== arity) {
+    throw new NonComplianceError(
+      API_SURFACE_VIOLATION,
+      `${name} must accept exactly ${arity} argument(s).`
+    );
+  }
+}
+
+function assertChildScopePolicy(child: unknown): void {
+  const candidate = child as { allowedScopes?: unknown };
+  const allowedScopes = candidate.allowedScopes;
+
+  if (!Array.isArray(allowedScopes) || allowedScopes.length === 0) {
+    throw new NonComplianceError(
+      API_SURFACE_VIOLATION,
+      "child() must declare allowedScopes to enforce scope union."
+    );
+  }
+
+  for (const scope of allowedScopes) {
+    if (!ALLOWED_SCOPES.includes(scope as AllowedScope)) {
+      throw new NonComplianceError(
+        API_SURFACE_VIOLATION,
+        `child() scope not allowed: ${String(scope)}.`
+      );
+    }
+  }
+}
+
+export function assertApiSurface(surface: unknown): void {
+  if (!surface || typeof surface !== "object") {
+    throw new NonComplianceError(
+      API_SURFACE_VIOLATION,
+      "API surface must be an object."
+    );
+  }
+
+  const api = surface as Record<string, unknown>;
+  const keys = Object.keys(api);
+
+  for (const key of keys) {
+    if (FORBIDDEN_NAMES.has(key)) {
+      throw new NonComplianceError(
+        API_SURFACE_VIOLATION,
+        `Forbidden API method detected: ${key}.`
+      );
+    }
+  }
+
+  if (!("step" in api)) {
+    throw new NonComplianceError(
+      API_SURFACE_VIOLATION,
+      "API surface must expose step(message)."
+    );
+  }
+
+  assertFunction(api.step, "step", 1);
+
+  if ("flush" in api) {
+    assertFunction(api.flush, "flush", 0);
+  }
+
+  if ("child" in api) {
+    assertFunction(api.child, "child", 1);
+    assertChildScopePolicy(api.child);
+  }
+
+  for (const key of keys) {
+    if (key !== "step" && key !== "child" && key !== "flush") {
+      throw new NonComplianceError(
+        API_SURFACE_VIOLATION,
+        `Unexpected API export: ${key}.`
+      );
+    }
+  }
+}

package/src/validate/noncompliance.ts

@@ -0,0 +1,33 @@
+export const API_SURFACE_VIOLATION = "API_SURFACE_VIOLATION" as const;
+export const CONTEXT_INJECTION_VIOLATION =
+  "CONTEXT_INJECTION_VIOLATION" as const;
+export const PAYLOAD_EMBEDDING_VIOLATION =
+  "PAYLOAD_EMBEDDING_VIOLATION" as const;
+export const CANONICAL_SCHEMA_VIOLATION =
+  "CANONICAL_SCHEMA_VIOLATION" as const;
+export const SINK_MUTATION_VIOLATION = "SINK_MUTATION_VIOLATION" as const;
+export const NO_AUTHORITATIVE_SINK = "NO_AUTHORITATIVE_SINK" as const;
+export const FANOUT_NONDETERMINISM = "FANOUT_NONDETERMINISM" as const;
+export const AUTHORITATIVE_FAILURE_SWALLOWED =
+  "AUTHORITATIVE_FAILURE_SWALLOWED" as const;
+export const UNBOUNDED_BUFFER_RISK = "UNBOUNDED_BUFFER_RISK" as const;
+
+export type NonComplianceCode =
+  | typeof API_SURFACE_VIOLATION
+  | typeof CONTEXT_INJECTION_VIOLATION
+  | typeof PAYLOAD_EMBEDDING_VIOLATION
+  | typeof CANONICAL_SCHEMA_VIOLATION
+  | typeof SINK_MUTATION_VIOLATION
+  | typeof NO_AUTHORITATIVE_SINK
+  | typeof FANOUT_NONDETERMINISM
+  | typeof AUTHORITATIVE_FAILURE_SWALLOWED
+  | typeof UNBOUNDED_BUFFER_RISK;
+
+export class NonComplianceError extends Error {
+  readonly code: NonComplianceCode;
+
+  constructor(code: NonComplianceCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/validate/schema_guard.ts

@@ -0,0 +1,242 @@
+import type { StepRecord } from "../core/types.js";
+import { assertValidMessage } from "../core/message_constraints.js";
+import type { SinkEntry } from "../sinks/sink_types.js";
+import {
+  CANONICAL_SCHEMA_VIOLATION,
+  CONTEXT_INJECTION_VIOLATION,
+  NO_AUTHORITATIVE_SINK,
+  PAYLOAD_EMBEDDING_VIOLATION,
+  NonComplianceError,
+} from "./noncompliance.js";
+
+const REQUIRED_FIELDS: Array<keyof StepRecord> = [
+  "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: Array<keyof StepRecord> = [
+  "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<string>([...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: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new NonComplianceError(
+      CANONICAL_SCHEMA_VIOLATION,
+      "Step record must be a plain object."
+    );
+  }
+  return value as Record<string, unknown>;
+}
+
+export function assertStepRecord(record: unknown): asserts record is StepRecord {
+  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: ReadonlyArray<SinkEntry>
+): void {
+  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: Record<string, unknown>,
+  field: string
+): void {
+  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: Record<string, unknown>,
+  field: string
+): void {
+  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: Record<string, unknown>,
+  field: string
+): void {
+  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: Record<string, unknown>,
+  field: string
+): void {
+  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.`
+    );
+  }
+}