Merge pull request #64 from CeceOs92/feat/50-51-52-55-telemetry-workers-exports-contract

feat/telemetry-workers-exports-contract

Author: BigDella

README.md

@@ -20,6 +20,10 @@ contributors work in parallel without ever conflicting.
 See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and
 [docs/FEATURE_CONTRACT.md](./docs/FEATURE_CONTRACT.md).
 
+Infrastructure docs: [Telemetry](./docs/TELEMETRY.md) ·
+[Workers](./docs/WORKERS.md) · [Exports](./docs/EXPORTS.md) ·
+[API Contract](./docs/API_CONTRACT.md).
+
 ## Tools
 
 | Tool | What it does |
@@ -66,6 +70,9 @@ npm run registry             # regenerate the feature registry
 npm run new:feature          # scaffold a complete feature slice
 npm run verify:features      # check every slice against the feature contract
 npm run verify:issues        # check 40+ independent issues and the advanced wave
+npm run verify:telemetry     # verify >= 5 operations are instrumented
+npm run verify:contract      # run the API contract drift tests
+npm run test:workers         # run the background worker suite
 npm run issues               # preview the next five GrantFox issue payloads
 npm run test                 # unit, hook, component and accessibility tests
 npm run test:coverage        # unit tests with a coverage summary

core/contract/__tests__/contract.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import {
+  TELEMETRY_FIELDS,
+  measure,
+  newCorrelationId,
+  resetTelemetrySink,
+  setTelemetrySink,
+  type TelemetryEvent
+} from "@/core/telemetry/telemetry";
+import { classifyHorizonError } from "@/core/horizon/errors";
+import { createWorkerFramework, type JobPayload } from "@/core/workers/queue";
+import { ok } from "@/core/result/result";
+import {
+  EXPORT_CURRENT_SCHEMA_VERSION,
+  exportRecords,
+  type ExportRecordSource
+} from "@/core/export/exporter";
+import type { FeatureManifest } from "@/core/registry/types";
+import { manifest as paymentQrManifest } from "@/features/payment-qr/manifest";
+import {
+  assertContract,
+  contractOperation,
+  validateContract
+} from "@/core/contract/contract";
+
+const V = "1.0";
+
+// The five contracts documented in docs/API_CONTRACT.md, kept in lockstep with
+// the real modules below. When a module changes a shape used by consumers,
+// this file must change too — which is the point of a drift test.
+
+const telemetryContract = contractOperation("telemetry.event", {
+  version: V,
+  fields: {
+    op: { type: "string", required: true },
+    actorType: { type: "string", required: true },
+    result: { type: "string", required: true },
+    latencyMs: { type: "number", required: true },
+    correlationId: { type: "string", required: true }
+  }
+});
+
+const horizonErrorContract = contractOperation("horizon.error", {
+  version: V,
+  fields: {
+    code: { type: "string", required: true },
+    detail: { type: "object", required: true },
+    "detail.status": { type: "number", required: false }
+  }
+});
+
+const workerJobContract = contractOperation("worker.job", {
+  version: V,
+  fields: {
+    id: { type: "string", required: true },
+    operation: { type: "string", required: true },
+    attempts: { type: "number", required: true },
+    status: { type: "string", required: true },
+    enqueuedAt: { type: "string", required: true },
+    correlationId: { type: "string", required: true }
+  }
+});
+
+const exportEnvelopeContract = contractOperation("export.envelope", {
+  version: V,
+  fields: {
+    schemaVersion: { type: "string", required: true },
+    generatedAt: { type: "string", required: true },
+    expiresAt: { type: "string", required: true },
+    generator: { type: "string", required: true },
+    correlationId: { type: "string", required: true },
+    recordCount: { type: "number", required: true },
+    totalRecords: { type: "number", required: true },
+    records: { type: "array", required: true }
+  }
+});
+
+const featureManifestContract = contractOperation("feature.manifest", {
+  version: V,
+  fields: {
+    slug: { type: "string", required: true },
+    title: { type: "string", required: true },
+    description: { type: "string", required: true },
+    category: { type: "string", required: true },
+    status: { type: "string", required: true }
+  }
+});
+
+async function realTelemetryEvent(): Promise<TelemetryEvent> {
+  let seen: TelemetryEvent | undefined;
+  setTelemetrySink({ emit: (event) => (seen = event) });
+
+  const correlationId = newCorrelationId();
+  await measure("horizon.request", { actorType: "client", correlationId }, () => ok(true));
+  resetTelemetrySink();
+
+  if (!seen) throw new Error("no telemetry emitted");
+  return seen;
+}
+
+describe("contract drift tests", () => {
+  it("locks the telemetry record shape to what the module emits", async () => {
+    const record = await realTelemetryEvent();
+    expect(TELEMETRY_FIELDS.every((field) => field in record)).toBe(true);
+    expect(assertContract(telemetryContract, () => record).ok).toBe(true);
+  });
+
+  it("locks the horizon error classification shape", () => {
+    const classified = classifyHorizonError({ response: { status: 429 } });
+    expect(assertContract(horizonErrorContract, () => classified).ok).toBe(true);
+  });
+
+  it("locks the worker job payload shape", () => {
+    const framework = createWorkerFramework();
+    const job: JobPayload = framework.enqueue({ operation: "demo.run" });
+    expect(assertContract(workerJobContract, () => job).ok).toBe(true);
+  });
+
+  it("locks the export envelope shape", () => {
+    const source: ExportRecordSource = {
+      recordType: "operation_log",
+      schemaVersion: EXPORT_CURRENT_SCHEMA_VERSION,
+      scope: "own",
+      collect: () => [{ op: "wallet.detect", result: "success" }]
+    };
+    const result = exportRecords(
+      { schemaVersion: EXPORT_CURRENT_SCHEMA_VERSION, scope: "own", actor: { kind: "user" } },
+      [source]
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(assertContract(exportEnvelopeContract, () => result.value).ok).toBe(true);
+  });
+
+  it("locks the feature manifest shape", () => {
+    const manifest: FeatureManifest = paymentQrManifest;
+    expect(assertContract(featureManifestContract, () => manifest).ok).toBe(true);
+  });
+
+  it("detects a drifted response that drops a required field", () => {
+    const drifted = { detail: {}, status: 200 }; // `code` is required
+    expect(validateContract(drifted, horizonErrorContract.schema).ok).toBe(false);
+    expect(assertContract(horizonErrorContract, () => drifted).ok).toBe(false);
+  });
+});

core/contract/contract.ts

@@ -0,0 +1,125 @@
+/**
+ * Public API contract documentation support and drift detection.
+ *
+ * Utix exposes no external HTTP API — it is a read-only browser toolkit — so
+ * the "public API" is the stable shape of the operations integration points
+ * call and consumers rely on: error classifications, telemetry records, worker
+ * jobs, export envelopes and feature manifests.
+ *
+ * Each operation gets a locked `ContractSchema`. Drift tests capture the real
+ * output of the operation and assert it still satisfies the schema, so an
+ * incompatible change to a response shape fails CI instead of silently
+ * breaking a downstream consumer.
+ */
+
+import { err, ok, type Result } from "@/core/result/result";
+import { measureSync } from "@/core/telemetry/telemetry";
+
+export type ContractErrorCode = "contract_drift" | "missing_required_field" | "wrong_type";
+
+export type ContractFieldType = "string" | "number" | "boolean" | "object" | "array";
+
+export interface ContractField {
+  type: ContractFieldType;
+  required?: boolean;
+  /** Dot-nested path when the value lives inside an object/array. */
+  path?: string;
+}
+
+export interface ContractSchema {
+  /** Stable contract version; bumps on any breaking change. */
+  version: string;
+  fields: Record<string, ContractField>;
+}
+
+export interface ContractOperation {
+  name: string;
+  schema: ContractSchema;
+}
+
+function fieldValue(root: unknown, path: string | undefined): unknown {
+  if (!path) return root;
+  let cursor: unknown = root;
+  for (const segment of path.split(".")) {
+    if (cursor === null || cursor === undefined) return undefined;
+    if (Array.isArray(cursor) && /^\d+$/.test(segment)) cursor = cursor[Number(segment)];
+    else if (typeof cursor === "object") cursor = (cursor as Record<string, unknown>)[segment];
+    else return undefined;
+  }
+  return cursor;
+}
+
+function matchesType(value: unknown, type: ContractFieldType): boolean {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+  }
+}
+
+/**
+ * Validates an actual value against a locked schema. Returns
+ * `contract_drift` (first field that no longer matches) or `ok`.
+ */
+export function validateContract(
+  actual: unknown,
+  schema: ContractSchema
+): Result<true, ContractErrorCode> {
+  if (typeof actual !== "object" || actual === null) {
+    return err("contract_drift");
+  }
+
+  for (const [name, field] of Object.entries(schema.fields)) {
+    if (!field.required) continue;
+    const value = fieldValue(actual, field.path ?? name);
+    if (value === undefined) return err("missing_required_field");
+    if (!matchesType(value, field.type)) return err("wrong_type");
+  }
+
+  return ok(true);
+}
+
+/**
+ * Registers an operation contract against the documented schema. Used by the
+ * drift tests and by `docs/API_CONTRACT.md` examples.
+ */
+export function contractOperation(name: string, schema: ContractSchema): ContractOperation {
+  return { name, schema };
+}
+
+/**
+ * Runs `capture` (the real implementation) and checks the result against the
+ * locked schema, emitting `contract.validate` telemetry in the process.
+ */
+export function assertContract(
+  operation: ContractOperation,
+  capture: () => unknown
+): Result<true, ContractErrorCode> {
+  return measureSync(
+    "contract.validate",
+    { actorType: "system", payload: { contract: operation.name } },
+    () => {
+      const actual = capture();
+      const validated = validateContract(actual, operation.schema);
+      return validated.ok ? ok(true) : err("contract_drift");
+    }
+  );
+}
+
+/** Convenience for error-shaped results: `{ code, detail }`. */
+export function errorSchema(version: string): ContractSchema {
+  return {
+    version,
+    fields: {
+      code: { type: "string", required: true },
+      detail: { type: "object", required: false }
+    }
+  };
+}