@unifyplane/logsdk 1.0.0

package/src/sinks/stdout_sink.ts

@@ -0,0 +1,20 @@
+/// <reference path="../process-shim.d.ts" />
+
+import type { StepRecord } from "../core/types";
+
+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";
+
+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,238 @@
+import type { StepRecord } from "../core/types";
+import { assertValidMessage } from "../core/message_constraints";
+import type { SinkEntry } from "../sinks/sink_types";
+import {
+  CANONICAL_SCHEMA_VIOLATION,
+  CONTEXT_INJECTION_VIOLATION,
+  NO_AUTHORITATIVE_SINK,
+  PAYLOAD_EMBEDDING_VIOLATION,
+  NonComplianceError,
+} from "./noncompliance";
+
+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"];
+
+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."
+        );
+      }
+    }
+  }
+}
+
+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.`
+    );
+  }
+}

package/tests/fanout.test.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "vitest";
+import type { StepRecord } from "../src/core/types";
+import { fanout } from "../src/core/fanout";
+import type { SinkEntry } from "../src/sinks/sink_types";
+
+function buildRecord(): StepRecord {
+  return Object.freeze({
+    record_version: "log.step.v1",
+    record_id: "rec_fanout_001",
+    sequence: 1,
+    timestamp_utc: new Date().toISOString(),
+    monotonic_time: Date.now(),
+    institution: "UnifyPlane",
+    system_name: "LogSDK",
+    system_type: "service",
+    environment: "test",
+    system_version: "1.0.0",
+    instance_id: "unit-test",
+    message: "Fanout check",
+    context_hash: "context_hash_001",
+    context_version: "log.context.v1",
+    record_hash: "hash_001",
+    hash_algorithm: "sha256",
+  });
+}
+
+test("fanout OK path", async () => {
+  const order: string[] = [];
+  const sinks: SinkEntry[] = [
+    {
+      sinkClass: "authoritative",
+      sink: {
+        emit() {
+          order.push("authoritative");
+        },
+      },
+    },
+    {
+      sinkClass: "observability",
+      sink: {
+        emit() {
+          order.push("observability");
+        },
+      },
+    },
+  ];
+
+  const outcome = await fanout(buildRecord(), sinks);
+  expect(outcome).toBe("OK");
+  expect(order).toEqual(["authoritative", "observability"]);
+});

package/tests/fanout_spool.test.ts

@@ -0,0 +1,96 @@
+import { test, expect, vi } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { SinkEntry } from "../src/sinks/sink_types";
+import { fanout } from "../src/core/fanout";
+import type { StepRecord } from "../src/core/types";
+import * as spool from "../src/core/spool";
+
+function buildRecord(recordId: string): StepRecord {
+  return Object.freeze({
+    record_version: "log.step.v1",
+    record_id: recordId,
+    sequence: 0,
+    timestamp_utc: new Date().toISOString(),
+    monotonic_time: Date.now(),
+    institution: "UnifyPlane",
+    system_name: "LogSDK",
+    system_type: "service",
+    environment: "test",
+    system_version: "1.0.0",
+    instance_id: "unit-test",
+    message: "Spool check",
+    context_hash: "context_hash_001",
+    context_version: "log.context.v1",
+    record_hash: "hash_001",
+    hash_algorithm: "sha256",
+  });
+}
+
+test("fanout returns DEGRADED when authoritative sink fails but spool succeeds", async () => {
+  const spoolPath = path.join(
+    os.tmpdir(),
+    `logsdk-spool-${Date.now()}-${Math.random()}.ndjson`
+  );
+  const previousSpool = process.env.LOGSDK_EMERGENCY_SPOOL_PATH;
+  process.env.LOGSDK_EMERGENCY_SPOOL_PATH = spoolPath;
+
+  const sinks: SinkEntry[] = [
+    {
+      sinkClass: "authoritative",
+      sink: {
+        emit() {
+          throw new Error("boom");
+        },
+      },
+    },
+    {
+      sinkClass: "observability",
+      sink: {
+        emit() {
+          // best effort
+        },
+      },
+    },
+  ];
+
+  try {
+    const outcome = await fanout(buildRecord("rec_spool_001"), sinks);
+    expect(outcome).toBe("DEGRADED");
+
+    const content = await fs.readFile(spoolPath, "utf8");
+    expect(content).toContain("rec_spool_001");
+  } finally {
+    await fs.rm(spoolPath, { force: true });
+    if (previousSpool === undefined) {
+      delete process.env.LOGSDK_EMERGENCY_SPOOL_PATH;
+    } else {
+      process.env.LOGSDK_EMERGENCY_SPOOL_PATH = previousSpool;
+    }
+  }
+});
+
+test("fanout returns FAILED when emergency spool cannot persist", async () => {
+  const sinks: SinkEntry[] = [
+    {
+      sinkClass: "authoritative",
+      sink: {
+        emit() {
+          throw new Error("boom");
+        },
+      },
+    },
+  ];
+
+  const spy = vi
+    .spyOn(spool, "writeEmergencySpool")
+    .mockRejectedValue(new Error("spool failure"));
+
+  try {
+    const outcome = await fanout(buildRecord("rec_spool_002"), sinks);
+    expect(outcome).toBe("FAILED");
+  } finally {
+    spy.mockRestore();
+  }
+});

package/tests/message_constraints.test.ts

@@ -0,0 +1,7 @@
+import { test, expect } from "vitest";
+import { assertValidMessage } from "../src/core/message_constraints";
+
+test("message constraints accept bounded message", () => {
+  const message = "Step completed successfully.";
+  expect(assertValidMessage(message)).toBe(message);
+});

package/tests/node-shim.d.ts

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

package/tests/record_builder.test.ts

@@ -0,0 +1,32 @@
+import { test, expect } from "vitest";
+import type { StepRecord } from "../src/core/types";
+import { assertStepRecord } from "../src/validate/schema_guard";
+
+function buildRecord(overrides: Partial<StepRecord> = {}): StepRecord {
+  const record: StepRecord = {
+    record_version: "log.step.v1",
+    record_id: "rec_test_001",
+    sequence: 1,
+    timestamp_utc: new Date().toISOString(),
+    monotonic_time: Date.now(),
+    institution: "UnifyPlane",
+    system_name: "LogSDK",
+    system_type: "service",
+    environment: "test",
+    system_version: "1.0.0",
+    instance_id: "unit-test",
+    message: "Step emitted",
+    context_hash: "context_hash_001",
+    context_version: "log.context.v1",
+    record_hash: "hash_001",
+    hash_algorithm: "sha256",
+    ...overrides,
+  };
+
+  return Object.freeze(record);
+}
+
+test("valid step record emitted", () => {
+  const record = buildRecord();
+  expect(() => assertStepRecord(record)).not.toThrow();
+});

package/tests/sequence_monotonic.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, test, expect } from "vitest";
+import { initLogSDK } from "../src/index";
+import { resetContextForTests } from "../src/core/context";
+import type { StepRecord } from "../src/core/types";
+
+const baseSystem = {
+  institution: "UnifyPlane",
+  system_name: "LogSDK",
+  system_type: "service",
+  environment: "test",
+  system_version: "1.0.0",
+  instance_id: "unit-test",
+};
+
+beforeEach(() => {
+  resetContextForTests();
+});
+
+function createCaptureSink(records: StepRecord[]) {
+  return {
+    sinkClass: "authoritative" as const,
+    sink: {
+      emit(record: StepRecord) {
+        records.push(record);
+      },
+    },
+  };
+}
+
+test("emitted sequences start at 0 and increment by 1", async () => {
+  const records: StepRecord[] = [];
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [createCaptureSink(records)],
+  });
+
+  await log.step("first step");
+  await log.step("second step");
+
+  expect(records[0].sequence).toBe(0);
+  expect(records[1].sequence).toBe(1);
+});
+
+test("monotonic_time strictly increases across successive steps", async () => {
+  const records: StepRecord[] = [];
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [createCaptureSink(records)],
+  });
+
+  const steps = 5;
+  for (let i = 0; i < steps; i += 1) {
+    await log.step(`step ${i}`);
+  }
+
+  expect(records.length).toBe(steps);
+  for (let i = 1; i < records.length; i += 1) {
+    expect(records[i].monotonic_time).toBeGreaterThan(records[i - 1].monotonic_time);
+  }
+});