@unifyplane/logsdk 1.0.0

package/docs/log_sdk_test_coverage_report.md

@@ -0,0 +1,198 @@
+# 🧪 LogSDK — Test Coverage Report
+
+**Status:** Audit-Derived (Read-Only)
+
+**Purpose:**
+This document provides an explicit, audit-grade description of **what is tested** in the LogSDK repository. It reconstructs test intent and coverage from the existing test suite **without adding or modifying any tests**. The report is suitable for:
+
+- RE-AUDIT / Freeze-gate validation
+- Evidence submission
+- Governance review
+- Downstream trust assessment
+
+---
+
+## 1. Scope & Methodology
+
+**Scope:** `tests/` directory only  
+**Method:** Static inspection of test files and assertions  
+**Exclusions:** No behavioral inference beyond explicit test intent
+
+This report:
+- Maps each test file to **explicit guarantees**
+- Aligns tests to **audit objectives** (determinism, evidence safety, contract fidelity)
+- Clearly states **what is not tested** to avoid over-claiming
+
+---
+
+## 2. Test Inventory
+
+| Test File | Primary Concern |
+|---------|----------------|
+| `sequence_monotonic.test.ts` | Determinism & ordering |
+| `record_builder.test.ts` | Step Record integrity |
+| `fanout.test.ts` | Sink fan-out semantics |
+| `fanout_spool.test.ts` | Degraded / emergency spool behavior |
+| `message_constraints.test.ts` | Context & payload safety |
+| `sinks_file_ndjson.test.ts` | Evidence persistence correctness |
+| `step1_compliance.test.ts` | Contract compliance (baseline) |
+
+---
+
+## 3. Determinism & Ordering
+
+### `sequence_monotonic.test.ts`
+
+**Verifies:**
+- Sequence numbering starts at the defined baseline
+- Sequence increments strictly and monotonically
+- No duplicate or skipped sequence values
+- Ordering is preserved across rapid `step()` calls
+
+**Audit Guarantees Proven:**
+- Deterministic sequencing
+- Replay-safe ordering
+- No timing-based nondeterminism
+
+---
+
+## 4. Step Record Integrity
+
+### `record_builder.test.ts`
+
+**Verifies:**
+- Canonical Step Record construction
+- Presence of all required fields
+- Controlled derivation of values
+- Immutability after record creation
+
+**Audit Guarantees Proven:**
+- Canonical shape preservation
+- No hidden mutation paths
+- Stable inputs for hashing/serialization
+
+---
+
+## 5. Fan-Out Semantics
+
+### `fanout.test.ts`
+
+**Verifies:**
+- Multiple sinks receive identical records
+- Sink failure isolation
+- Core execution is not aborted by non-authoritative sink failures
+- Correct outcome classification
+
+**Audit Guarantees Proven:**
+- Fan-out does not mutate evidence
+- Sink isolation correctness
+- No silent failure masking
+
+---
+
+## 6. Degraded Mode & Emergency Spooling
+
+### `fanout_spool.test.ts`
+
+**Verifies:**
+- Authoritative sink failure triggers fallback
+- Evidence is preserved via emergency spool
+- DEGRADED vs FAILED states are distinguished
+- No silent evidence loss
+
+**Audit Guarantees Proven:**
+- Evidence durability under failure
+- Correct degraded-mode semantics
+- Compliance with prior audit remediation
+
+---
+
+## 7. Message & Context Safety
+
+### `message_constraints.test.ts`
+
+**Verifies:**
+- Message size limits are enforced
+- Invalid payloads are rejected deterministically
+- Context constraints are strictly applied
+- No implicit truncation occurs
+
+**Audit Guarantees Proven:**
+- LLM-context containment
+- Deterministic rejection behavior
+- Injection resistance
+
+---
+
+## 8. Evidence Persistence
+
+### `sinks_file_ndjson.test.ts`
+
+**Verifies:**
+- Correct NDJSON output format
+- One record per line
+- No partial or corrupted writes
+- Correct behavior across multiple writes
+
+**Audit Guarantees Proven:**
+- Evidence persistence correctness
+- Replay-friendly storage format
+- No corruption across steps
+
+---
+
+## 9. Contract Compliance
+
+### `step1_compliance.test.ts`
+
+**Verifies:**
+- End-to-end compliance with Step Record v1
+- Presence of all required baseline fields
+- Absence of forbidden or extraneous fields
+
+**Audit Guarantees Proven:**
+- Contract fidelity
+- No schema drift
+- Downstream consumer safety
+
+---
+
+## 10. Explicit Non-Coverage (Declared)
+
+The following are **explicitly not tested** (by design, not omission):
+
+- Cross-process replay
+- Multi-runtime adapters (Node.js is the defined runtime)
+- Performance or throughput characteristics
+- Long-running memory behavior
+- External sink integrations beyond file/stdout
+
+These are **out of scope** for the current audit and freeze-gate.
+
+---
+
+## 11. Coverage-to-Audit Mapping
+
+| Audit Dimension | Coverage |
+|----------------|----------|
+| Determinism | ✅ |
+| Ordering | ✅ |
+| Evidence durability | ✅ |
+| Degraded vs failed semantics | ✅ |
+| Step Record integrity | ✅ |
+| Downstream compatibility | ✅ |
+| LLM context safety | ✅ |
+| Authority discipline | ✅ |
+
+---
+
+## 12. Audit Statement
+
+> **The existing LogSDK test suite provides deterministic, contract-level coverage of sequencing, record integrity, fan-out semantics, degraded evidence handling, and context safety sufficient for freeze-gate validation.**
+
+---
+
+**Document Classification:** Non-authoritative audit evidence  
+**Generated From:** Existing tests only  
+**Change Policy:** Update only if tests change
+

