okengine 0.1.4

package/src/manifest/fixtures/base.manifest.json

@@ -0,0 +1,112 @@
+{
+  "oke": "1.0",
+  "app": "demo",
+  "flows": {
+    "reports.export": {
+      "trigger": { "http": { "method": "GET", "path": "/reports/export" } },
+      "gates": ["staff"],
+      "in": {
+        "type": "object",
+        "properties": {
+          "format": { "type": "string", "enum": ["csv", "json"] }
+        }
+      },
+      "out": {
+        "type": "object",
+        "required": ["url"],
+        "properties": {
+          "url": { "type": "string" }
+        }
+      },
+      "errors": ["NotFound", "Forbidden"],
+      "effects": {
+        "reads": ["sql:reports"],
+        "writes": [],
+        "emits": [],
+        "sends": [],
+        "asks": [],
+        "secrets": [],
+        "calls": []
+      },
+      "plane": "user",
+      "source": "src/flows/reports.ts:10",
+      "slo": { "availability": "99.9%", "latency": { "p99": "200ms" } }
+    },
+    "orders.create": {
+      "trigger": { "http": { "method": "POST", "path": "/orders" } },
+      "gates": ["member", "rate:sliding-window-counter:300/1m"],
+      "in": {
+        "type": "object",
+        "required": ["sku"],
+        "properties": {
+          "sku": { "type": "string" },
+          "qty": { "type": "integer" }
+        }
+      },
+      "out": {
+        "type": "object",
+        "required": ["id"],
+        "properties": { "id": { "type": "string" } }
+      },
+      "errors": ["OutOfStock"],
+      "effects": {
+        "reads": ["sql:orders"],
+        "writes": ["sql:orders"],
+        "emits": ["order-placed"]
+      },
+      "source": "src/flows/orders.ts:4"
+    }
+  },
+  "signals": {
+    "order-placed": { "delivery": "once", "retries": 5, "deadLetter": true }
+  },
+  "stores": {
+    "db": {
+      "facet": "sql",
+      "tables": {
+        "orders": {
+          "classifications": {
+            "email": { "pii": true }
+          }
+        },
+        "reports": {}
+      }
+    }
+  },
+  "clocks": {
+    "nightly": { "cron": "0 0 * * *", "timezone": "UTC" }
+  },
+  "gates": {
+    "staff": { "kind": "policy", "roles": ["staff"] },
+    "member": { "kind": "policy", "roles": ["member"] }
+  },
+  "vault": {
+    "STRIPE_KEY": { "description": "stripe", "schema": { "type": "string" } }
+  },
+  "channels": {
+    "order-confirmed": { "medium": "email", "locales": ["en"] }
+  },
+  "ai": {
+    "models": { "smart": { "provider": "anthropic", "tier": "opus" } },
+    "prompts": {
+      "triage": { "version": 1, "evals": "./evals/t.jsonl", "budget": { "maxCostPerCall": 0.01 } }
+    },
+    "agents": {
+      "support": { "tools": ["orders.create"], "maxSteps": 3 }
+    }
+  },
+  "plugins": {
+    "audit": {
+      "origin": "local",
+      "version": "1.0.0",
+      "declares": ["consolePanel:audit"],
+      "intercepts": []
+    }
+  },
+  "drivers": {
+    "prod": ["postgres", "redis"]
+  },
+  "tenancy": { "isolation": "schema" },
+  "i18n": { "locales": ["en", "ar"], "default": "en" },
+  "topology": "monolith"
+}

package/src/manifest/fixtures/skyport.excerpt.json

