okengine 0.2.6 → 0.2.8

package/src/elements/clock/reconcile.ts

@@ -68,12 +68,7 @@ export interface CronStore {
    * @param now - Current epoch-ms
    * @param leaseMs - Lease TTL
    */
-  acquireLease(
-    name: string,
-    instanceId: string,
-    now: number,
-    leaseMs: number,
-  ): Promise<boolean>;
+  acquireLease(name: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
 }
 
 /** Result of one reconciliation pass. */
@@ -107,13 +102,9 @@ export async function reconcileClocks(
   for (const decl of declared) {
     const prev = await store.get(decl.name);
     const overrideCron =
-      decl.overridable && prev?.overrideCron !== undefined
-        ? prev.overrideCron
-        : undefined;
+      decl.overridable && prev?.overrideCron !== undefined ? prev.overrideCron : undefined;
     const overrideEvery =
-      decl.overridable && prev?.overrideEvery !== undefined
-        ? prev.overrideEvery
-        : undefined;
+      decl.overridable && prev?.overrideEvery !== undefined ? prev.overrideEvery : undefined;
 
     const row: CronRow = {
       name: decl.name,
@@ -179,9 +170,7 @@ export function effectiveSchedule(row: CronRow): {
  *
  * @param seed - Optional initial rows
  */
-export function createMemoryCronStore(
-  seed?: readonly CronRow[],
-): CronStore {
+export function createMemoryCronStore(seed?: readonly CronRow[]): CronStore {
   const rows = new Map<string, CronRow>();
   for (const r of seed ?? []) {
     rows.set(r.name, structuredClone(r));

package/src/elements/clock/runtime.ts

@@ -99,12 +99,9 @@ export interface ClockRuntime {
  *
  * @param options - Instance id, store, clock
  */
-export function createClockRuntime(
-  options: CreateClockRuntimeOptions = {},
-): ClockRuntime {
+export function createClockRuntime(options: CreateClockRuntimeOptions = {}): ClockRuntime {
   const timeTravel = options.timeTravel;
-  const now = (): number =>
-    timeTravel ? timeTravel.now() : (options.now ?? (() => Date.now()))();
+  const now = (): number => (timeTravel ? timeTravel.now() : (options.now ?? (() => Date.now()))());
   const store = options.store ?? createMemoryCronStore();
   const instanceId = options.instanceId ?? crypto.randomUUID();
   const leaseMs = options.leaseMs ?? 30_000;

package/src/elements/clock/schedule.ts

@@ -15,11 +15,7 @@ import { effectiveSchedule, type CronRow } from "./reconcile.ts";
  * @param from - Inclusive start epoch-ms
  * @param until - Exclusive end epoch-ms
  */
-export function nextOccurrences(
-  row: CronRow,
-  from: number,
-  until: number,
-): readonly number[] {
+export function nextOccurrences(row: CronRow, from: number, until: number): readonly number[] {
   if (row.status !== "active" && row.status !== "paused") return [];
   if (until <= from) return [];
 
@@ -75,11 +71,7 @@ export function previousOccurrence(row: CronRow, at: number): number | null {
  * @param from - Exclusive lower bound (usually lastRunAt)
  * @param until - Inclusive upper bound (usually now)
  */
-export function countMissedOccurrences(
-  row: CronRow,
-  from: number,
-  until: number,
-): number {
+export function countMissedOccurrences(row: CronRow, from: number, until: number): number {
   if (until <= from) return 0;
   const sched = effectiveSchedule(row);
   if (sched.every) {
@@ -129,11 +121,7 @@ function nextCronOccurrences(
 ): readonly number[] {
   const parsed = parseSimpleDaily(cron);
   if (!parsed) {
-    if (
-      row.nextRunAt !== undefined &&
-      row.nextRunAt >= from &&
-      row.nextRunAt < until
-    ) {
+    if (row.nextRunAt !== undefined && row.nextRunAt >= from && row.nextRunAt < until) {
       return [row.nextRunAt];
     }
     return [];
@@ -202,11 +190,7 @@ function civilFiresOnDay(
   for (let offsetMin = -14 * 60; offsetMin <= 14 * 60; offsetMin += 15) {
     const utc = base + parsed.hour * 3_600_000 + parsed.minute * 60_000 - offsetMin * 60_000;
     const local = zonedParts(utc, timezone);
-    if (
-      local.date === dateStr &&
-      local.hour === parsed.hour &&
-      local.minute === parsed.minute
-    ) {
+    if (local.date === dateStr && local.hour === parsed.hour && local.minute === parsed.minute) {
       if (parsed.dow !== undefined) {
         const localDow = zonedDow(utc, timezone);
         if (localDow !== parsed.dow) continue;

package/src/elements/clock.test.ts

@@ -13,10 +13,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { flow } from "../kernel/flow.ts";
-import {
-  createFileJournalStore,
-  createMemoryJournalStore,
-} from "../kernel/journal.ts";
+import { createFileJournalStore, createMemoryJournalStore } from "../kernel/journal.ts";
 import {
   clock,
   createClockRuntime,
@@ -340,9 +337,7 @@ describe("DST ambiguity", () => {
     expect(detectDstAmbiguity("0 2 * * *", "UTC")).toBeNull();
 
     // Noon is outside the transition window for US zones.
-    expect(
-      detectDstAmbiguity("0 12 * * *", "America/New_York", Date.UTC(2026, 0, 1)),
-    ).toBeNull();
+    expect(detectDstAmbiguity("0 12 * * *", "America/New_York", Date.UTC(2026, 0, 1))).toBeNull();
   });
 
   test("reconcile attaches dstAmbiguity on the store row", async () => {

package/src/elements/clock.ts

@@ -15,10 +15,7 @@ export type { ClockDecl, ClockOptions } from "./clock/declare.ts";
 
 export { parseDurationMs } from "./clock/duration.ts";
 
-export {
-  detectDstAmbiguity,
-  type DstAmbiguity,
-} from "./clock/dst.ts";
+export { detectDstAmbiguity, type DstAmbiguity } from "./clock/dst.ts";
 
 export {
   tryAcquireLease,
@@ -38,10 +35,7 @@ export {
   type ReconcileResult,
 } from "./clock/reconcile.ts";
 
-export {
-  createTimeTravel,
-  type TimeTravel,
-} from "./clock/time-travel.ts";
+export { createTimeTravel, type TimeTravel } from "./clock/time-travel.ts";
 
 export {
   createClockRuntime,
@@ -51,23 +45,11 @@ export {
   type CronHandler,
 } from "./clock/runtime.ts";
 
-export {
-  runDurable,
-  type DurableResult,
-  type RunDurableOptions,
-} from "./clock/durable.ts";
+export { runDurable, type DurableResult, type RunDurableOptions } from "./clock/durable.ts";
 
-export {
-  cronHealth,
-  type CatchUpPolicy,
-  type CronHealth,
-} from "./clock/health.ts";
+export { cronHealth, type CatchUpPolicy, type CronHealth } from "./clock/health.ts";
 
-export {
-  nextOccurrences,
-  previousOccurrence,
-  countMissedOccurrences,
-} from "./clock/schedule.ts";
+export { nextOccurrences, previousOccurrence, countMissedOccurrences } from "./clock/schedule.ts";
 
 export {
   pauseCron,

package/src/elements/gate/permissions.ts

@@ -81,10 +81,7 @@ function effectToAction(ref: string, op: "read" | "write"): string {
   return `store.${facet}:${op}`;
 }
 
-function collectEffects(
-  manifest: Manifest,
-  kind: "reads" | "writes",
-): string[] {
+function collectEffects(manifest: Manifest, kind: "reads" | "writes"): string[] {
   const out: string[] = [];
   for (const flow of Object.values(manifest.flows ?? {})) {
     const list = flow.effects?.[kind];

package/src/elements/gate/runtime.ts

@@ -8,11 +8,7 @@ import { takeRate } from "./strategies.ts";
 
 /** KV surface required for rate gates. */
 export interface GateKv {
-  eval<T = unknown>(
-    script: string,
-    keys: readonly string[],
-    args?: readonly string[],
-  ): Promise<T>;
+  eval<T = unknown>(script: string, keys: readonly string[], args?: readonly string[]): Promise<T>;
 }
 
 /** Options for {@link createGateRuntime}. */
@@ -45,20 +41,14 @@ export interface GateRuntime {
    * @param names - Gate names / rate ids
    * @param ctx - Policy context
    */
-  check(
-    names: readonly string[],
-    ctx: GatePolicyContext,
-  ): Promise<GateEvaluation[]>;
+  check(names: readonly string[], ctx: GatePolicyContext): Promise<GateEvaluation[]>;
   /**
    * Whether every gate in the chain allows.
    *
    * @param names - Gate names
    * @param ctx - Policy context
    */
-  allow(
-    names: readonly string[],
-    ctx: GatePolicyContext,
-  ): Promise<boolean>;
+  allow(names: readonly string[], ctx: GatePolicyContext): Promise<boolean>;
 }
 
 /**
@@ -66,19 +56,14 @@ export interface GateRuntime {
  *
  * @param options - Declarations + kv
  */
-export function createGateRuntime(
-  options: CreateGateRuntimeOptions = {},
-): GateRuntime {
+export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateRuntime {
   const map = new Map<string, GateDecl>();
   for (const g of options.gates ?? []) {
     map.set(g.name, g);
   }
   const now = options.now ?? (() => Date.now());
 
-  async function evaluateOne(
-    name: string,
-    ctx: GatePolicyContext,
-  ): Promise<GateEvaluation> {
+  async function evaluateOne(name: string, ctx: GatePolicyContext): Promise<GateEvaluation> {
     const decl = map.get(name);
     if (!decl) {
       return {
@@ -100,10 +85,7 @@ export function createGateRuntime(
     return evaluateRate(decl, ctx);
   }
 
-  async function evaluateRate(
-    decl: RateGateDecl,
-    ctx: GatePolicyContext,
-  ): Promise<GateEvaluation> {
+  async function evaluateRate(decl: RateGateDecl, ctx: GatePolicyContext): Promise<GateEvaluation> {
     if (!options.kv) {
       return {
         name: decl.name,
@@ -157,10 +139,7 @@ export function createGateRuntime(
   };
 }
 
-function resolveSubject(
-  keyBy: string | undefined,
-  ctx: GatePolicyContext,
-): string {
+function resolveSubject(keyBy: string | undefined, ctx: GatePolicyContext): string {
   switch (keyBy) {
     case "user":
       return ctx.auth.userId ?? ctx.meta?.userId ?? "anon";

package/src/elements/gate.ts

@@ -35,8 +35,4 @@ export {
   type TakeRateOptions,
 } from "./gate/strategies.ts";
 
-export {
-  deriveModuleActions,
-  flowIdToAction,
-  formatGatesList,
-} from "./gate/permissions.ts";
+export { deriveModuleActions, flowIdToAction, formatGatesList } from "./gate/permissions.ts";

package/src/elements/index.ts

@@ -12,6 +12,9 @@ export {
   id,
   now,
   defineTable,
+  field,
+  schemaTable,
+  schemaRelations,
   createStoreRuntime,
   createStoreCache,
   computedCacheKey,
@@ -32,6 +35,9 @@ export type {
   SqlStoreHandle,
   TableHandle,
   ColumnDef,
+  SchemaTableDecl,
+  SchemaColumnDecl,
+  SchemaRelationsDecl,
 } from "./store.ts";
 
 export { signal, createSignalRuntime } from "./signal.ts";
@@ -52,13 +58,7 @@ export {
   detectDstAmbiguity,
   parseDurationMs,
 } from "./clock.ts";
-export type {
-  ClockDecl,
-  ClockOptions,
-  ClockRuntime,
-  TimeTravel,
-  DurableResult,
-} from "./clock.ts";
+export type { ClockDecl, ClockOptions, ClockRuntime, TimeTravel, DurableResult } from "./clock.ts";
 
 export {
   gate,
@@ -86,6 +86,8 @@ export {
   fingerprintSecretSync,
   createSecretRedactor,
   resolveLayerSource,
+  COMPOSE_ENV_REL,
+  resolveComposeEnvPath,
 } from "./vault.ts";
 export type {
   VaultSecretDecl,

package/src/elements/signal/declare.ts

@@ -53,18 +53,13 @@ export interface SignalDecl<T = unknown> {
  * @param name - Signal name
  * @param options - Delivery physics and retry / DLQ policy
  */
-export function signal<T = unknown>(
-  name: string,
-  options: SignalOptions,
-): SignalDecl<T> {
+export function signal<T = unknown>(name: string, options: SignalOptions): SignalDecl<T> {
   if (
     options.delivery !== "once" &&
     options.delivery !== "broadcast" &&
     options.delivery !== "live"
   ) {
-    throw new TypeError(
-      `signal("${name}"): delivery is mandatory (once | broadcast | live)`,
-    );
+    throw new TypeError(`signal("${name}"): delivery is mandatory (once | broadcast | live)`);
   }
   return {
     name,

package/src/elements/signal/reconcile.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { signal } from "./declare.ts";
-import {
-  createMemorySignalConfigStore,
-  reconcileSignals,
-} from "./reconcile.ts";
+import { createMemorySignalConfigStore, reconcileSignals } from "./reconcile.ts";
 
 describe("reconcileSignals", () => {
   test("marks a removed signal orphaned without deleting it", async () => {

package/src/elements/signal/runtime.ts

@@ -52,9 +52,7 @@ export interface SignalRuntime {
  *
  * @param options - Driver and bindings
  */
-export function createSignalRuntime(
-  options: CreateSignalRuntimeOptions,
-): SignalRuntime {
+export function createSignalRuntime(options: CreateSignalRuntimeOptions): SignalRuntime {
   const declarations = new Map<string, SignalDecl>();
   let bus: SignalBus | null = null;
 

package/src/elements/signal.test.ts

@@ -205,9 +205,7 @@ for (const { label, driver, setup } of drivers) {
         attempt: 1,
       });
       expect(dlq[0]!.failures[0]!.message).toContain("boom-");
-      expect(dlq[0]!.failures.map((f) => f.attempt)).toEqual(
-        dlq[0]!.failures.map((_, i) => i + 1),
-      );
+      expect(dlq[0]!.failures.map((f) => f.attempt)).toEqual(dlq[0]!.failures.map((_, i) => i + 1));
     });
   });
 }
@@ -303,12 +301,7 @@ describe("chaos — kill process mid-transaction", () => {
     const durablePath = join(dir, "bus.json");
     try {
       const child = Bun.spawn({
-        cmd: [
-          "bun",
-          join(import.meta.dir, "signal/chaos-child.ts"),
-          durablePath,
-          "mid-txn",
-        ],
+        cmd: ["bun", join(import.meta.dir, "signal/chaos-child.ts"), durablePath, "mid-txn"],
         stdout: "pipe",
         stderr: "pipe",
       });
@@ -406,12 +399,7 @@ describe("chaos — kill process mid-transaction", () => {
     const durablePath = join(dir, "bus.json");
     try {
       const child = Bun.spawn({
-        cmd: [
-          "bun",
-          join(import.meta.dir, "signal/chaos-child.ts"),
-          durablePath,
-          "commit",
-        ],
+        cmd: ["bun", join(import.meta.dir, "signal/chaos-child.ts"), durablePath, "commit"],
         stdout: "pipe",
         stderr: "pipe",
       });

package/src/elements/signal.ts

@@ -10,15 +10,9 @@ export { signal } from "./signal/declare.ts";
 export type { SignalDecl, SignalOptions } from "./signal/declare.ts";
 
 export { createSignalRuntime } from "./signal/runtime.ts";
-export type {
-  CreateSignalRuntimeOptions,
-  SignalRuntime,
-} from "./signal/runtime.ts";
+export type { CreateSignalRuntimeOptions, SignalRuntime } from "./signal/runtime.ts";
 
-export {
-  reconcileSignals,
-  createMemorySignalConfigStore,
-} from "./signal/reconcile.ts";
+export { reconcileSignals, createMemorySignalConfigStore } from "./signal/reconcile.ts";
 export type {
   SignalConfigRow,
   SignalConfigStatus,

package/src/elements/store/cache.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Tier-1 cache exactness lock — invalidation keys off declared resources.
+ *
+ * A write invalidates a cached read only when the written resource appears
+ * in that read's `effects.reads`. A read that recorded only its root table
+ * is NOT invalidated by a write to a related table — which is exactly why
+ * relational `with:` is not exposed through `fx` (silent staleness hazard).
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Effects } from "../../manifest/types.ts";
+import {
+  computedCacheKey,
+  createStoreCache,
+  isInvalidatedByWrite,
+  tier1KeysForReads,
+} from "./cache.ts";
+
+describe("tier-1 cache — exact per-resource invalidation (path b)", () => {
+  test("a write invalidates only reads that declared the written resource", () => {
+    const cache = createStoreCache();
+
+    // Root-only read — what a half-shipped `with:` expansion would record.
+    const rootOnly: Effects = { reads: ["sql:links"] };
+    const keys = tier1KeysForReads(rootOnly);
+    expect(keys).toEqual([computedCacheKey("sql:links")]);
+
+    cache.set({
+      tier: 1,
+      key: keys[0]!,
+      value: [{ id: "l1" }],
+      resources: ["sql:links"],
+      expiresAt: null,
+    });
+
+    // A write to the related table does not invalidate the root-only read.
+    expect(isInvalidatedByWrite(keys[0]!, { writes: ["sql:daily"] })).toBe(false);
+    expect(cache.invalidateFromEffects({ writes: ["sql:daily"] }).keys).toEqual([]);
+    expect(cache.get(keys[0]!)).toBeDefined();
+
+    // Exact match on the declared resource still invalidates.
+    expect(isInvalidatedByWrite(keys[0]!, { writes: ["sql:links"] })).toBe(true);
+    expect(cache.invalidateFromEffects({ writes: ["sql:links"] }).keys).toEqual(keys);
+    expect(cache.get(keys[0]!)).toBeUndefined();
+  });
+});

package/src/elements/store/cache.ts

@@ -38,10 +38,7 @@ export interface InvalidationEvent {
  * @param resource - Store resource ref
  * @param dims - Optional dimension suffixes (e.g. `userId`)
  */
-export function computedCacheKey(
-  resource: ResourceRef,
-  dims?: readonly string[],
-): string {
+export function computedCacheKey(resource: ResourceRef, dims?: readonly string[]): string {
   if (!dims || dims.length === 0) return `computed:${resource}`;
   return `computed:${resource}/${dims.join("/")}`;
 }
@@ -57,9 +54,7 @@ export function tier1KeysForReads(
   dimsByResource?: Readonly<Record<string, readonly string[]>>,
 ): string[] {
   const reads = effects.reads ?? [];
-  return reads.map((resource) =>
-    computedCacheKey(resource, dimsByResource?.[resource]),
-  );
+  return reads.map((resource) => computedCacheKey(resource, dimsByResource?.[resource]));
 }
 
 /**
@@ -79,10 +74,7 @@ export function resourcesTouchedByWrites(effects: Effects): ResourceRef[] {
  * @param key - Tier-1 cache key (`computed:…`)
  * @param writeEffects - Effects of the writing flow
  */
-export function isInvalidatedByWrite(
-  key: string,
-  writeEffects: Effects,
-): boolean {
+export function isInvalidatedByWrite(key: string, writeEffects: Effects): boolean {
   if (!key.startsWith("computed:")) return false;
   const body = key.slice("computed:".length);
   const resource = body.split("/")[0] ?? "";

package/src/elements/store/classify.ts

@@ -4,11 +4,7 @@
  */
 
 import type { ColumnClassification } from "../../manifest/types.ts";
-import {
-  classificationKey,
-  type ClassificationMap,
-  type SqlRow,
-} from "../../drivers/types.ts";
+import { classificationKey, type ClassificationMap, type SqlRow } from "../../drivers/types.ts";
 
 /** Default mask token for PII columns when reveal is denied. */
 export const PII_MASK = "[redacted]";
@@ -21,9 +17,7 @@ export const PII_MASK = "[redacted]";
  *
  * @param classification - Tags to attach
  */
-export function classify(
-  classification: ColumnClassification,
-): ColumnClassification {
+export function classify(classification: ColumnClassification): ColumnClassification {
   return { ...classification };
 }
 
@@ -33,9 +27,7 @@ export function classify(
  * @param tables - Per-table column classifications
  */
 export function buildClassificationMap(
-  tables: Readonly<
-    Record<string, Readonly<Record<string, ColumnClassification>>>
-  >,
+  tables: Readonly<Record<string, Readonly<Record<string, ColumnClassification>>>>,
 ): ClassificationMap {
   const map = new Map<string, ColumnClassification>();
   for (const [table, cols] of Object.entries(tables)) {
@@ -90,10 +82,7 @@ export interface MaskRowsOptions {
  * @param rows - Raw driver rows
  * @param options - Classification + reveal policy
  */
-export function maskRows(
-  rows: readonly SqlRow[],
-  options: MaskRowsOptions,
-): SqlRow[] {
+export function maskRows(rows: readonly SqlRow[], options: MaskRowsOptions): SqlRow[] {
   if (options.revealPii || options.classifications.size === 0) {
     return rows.map((r) => ({ ...r }));
   }
@@ -101,13 +90,7 @@ export function maskRows(
   return rows.map((row) => {
     const out: SqlRow = {};
     for (const [column, value] of Object.entries(row)) {
-      out[column] = isPiiColumn(
-        options.classifications,
-        options.table,
-        column,
-      )
-        ? mask
-        : value;
+      out[column] = isPiiColumn(options.classifications, options.table, column) ? mask : value;
     }
     return out;
   });

package/src/elements/store/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ColumnClassification, ResourceRef, StoreFacet } from "../../manifest/types.ts";
+import { schema } from "./schema-decl.ts";
 import { resolveTableName, type TableHandle } from "./table.ts";
 
 /** CDC trigger shape (mirrors kernel `CdcTrigger` without importing it). */
@@ -47,9 +48,7 @@ export interface SqlStoreOptions {
    * Explicit classifications: `table → column → tags`.
    * Merged with schema-derived tags; wins on conflict for the same column.
    */
-  readonly classify?: Readonly<
-    Record<string, Readonly<Record<string, ColumnClassification>>>
-  >;
+  readonly classify?: Readonly<Record<string, Readonly<Record<string, ColumnClassification>>>>;
 }
 
 /** SQL store declaration. */
@@ -106,11 +105,7 @@ export interface IndexStoreDecl extends StoreDeclBase {
 }
 
 /** Any store declaration. */
-export type StoreDecl =
-  | SqlStoreDecl
-  | KvStoreDecl
-  | FilesStoreDecl
-  | IndexStoreDecl;
+export type StoreDecl = SqlStoreDecl | KvStoreDecl | FilesStoreDecl | IndexStoreDecl;
 
 /**
  * Declare a SQL store.
@@ -161,10 +156,7 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
  * @param name - Bucket name
  * @param options - Options
  */
-export function files(
-  name: string,
-  options: FilesStoreOptions = {},
-): FilesStoreDecl {
+export function files(name: string, options: FilesStoreOptions = {}): FilesStoreDecl {
   return {
     facet: "files",
     name,
@@ -179,10 +171,7 @@ export function files(
  * @param name - Index name
  * @param options - Dimensions
  */
-export function index(
-  name: string,
-  options: IndexStoreOptions = {},
-): IndexStoreDecl {
+export function index(name: string, options: IndexStoreOptions = {}): IndexStoreDecl {
   return {
     facet: "index",
     name,
@@ -191,10 +180,12 @@ export function index(
   };
 }
 
-/** Public `store` element — four facets. */
+/** Public `store` element — four facets + abstract schema declare. */
 export const store = {
   sql,
   kv,
   files,
   index,
+  /** ORM-agnostic table declarations (`store.schema.table`). */
+  schema,
 } as const;