package/docs/prompts/AuditorSDK.txt

@@ -0,0 +1,214 @@
+# 🧩 LogSDK RE-AUDIT PROMPT (Freeze-Gate Validation)
+
+## ROLE
+
+You are an **independent senior logging and distributed-systems auditor**
+with **20+ years of experience** across:
+
+* long-running processes
+* distributed pipelines
+* HTTP / request-response systems
+* content and publishing systems
+* multi-runtime environments (Node.js, Python, CLI, workers)
+* audit-, evidence-, and compliance-critical platforms
+
+You are performing a **FORMAL RE-AUDIT** of **LogSDK**
+**after remediation of previously identified audit findings**.
+
+You are **NOT a contributor**.
+You have **NO authority** to redesign, extend, or optimize the SDK.
+
+---
+
+## MODE
+
+**READ-ONLY RE-AUDIT / FREEZE-GATE VALIDATION**
+
+This is a **verification exercise**, not a design review.
+
+---
+
+## NON-NEGOTIABLE CONSTRAINTS
+
+### ❌ YOU MUST NOT
+
+* redesign or re-architect the SDK
+* add or suggest new APIs
+* introduce configuration options
+* refactor internal structure
+* optimize for performance or ergonomics
+* weaken governance, determinism, or evidence guarantees
+* propose future improvements beyond audit findings
+
+### ✅ YOU MUST
+
+* validate remediation **against prior audit findings**
+* detect **regressions or newly introduced violations**
+* verify **determinism, immutability, and evidence safety**
+* confirm **downstream compatibility is preserved**
+* issue **explicit PASS / FAIL / RISK findings**
+
+---
+
+## AUDIT SCOPE (MANDATORY)
+
+You MUST re-scan the **entire LogSDK repository**, including but not limited to:
+
+* core SDK logic
+* sequence and clock generation
+* step record construction
+* fan-out and sink handling
+* emergency spool / degraded-mode logic (if present)
+* validation and guard layers
+* tests and fixtures
+* documentation and specifications
+
+⚠️ **NO FILE, DIRECTORY, OR PATH MAY BE SKIPPED**
+⚠️ **ASSUME NOTHING IS CORRECT BY DEFAULT**
+
+---
+
+## AUTHORITATIVE BASELINE (HARD CONTRACTS)
+
+All validation must be performed strictly against these **non-negotiable references**:
+
+1. `governance/contracts/step-record.v1.md`
+2. **LogSDK Functional Specification v1.1**
+3. `/audit/logsdk_deep_audit_report.json` (PREVIOUS AUDIT FINDINGS)
+
+Your sole task is to verify **alignment AFTER remediation**.
+
+---
+
+## RE-AUDIT OBJECTIVES
+
+**ALL OBJECTIVES ARE REQUIRED FOR A PASS**
+
+---
+
+### 1️⃣ Verification of Prior Audit Issue Resolution
+
+You MUST explicitly verify the following previously identified issues:
+
+* Sequence numbering **starts at `0`**
+* Sequence increments **strictly and monotonically**
+* `monotonic_time` is **strictly increasing**, even across rapid successive `step()` calls
+* Fan-out semantics explicitly support:
+
+  * **OK** — all sinks succeed
+  * **DEGRADED** — authoritative evidence preserved, secondary sinks fail
+  * **FAILED** — authoritative evidence lost
+* Authoritative sink failures **do not silently drop evidence**
+* Emergency spool / fallback path exists and is correctly engaged (if specified)
+* Node.js runtime assumptions are **explicitly documented** and not implicit
+
+Each prior issue MUST be classified as:
+
+* **RESOLVED**
+* **PARTIALLY RESOLVED**
+* **NOT RESOLVED**
+
+No issue may be skipped or implicitly assumed resolved.
+
+---
+
+### 2️⃣ Regression Detection (Critical)
+
+You MUST verify that remediation has **NOT introduced** any of the following:
+
+* changes to the **Canonical Step Record shape**
+* new fields, removed fields, or reordered fields
+* changes to message or context constraints
+* changes to the public API (`log.step(message: string)`)
+* implicit per-step context injection
+* weakened immutability or hashing guarantees
+* altered downstream usage semantics
+* behavioral drift observable by existing consumers
+
+Any regression must be explicitly called out.
+
+---
+
+### 3️⃣ Determinism & Replay Safety (Re-Validation)
+
+You MUST confirm that:
+
+* canonical serialization is unchanged
+* record hashing is stable and deterministic
+* replay of identical executions produces **equivalent evidence**
+* ordering guarantees are preserved under all execution modes
+* no hidden sources of nondeterminism were introduced
+
+---
+
+### 4️⃣ Downstream Compatibility Verification
+
+You MUST explicitly validate that existing downstream usage patterns remain valid, including but not limited to:
+
+```ts
+log.step("schema apply completed: X");
+log.step("validation failed: missing field Y");
+log.step(`write completed for ${entityId}`);
+```
+
+Specifically confirm that:
+
+* no caller code changes are required
+* message-only invocation remains valid
+* no new required parameters exist
+* existing sinks and consumers continue to function unchanged
+* no implicit behavioral coupling was introduced
+
+---
+
+### 5️⃣ Documentation Alignment Check
+
+You MUST verify that:
+
+* documentation accurately reflects current behavior
+* no undocumented behavior changes exist
+* remediation changes are correctly described (if applicable)
+* no misleading or stale guarantees remain
+
+---
+
+## REQUIRED OUTPUT FORMAT
+
+Your response MUST be structured as follows:
+
+1. **Executive Re-Audit Summary**
+2. **Prior Findings Resolution Table** (Issue → Status → Evidence)
+3. **Regression Scan Results**
+4. **Determinism & Replay Validation**
+5. **Downstream Compatibility Assessment**
+6. **Documentation Alignment Findings**
+7. **Final Freeze-Gate Verdict**
+
+---
+
+## FINAL VERDICT RULE
+
+A **FREEZE-ELIGIBLE PASS** may be issued **ONLY IF**:
+
+* all prior issues are RESOLVED or ACCEPTABLY PARTIAL (with justification)
+* zero regressions are detected
+* determinism and replay safety are confirmed
+* downstream compatibility is preserved
+
+Otherwise, the verdict MUST be **FAIL** or **CONDITIONAL FAIL** with explicit reasons.
+
+---
+
+### 🧠 Closing Principle (Implicit but Binding)
+
+> This audit verifies **trustworthiness, not elegance**.
+> Stability, determinism, and evidence safety override all other considerations.
+
+---
+
+If you want, next I can:
+
+* convert this into a **CI-enforced audit harness**
+* align it with **UnifyPlane CIA readiness validation**
+* or create a **multi-repo standardized audit template**
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@unifyplane/logsdk",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "verify": "node tools/test_results/run-tests-then-prebuild.js",
+    "build": "npm run verify && npm run build:impl",
+    "build:impl": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "crypto": "^1.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0",
+    "ts-node": "^10.9.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js"
+    }
+  }
+}