@@ -0,0 +1,51 @@
+{
+  "oke": "1.0",
+  "app": "skyport",
+  "flows": {
+    "bookings.create": {
+      "trigger": { "http": { "method": "POST", "path": "/bookings" } },
+      "gates": ["member", "booking:create", "rate:sliding-window-counter:300/1m"],
+      "in": "…",
+      "out": "…",
+      "errors": ["FlightFull"],
+      "effects": {
+        "reads": ["sql:bookings"],
+        "writes": ["sql:bookings"],
+        "emits": ["order-placed", "seat-feed"],
+        "secrets": []
+      },
+      "slo": { "availability": "99.9%", "latency": { "p99": "200ms" } },
+      "source": "src/flows/bookings/index.ts:18"
+    },
+    "bookings.mine": { "live": true, "cacheKeys": "computed:sql:bookings/userId" },
+    "payments.chargeBooking": {
+      "durable": true,
+      "steps": ["create-intent", "confirm"],
+      "effects": { "secrets": ["STRIPE_KEY"] }
+    },
+    "support.createTicket": {
+      "effects": { "writes": ["sql:tickets"], "asks": ["ticket-triage@3"] },
+      "nondeterministic": true,
+      "cost": { "estimatePerCall": 0.011, "budget": 0.02 },
+      "pii": "masked"
+    }
+  },
+  "signals": {
+    "order-placed": { "delivery": "once", "retries": 5, "deadLetter": true },
+    "seat-feed": { "delivery": "live" }
+  },
+  "channels": { "booking-confirmed": { "medium": "email", "locales": ["en", "ar"] } },
+  "ai": {
+    "models": { "smart": { "provider": "anthropic", "tier": "opus" } },
+    "prompts": { "ticket-triage": { "version": 3, "evals": "./evals/triage.jsonl" } },
+    "agents": {
+      "support": {
+        "tools": ["bookings.getBooking", "bookings.refundBooking"],
+        "maxSteps": 6
+      }
+    }
+  },
+  "journeys": { "book-a-flight": { "slo": { "availability": "99.5%" }, "composes": "99.6%" } },
+  "drivers": { "prod": ["postgres", "redis", "s3", "smtp", "sops", "anthropic", "pgvector"] },
+  "tenancy": { "isolation": "row" }
+}

package/src/manifest/fixtures/skyport.manifest.json

@@ -0,0 +1,153 @@
+{
+  "oke": "1.0",
+  "app": "skyport",
+  "flows": {
+    "bookings.create": {
+      "trigger": { "http": { "method": "POST", "path": "/bookings" } },
+      "gates": ["member", "booking:create", "rate:sliding-window-counter:300/1m"],
+      "in": {
+        "type": "object",
+        "required": ["flightId", "seats"],
+        "properties": {
+          "flightId": { "type": "string" },
+          "seats": { "type": "integer", "minimum": 1 }
+        }
+      },
+      "out": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" }
+        }
+      },
+      "errors": ["FlightFull"],
+      "effects": {
+        "reads": ["sql:bookings"],
+        "writes": ["sql:bookings"],
+        "emits": ["order-placed", "seat-feed"],
+        "secrets": []
+      },
+      "slo": { "availability": "99.9%", "latency": { "p99": "200ms" } },
+      "source": "src/flows/bookings/index.ts:18",
+      "plane": "user"
+    },
+    "bookings.mine": {
+      "trigger": { "http": { "method": "GET", "path": "/bookings" } },
+      "gates": ["member"],
+      "live": true,
+      "cacheKeys": "computed:sql:bookings/userId",
+      "effects": {
+        "reads": ["sql:bookings"]
+      },
+      "source": "src/flows/bookings/index.ts:42"
+    },
+    "payments.chargeBooking": {
+      "durable": true,
+      "steps": ["create-intent", "confirm"],
+      "effects": { "secrets": ["STRIPE_KEY"] },
+      "source": "src/flows/payments/index.ts:12"
+    },
+    "support.createTicket": {
+      "trigger": { "http": { "method": "POST", "path": "/tickets" } },
+      "gates": ["member"],
+      "effects": {
+        "writes": ["sql:tickets"],
+        "asks": ["ticket-triage@3"]
+      },
+      "nondeterministic": true,
+      "cost": { "estimatePerCall": 0.011, "budget": 0.02 },
+      "pii": "masked",
+      "source": "src/flows/support/index.ts:8"
+    }
+  },
+  "signals": {
+    "order-placed": { "delivery": "once", "retries": 5, "deadLetter": true },
+    "seat-feed": { "delivery": "live" }
+  },
+  "stores": {
+    "db": {
+      "facet": "sql",
+      "tables": {
+        "bookings": {
+          "classifications": {
+            "passengerEmail": { "pii": true, "retain": "7y" }
+          }
+        },
+        "tickets": {
+          "classifications": {
+            "body": { "pii": true }
+          }
+        }
+      }
+    }
+  },
+  "clocks": {
+    "expire-holds": { "every": "10m", "overridable": true }
+  },
+  "gates": {
+    "member": { "kind": "policy", "roles": ["member"] },
+    "booking:create": { "kind": "policy", "scopes": ["booking:create"] },
+    "fair": {
+      "kind": "rate",
+      "strategy": "sliding-window-counter",
+      "max": 300,
+      "per": "1m",
+      "keyBy": "user"
+    }
+  },
+  "vault": {
+    "STRIPE_KEY": {
+      "description": "Payments gateway key",
+      "rotate": "90d",
+      "schema": { "type": "string" }
+    }
+  },
+  "channels": {
+    "booking-confirmed": { "medium": "email", "locales": ["en", "ar"] }
+  },
+  "ai": {
+    "models": { "smart": { "provider": "anthropic", "tier": "opus" } },
+    "prompts": {
+      "ticket-triage": {
+        "version": 3,
+        "evals": "./evals/triage.jsonl",
+        "budget": { "maxCostPerCall": 0.02 }
+      }
+    },
+    "agents": {
+      "support": {
+        "tools": ["bookings.getBooking", "bookings.refundBooking"],
+        "maxSteps": 6
+      }
+    }
+  },
+  "plugins": {
+    "audit": {
+      "origin": "local",
+      "version": "1.0.0",
+      "declares": ["store.sql:audit", "consolePanel:audit"],
+      "intercepts": ["afterHandle"]
+    }
+  },
+  "journeys": {
+    "book-a-flight": {
+      "slo": { "availability": "99.5%" },
+      "composes": "99.6%",
+      "flows": ["bookings.create", "payments.chargeBooking"]
+    }
+  },
+  "drivers": {
+    "prod": ["postgres", "redis", "s3", "smtp", "sops", "anthropic", "pgvector"]
+  },
+  "tenancy": { "isolation": "row" },
+  "i18n": {
+    "locales": ["en", "ar"],
+    "default": "ar",
+    "dir": { "ar": "rtl" }
+  },
+  "topology": "monolith",
+  "images": {
+    "store.sql": "pgvector/pgvector:pg17",
+    "store.kv": "valkey/valkey:8-alpine"
+  }
+}

