okengine 0.1.4

package/src/manifest/undeclared.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Undeclared contract-break filter — console §9.12 CI gate.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Flow, Manifest } from "./types.ts";
+import { undeclaredContractBreaks } from "./undeclared.ts";
+import { parseManifest } from "./validate.ts";
+
+const baseUrl = new URL("./fixtures/base.manifest.json", import.meta.url);
+
+async function loadBase(): Promise<Manifest> {
+  return parseManifest(await Bun.file(baseUrl).text());
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+/** Remove a named error from a flow (array or map form). */
+function removeError(flow: Flow, name: string): void {
+  const errors = flow.errors;
+  if (Array.isArray(errors)) {
+    flow.errors = errors.filter((e) => e !== name);
+  } else if (errors && typeof errors === "object") {
+    const next = { ...errors };
+    delete next[name];
+    flow.errors = next;
+  }
+}
+
+describe("undeclaredContractBreaks", () => {
+  test("blocks contract-breaking changes without breaking: true", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    removeError(after.flows!["reports.export"]!, "Forbidden");
+
+    const undeclared = undeclaredContractBreaks(before, after);
+    expect(undeclared.length).toBeGreaterThan(0);
+    expect(undeclared.some((c) => c.path.includes("Forbidden"))).toBe(true);
+  });
+
+  test("allows contract breaks when the owning flow sets breaking: true", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    removeError(after.flows!["reports.export"]!, "Forbidden");
+    after.flows!["reports.export"]!.breaking = true;
+
+    const undeclared = undeclaredContractBreaks(before, after);
+    expect(
+      undeclared.filter((c) => c.path.includes("reports.export")),
+    ).toHaveLength(0);
+  });
+
+  test("does not let one flow's breaking: true cover another flow", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    after.flows!["orders.create"]!.breaking = true;
+    removeError(after.flows!["reports.export"]!, "Forbidden");
+
+    const undeclared = undeclaredContractBreaks(before, after);
+    expect(undeclared.length).toBeGreaterThan(0);
+    expect(undeclared.some((c) => c.path.includes("reports.export"))).toBe(
+      true,
+    );
+    expect(
+      undeclared.every((c) => !c.path.includes("orders.create")),
+    ).toBe(true);
+  });
+
+  test("flow removal is allowed when baseline had breaking: true", async () => {
+    const before = await loadBase();
+    before.flows!["orders.create"]!.breaking = true;
+    const after = clone(before);
+    delete after.flows!["orders.create"];
+
+    const undeclared = undeclaredContractBreaks(before, after);
+    expect(
+      undeclared.filter((c) => c.path.includes("orders.create")),
+    ).toHaveLength(0);
+  });
+});

package/src/manifest/undeclared.ts