package/src/core/clock.ts

@@ -0,0 +1,25 @@
+let lastMonotonic = 0;
+const hasPerformance =
+  typeof performance !== "undefined" && typeof performance.now === "function";
+const epochStart = Date.now();
+
+export function nowUtcIso(): string {
+  return new Date().toISOString();
+}
+
+export function monotonicNow(): number {
+  let current: number;
+
+  if (hasPerformance) {
+    current = epochStart + performance.now();
+  } else {
+    current = Date.now();
+  }
+
+  if (current <= lastMonotonic) {
+    current = lastMonotonic + 1;
+  }
+
+  lastMonotonic = current;
+  return current;
+}

package/src/core/context.ts

@@ -0,0 +1,142 @@
+/// <reference path="../crypto-shim.d.ts" />
+
+import { createHash } from "crypto";
+
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+type ContextState = {
+  value: JsonValue;
+  hash: string;
+  version: string;
+  initialized: boolean;
+};
+
+const DEFAULT_CONTEXT_VERSION = "log.context.v1";
+
+const state: ContextState = {
+  value: {},
+  hash: "",
+  version: DEFAULT_CONTEXT_VERSION,
+  initialized: false,
+};
+
+export function initContext(
+  context: unknown,
+  version: string = DEFAULT_CONTEXT_VERSION
+): void {
+  if (state.initialized) {
+    throw new Error("Context already initialized");
+  }
+
+  if (!context || typeof context !== "object" || Array.isArray(context)) {
+    throw new Error("Context must be a non-array object");
+  }
+
+  const normalized = normalizeJsonValue(context, "$");
+  const canonical = stableStringify(normalized);
+  const hash = createHash("sha256").update(canonical).digest("hex");
+
+  state.value = deepFreeze(normalized);
+  state.hash = hash;
+  state.version = version;
+  state.initialized = true;
+}
+
+export function getContextHash(): string {
+  if (!state.initialized) {
+    throw new Error("Context not initialized");
+  }
+  return state.hash;
+}
+
+export function getContextVersion(): string {
+  if (!state.initialized) {
+    throw new Error("Context not initialized");
+  }
+  return state.version;
+}
+
+export function resetContextForTests(): void {
+  state.value = {};
+  state.hash = "";
+  state.version = DEFAULT_CONTEXT_VERSION;
+  state.initialized = false;
+}
+
+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 normalizeJsonValue(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) =>
+      normalizeJsonValue(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).sort();
+
+    for (const key of keys) {
+      const next = obj[key];
+      if (next === undefined) {
+        throw new Error(`Undefined value at ${path}.${key}`);
+      }
+      result[key] = normalizeJsonValue(next, `${path}.${key}`);
+    }
+
+    return result;
+  }
+
+  throw new Error(`Unsupported type at ${path}`);
+}
+
+function stableStringify(value: JsonValue): string {
+  return JSON.stringify(value);
+}