package/src/manifest/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Manifest — the 100-year artifact.
+ *
+ * Public contract: `spec/manifest.v1.schema.json`
+ */
+
+export type * from "./types.ts";
+export {
+  diffManifest,
+  highestSeverity,
+} from "./diff.ts";
+export {
+  flowNameFromPath,
+  isDeclaredBreak,
+  undeclaredContractBreaks,
+} from "./undeclared.ts";
+export {
+  assertLosslessRoundTrip,
+  loadManifestSchema,
+  ManifestValidationError,
+  manifestSchemaUrl,
+  parseManifest,
+  serializeManifest,
+  validateManifest,
+  type ManifestValidationIssue,
+  type ManifestValidationResult,
+} from "./validate.ts";

package/src/manifest/types.ts

@@ -0,0 +1,358 @@
+/**
+ * TypeScript surface matching `spec/manifest.v1.schema.json`.
+ *
+ * Kept hand-aligned with the schema (the public, runtime-neutral contract).
+ * Within major version `1.x`, only additive schema changes are allowed.
+ */
+
+/** Manifest schema version — independent of the okengine runtime package. */
+export type ManifestOkeVersion = "1.0";
+
+/** Store facet identifiers. */
+export type StoreFacet = "sql" | "kv" | "files" | "index";
+
+/** Signal delivery physics — mandatory, no default. */
+export type SignalDelivery = "once" | "broadcast" | "live";
+
+/** Flow plane — user (application) vs operator (Console). */
+export type FlowPlane = "user" | "operator";
+
+/** Deployable topology axis. */
+export type Topology = "monolith" | "services";
+
+/** Tenancy isolation strength. */
+export type TenancyIsolation = "row" | "schema" | "database";
+
+/** Plugin supply-chain origin. */
+export type PluginOrigin = "core" | "local" | "community";
+
+/** Rate-limit strategies. */
+export type RateStrategy =
+  | "sliding-window-counter"
+  | "fixed-window"
+  | "sliding-log"
+  | "token-bucket"
+  | "leaky-bucket";
+
+/** Channel medium. */
+export type ChannelMedium = "email" | "sms" | "whatsapp" | "push" | "any";
+
+/** Resource ref: `sql:table`, `kv:namespace`, `files:bucket`, `index:name`. */
+export type ResourceRef = `${StoreFacet}:${string}`;
+
+/** Signal name reference. */
+export type SignalRef = string;
+
+/** Channel template name reference. */
+export type TemplateRef = string;
+
+/** Prompt name, optionally `name@version`. */
+export type PromptRef = string;
+
+/** Vault secret name reference. */
+export type SecretRef = string;
+
+/** Flow id reference. */
+export type FlowRef = string;
+
+/**
+ * Embedded JSON Schema document, or an opaque string ref from extraction.
+ */
+export type JsonSchema = string | Record<string, unknown>;
+
+/**
+ * Load-bearing effect surface inferred from `fx` usage.
+ *
+ * `secrets` is a capability (not an irreversible effect).
+ * `calls` portals to the callee's transitive effects.
+ * `sends` / `asks` are irreversible (asks also nondeterministic + cost).
+ */
+export interface Effects {
+  /** Store reads. */
+  reads?: ResourceRef[];
+  /** Store writes. */
+  writes?: ResourceRef[];
+  /** Emitted signals. */
+  emits?: SignalRef[];
+  /** Channel template sends (irreversible). */
+  sends?: TemplateRef[];
+  /** AI prompt asks (irreversible, nondeterministic, cost). */
+  asks?: PromptRef[];
+  /** Vault secret capabilities. */
+  secrets?: SecretRef[];
+  /** Nested flow calls (transitive effects). */
+  calls?: FlowRef[];
+}
+
+/** HTTP trigger surface. */
+export interface HttpTrigger {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+  path: string;
+}
+
+/** Change-data-capture trigger. */
+export interface CdcTrigger {
+  table: string;
+  column?: string;
+  store?: string;
+}
+
+/**
+ * Discriminated trigger. Omitting trigger means call-only (internal) flow.
+ */
+export interface Trigger {
+  http?: HttpTrigger;
+  signal?: string;
+  cron?: string;
+  every?: string;
+  cdc?: CdcTrigger;
+}
+
+/** Declared service-level objective. */
+export interface Slo {
+  availability?: string;
+  latency?: Record<string, string>;
+}
+
+/** Deprecation marker. */
+export type Deprecated =
+  | boolean
+  | string
+  | {
+      since?: string;
+      replaceWith?: string;
+      message?: string;
+    };
+
+/** Per-flow AI/cost estimate. */
+export interface FlowCost {
+  estimatePerCall?: number;
+  budget?: number;
+}
+
+/** Typed error map or list of error names. */
+export type FlowErrors = string[] | Record<string, JsonSchema>;
+
+/** One Flow in the manifest. */
+export interface Flow {
+  trigger?: Trigger;
+  gates?: string[];
+  in?: JsonSchema;
+  out?: JsonSchema;
+  errors?: FlowErrors;
+  effects?: Effects;
+  source?: string;
+  plane?: FlowPlane;
+  durable?: boolean;
+  live?: boolean;
+  cache?: boolean | string;
+  cacheKeys?: string;
+  slo?: Slo;
+  deprecated?: Deprecated;
+  steps?: string[];
+  nondeterministic?: boolean;
+  cost?: FlowCost;
+  pii?: "masked" | "allow" | "denied";
+  /**
+   * Explicit acknowledgement that PII may reach a third-party model.
+   * Alias of `pii: "allow"` for AI egress governance.
+   */
+  allowPii?: boolean;
+  /** Author acknowledges an intentional contract break. */
+  breaking?: boolean;
+}
+
+/** One Signal declaration. */
+export interface Signal {
+  delivery: SignalDelivery;
+  retries?: number;
+  deadLetter?: boolean;
+  schema?: JsonSchema;
+  optional?: boolean;
+}
+
+/** Column / field classification for privacy and retention. */
+export interface ColumnClassification {
+  pii?: boolean;
+  sensitive?: boolean;
+  retain?: string;
+}
+
+/** Field classification value forms. */
+export type ClassificationValue =
+  | string
+  | string[]
+  | ColumnClassification;
+
+/** SQL table metadata. */
+export interface Table {
+  columns?: Record<string, ColumnClassification>;
+  classifications?: Record<string, ClassificationValue>;
+}
+
+/** One Store declaration. */
+export interface Store {
+  facet: StoreFacet;
+  tables?: Record<string, Table>;
+  namespaces?: string[];
+  buckets?: string[];
+  indexes?: string[];
+  classifications?: Record<string, ClassificationValue>;
+}
+
+/** Named clock / schedule. */
+export interface Clock {
+  cron?: string;
+  every?: string;
+  timezone?: string;
+  overridable?: boolean;
+}
+
+/** Named gate — policy or rate strategy. */
+export interface Gate {
+  kind?: "policy" | "rate";
+  policy?: string;
+  strategy?: RateStrategy;
+  max?: number;
+  per?: string;
+  keyBy?: string;
+  scopes?: string[];
+  roles?: string[];
+}
+
+/** Vault secret / config contract (never a secret value). */
+export interface SecretContract {
+  description?: string;
+  rotate?: string;
+  schema?: JsonSchema;
+  /**
+   * When `false`, the value is non-sensitive config — Console may show it
+   * in the clear. Defaults to `true` (secret).
+   */
+  sensitive?: boolean;
+}
+
+/** Channel template. */
+export interface Channel {
+  medium?: ChannelMedium;
+  locales?: string[];
+  schema?: JsonSchema;
+  from?: string;
+}
+
+/** AI model binding. */
+export interface AiModel {
+  provider?: string;
+  tier?: string;
+  model?: string;
+}
+
+/** Prompt / agent budget. */
+export interface AiBudget {
+  maxCostPerCall?: number;
+  maxCostPerRun?: number;
+}
+
+/** Versioned prompt artifact. */
+export interface AiPrompt {
+  version?: number;
+  evals?: string;
+  budget?: AiBudget;
+  model?: string;
+  in?: JsonSchema;
+  out?: JsonSchema;
+}
+
+/** Bounded agent whose tools are flows. */
+export interface AiAgent {
+  tools?: FlowRef[];
+  maxSteps?: number;
+  model?: string;
+  budget?: AiBudget;
+}
+
+/** AI element catalogue. */
+export interface Ai {
+  models?: Record<string, AiModel>;
+  prompts?: Record<string, AiPrompt>;
+  agents?: Record<string, AiAgent>;
+}
+
+/** Plugin capability declaration. */
+export interface Plugin {
+  origin?: PluginOrigin;
+  version?: string;
+  declares?: string[];
+  intercepts?: string[];
+}
+
+/** Tenancy configuration (resolver is code; isolation is data). */
+export interface Tenancy {
+  isolation?: TenancyIsolation;
+}
+
+/** i18n configuration. */
+export interface I18n {
+  locales?: string[];
+  default?: string;
+  dir?: Record<string, "ltr" | "rtl">;
+}
+
+/** Cross-flow journey with composed SLO. */
+export interface Journey {
+  slo?: Slo;
+  composes?: string;
+  flows?: FlowRef[];
+}
+
+/**
+ * The Manifest — the 100-year artifact.
+ *
+ * Everything else (client, docs, Console, capabilities, infra) derives from this.
+ */
+export interface Manifest {
+  oke: ManifestOkeVersion;
+  app: string;
+  flows?: Record<string, Flow>;
+  signals?: Record<string, Signal>;
+  stores?: Record<string, Store>;
+  clocks?: Record<string, Clock>;
+  gates?: Record<string, Gate>;
+  vault?: Record<string, SecretContract>;
+  channels?: Record<string, Channel>;
+  ai?: Ai;
+  plugins?: Record<string, Plugin>;
+  drivers?: Record<string, string[]>;
+  tenancy?: Tenancy;
+  i18n?: I18n;
+  journeys?: Record<string, Journey>;
+  topology?: Topology;
+  images?: Record<string, string>;
+}
+
+/** Four blast-radius categories from Console §9.12. */
+export type DiffCategory =
+  | "contract-breaking"
+  | "permission-widening"
+  | "effect-widening"
+  | "no-impact";
+
+/** How a path changed. */
+export type DiffKind = "added" | "removed" | "changed";
+
+/** One classified behavioural change between two manifests. */
+export interface ManifestChange {
+  path: string;
+  category: DiffCategory;
+  kind: DiffKind;
+  before?: unknown;
+  after?: unknown;
+  summary: string;
+}
+
+/** Result of {@link diffManifest}. */
+export interface ManifestDiffResult {
+  changes: ManifestChange[];
+  /** Highest blast-radius category present, or `null` when empty. */
+  severity: DiffCategory | null;
+}