@@ -0,0 +1,65 @@
+/**
+ * Undeclared contract-break filter for the CI gate (console §9.12).
+ *
+ * The gate blocks the *undeclared* break, not the break. Setting
+ * `breaking: true` on a flow allows that flow's contract-breaking changes
+ * through; other flows without the acknowledgement still fail the gate.
+ */
+
+import { diffManifest } from "./diff.ts";
+import type { Manifest, ManifestChange } from "./types.ts";
+
+/**
+ * Contract-breaking changes that lack a `breaking: true` acknowledgement
+ * on the owning flow.
+ *
+ * @param before - Baseline manifest
+ * @param after - Candidate manifest
+ */
+export function undeclaredContractBreaks(
+  before: Manifest,
+  after: Manifest,
+): readonly ManifestChange[] {
+  const { changes } = diffManifest(before, after);
+  return changes.filter(
+    (c) =>
+      c.category === "contract-breaking" && !isDeclaredBreak(c, before, after),
+  );
+}
+
+/**
+ * Whether a contract-breaking change is acknowledged via `breaking: true`.
+ *
+ * @param change - Classified change
+ * @param before - Baseline
+ * @param after - Candidate
+ */
+export function isDeclaredBreak(
+  change: ManifestChange,
+  before: Manifest,
+  after: Manifest,
+): boolean {
+  const flowName = flowNameFromPath(change.path);
+  if (flowName === null) return false;
+
+  const afterFlow = after.flows?.[flowName];
+  if (afterFlow?.breaking === true) return true;
+
+  // Flow removal: acknowledgement lives on the baseline declaration.
+  if (change.kind === "removed") {
+    const beforeFlow = before.flows?.[flowName];
+    if (beforeFlow?.breaking === true) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Extract `/flows/{name}` from a Manifest Diff path.
+ *
+ * @param path - Change path (e.g. `/flows/orders.create/trigger`)
+ */
+export function flowNameFromPath(path: string): string | null {
+  const match = /^\/flows\/([^/]+)/.exec(path);
+  return match?.[1] ?? null;
+}

package/src/manifest/validate.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+  assertLosslessRoundTrip,
+  loadManifestSchema,
+  ManifestValidationError,
+  manifestSchemaUrl,
+  parseManifest,
+  serializeManifest,
+  validateManifest,
+} from "./validate.ts";
+
+const skyportUrl = new URL("./fixtures/skyport.manifest.json", import.meta.url);
+const baseUrl = new URL("./fixtures/base.manifest.json", import.meta.url);
+
+describe("validateManifest", () => {
+  test("schema document loads and declares oke 1.0", async () => {
+    const schema = (await loadManifestSchema()) as {
+      properties: { oke: { const: string } };
+    };
+    expect(schema.properties.oke.const).toBe("1.0");
+    expect(manifestSchemaUrl().href).toContain("manifest.v1.schema.json");
+  });
+
+  test("accepts the Skyport manifest excerpt (expanded fixture)", async () => {
+    const text = await Bun.file(skyportUrl).text();
+    const value = JSON.parse(text) as unknown;
+    const result = await validateManifest(value);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.manifest.app).toBe("skyport");
+      expect(result.manifest.flows?.["bookings.create"]?.errors).toEqual([
+        "FlightFull",
+      ]);
+      expect(result.manifest.tenancy?.isolation).toBe("row");
+    }
+  });
+
+  test("accepts the literal Skyport excerpt from the spec (string schema placeholders)", async () => {
+    const excerptUrl = new URL("./fixtures/skyport.excerpt.json", import.meta.url);
+    const text = await Bun.file(excerptUrl).text();
+    const result = await validateManifest(JSON.parse(text));
+    expect(result.ok).toBe(true);
+  });
+
+  test("accepts the base fixture", async () => {
+    const text = await Bun.file(baseUrl).text();
+    const result = await validateManifest(JSON.parse(text));
+    expect(result.ok).toBe(true);
+  });
+
+  test("rejects a document with the wrong oke version", async () => {
+    const result = await validateManifest({ oke: "2.0", app: "x" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.length).toBeGreaterThan(0);
+      expect(result.issues.some((i) => i.path === "/oke" || i.path === "/")).toBe(
+        true,
+      );
+    }
+  });
+
+  test("rejects a signal missing mandatory delivery", async () => {
+    const result = await validateManifest({
+      oke: "1.0",
+      app: "x",
+      signals: { ping: { retries: 1 } },
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects an invalid resource ref facet", async () => {
+    const result = await validateManifest({
+      oke: "1.0",
+      app: "x",
+      flows: {
+        f: { effects: { reads: ["mongo:users"] } },
+      },
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  test("parseManifest throws ManifestValidationError on invalid JSON", async () => {
+    expect(parseManifest("{")).rejects.toBeInstanceOf(ManifestValidationError);
+  });
+
+  test("parseManifest throws on schema-invalid documents", async () => {
+    expect(parseManifest(JSON.stringify({ oke: "1.0" }))).rejects.toBeInstanceOf(
+      ManifestValidationError,
+    );
+  });
+
+  test("round-trip parse/serialise is lossless for Skyport", async () => {
+    const text = await Bun.file(skyportUrl).text();
+    const again = await assertLosslessRoundTrip(text);
+    expect(again.app).toBe("skyport");
+    const serialised = serializeManifest(again);
+    const third = await parseManifest(serialised);
+    expect(third).toEqual(again);
+  });
+
+  test("round-trip parse/serialise is lossless for base", async () => {
+    const text = await Bun.file(baseUrl).text();
+    await assertLosslessRoundTrip(text);
+  });
+});

package/src/manifest/validate.ts

@@ -0,0 +1,174 @@
+/**
+ * Runtime validation of Manifest documents against `spec/manifest.v1.schema.json`.
+ */
+
+import Ajv2020, {
+  type AnySchema,
+  type ErrorObject,
+} from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import type { Manifest } from "./types.ts";
+
+/** A single schema violation. */
+export interface ManifestValidationIssue {
+  /** JSON Pointer path, when available. */
+  path: string;
+  message: string;
+  keyword?: string;
+}
+
+/** Outcome of {@link validateManifest}. */
+export type ManifestValidationResult =
+  | { ok: true; manifest: Manifest }
+  | { ok: false; issues: ManifestValidationIssue[] };
+
+const SCHEMA_URL = new URL(
+  "../../spec/manifest.v1.schema.json",
+  import.meta.url,
+);
+
+let validator: ReturnType<Ajv2020["compile"]> | undefined;
+let schemaDocument: unknown;
+
+/**
+ * URL of the versioned public schema (readable without okengine runtime code).
+ */
+export function manifestSchemaUrl(): URL {
+  return SCHEMA_URL;
+}
+
+/**
+ * Load (and cache) the Manifest v1 JSON Schema document.
+ */
+export async function loadManifestSchema(): Promise<unknown> {
+  if (schemaDocument !== undefined) return schemaDocument;
+  const text = await Bun.file(SCHEMA_URL).text();
+  schemaDocument = JSON.parse(text) as unknown;
+  return schemaDocument;
+}
+
+function getValidator(schema: unknown): ReturnType<Ajv2020["compile"]> {
+  if (validator) return validator;
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    validateSchema: true,
+  });
+  addFormats(ajv);
+  validator = ajv.compile(schema as AnySchema);
+  return validator;
+}
+
+function issueFromError(error: ErrorObject): ManifestValidationIssue {
+  const path = error.instancePath === "" ? "/" : error.instancePath;
+  const message = error.message ?? "validation failed";
+  return {
+    path,
+    message: error.params ? `${message} (${JSON.stringify(error.params)})` : message,
+    keyword: error.keyword,
+  };
+}
+
+/**
+ * Validate an unknown value as a Manifest v1 document.
+ *
+ * Pure with respect to the input — does not mutate `input`.
+ */
+export async function validateManifest(
+  input: unknown,
+): Promise<ManifestValidationResult> {
+  const schema = await loadManifestSchema();
+  const validate = getValidator(schema);
+  const ok = validate(input);
+  if (ok) {
+    return { ok: true, manifest: input as Manifest };
+  }
+  const errors = validate.errors ?? [];
+  return {
+    ok: false,
+    issues: errors.map(issueFromError),
+  };
+}
+
+/**
+ * Parse JSON text, validate, and return a typed Manifest.
+ *
+ * @throws {ManifestValidationError} when the document is invalid
+ */
+export async function parseManifest(text: string): Promise<Manifest> {
+  let value: unknown;
+  try {
+    value = JSON.parse(text) as unknown;
+  } catch (cause) {
+    throw new ManifestValidationError(
+      [{ path: "/", message: `invalid JSON: ${String(cause)}` }],
+      cause,
+    );
+  }
+  const result = await validateManifest(value);
+  if (!result.ok) {
+    throw new ManifestValidationError(result.issues);
+  }
+  return result.manifest;
+}
+
+/**
+ * Serialise a Manifest to stable, lossless JSON text (2-space indent + trailing newline).
+ */
+export function serializeManifest(manifest: Manifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * Round-trip: parse → serialise → parse, asserting structural equality.
+ *
+ * @returns the re-parsed Manifest when lossless
+ * @throws {Error} when the round-trip is lossy
+ */
+export async function assertLosslessRoundTrip(text: string): Promise<Manifest> {
+  const first = await parseManifest(text);
+  const again = await parseManifest(serializeManifest(first));
+  if (!stableEqual(first, again)) {
+    throw new Error("manifest round-trip was lossy");
+  }
+  return again;
+}
+
+/**
+ * Error raised when a document fails Manifest schema validation.
+ */
+export class ManifestValidationError extends Error {
+  /** Structured validation issues. */
+  readonly issues: ManifestValidationIssue[];
+
+  /**
+   * @param issues - schema violations
+   * @param cause - optional parse cause
+   */
+  constructor(issues: ManifestValidationIssue[], cause?: unknown) {
+    const summary = issues
+      .map((i) => `${i.path}: ${i.message}`)
+      .join("; ");
+    super(`Invalid Manifest: ${summary}`, cause !== undefined ? { cause } : undefined);
+    this.name = "ManifestValidationError";
+    this.issues = issues;
+  }
+}
+
+/** Deep equality after sorting object keys (order-insensitive objects, order-sensitive arrays). */
+function stableEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value !== null && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      out[key] = sortKeys(obj[key]);
+    }
+    return out;
+  }
+  return value;
+}