package/src/core/fanout.ts

@@ -0,0 +1,38 @@
+import type { SinkEntry, StepRecord } from "../sinks/sink_types";
+import { assertHasAuthoritativeSink } from "../validate/schema_guard";
+import { writeEmergencySpool } from "./spool";
+
+export type FanoutOutcome = "OK" | "DEGRADED" | "FAILED";
+
+export async function fanout(
+  record: StepRecord,
+  sinks: ReadonlyArray<SinkEntry>
+): Promise<FanoutOutcome> {
+  assertHasAuthoritativeSink(sinks);
+  const frozenRecord = Object.isFrozen(record) ? record : Object.freeze(record);
+  let outcome: FanoutOutcome = "OK";
+  let spooled = false;
+
+  for (const entry of sinks) {
+    try {
+      await entry.sink.emit(frozenRecord);
+    } catch {
+      if (entry.sinkClass === "authoritative") {
+        if (!spooled) {
+          try {
+            await writeEmergencySpool(frozenRecord);
+            outcome = "DEGRADED";
+            spooled = true;
+          } catch {
+            outcome = "FAILED";
+          }
+        }
+        if (outcome === "FAILED") {
+          break;
+        }
+      }
+    }
+  }
+
+  return outcome;
+}

package/src/core/ids.ts

@@ -0,0 +1,35 @@
+import { monotonicNow } from "./clock";
+
+export interface IdGenerator {
+  nextRecordId(): string;
+  nextSequence(): number;
+}
+
+const processStart = Date.now().toString(36);
+let instanceCounter = 0;
+
+function sanitizeTag(tag: string): string {
+  return tag.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 32);
+}
+
+export function createIdGenerator(instanceTag?: string): IdGenerator {
+  const instanceId = ++instanceCounter;
+  let sequence = 0;
+  let localCounter = 0;
+  const tag = instanceTag ? sanitizeTag(instanceTag) : "";
+
+  return {
+    nextSequence() {
+      const current = sequence;
+      sequence += 1;
+      return current;
+    },
+    nextRecordId() {
+      localCounter += 1;
+      const timePart = Math.floor(monotonicNow()).toString(36);
+      const counterPart = localCounter.toString(36);
+      const tagPart = tag ? `_${tag}` : "";
+      return `rec_${processStart}_${instanceId}${tagPart}_${timePart}_${counterPart}`;
+    },
+  };
+}