okengine 0.1.4

package/src/elements/store/cache.ts

@@ -0,0 +1,197 @@
+/**
+ * Three cache tiers.
+ *
+ * - Tier 1 — automatic for live / read flows; invalidation computed from effects
+ * - Tier 2 — a flag on any flow (`cache: "5m"`)
+ * - Tier 3 — manual via `fx.cache.getOrSet`
+ */
+
+import type { Effects, ResourceRef } from "../../manifest/types.ts";
+
+/** Cache tier identifiers. */
+export type CacheTier = 1 | 2 | 3;
+
+/** One cached entry with its provenance. */
+export interface CacheEntry<T = unknown> {
+  readonly tier: CacheTier;
+  readonly key: string;
+  readonly value: T;
+  /** Resources this entry was derived from (tier 1). */
+  readonly resources: readonly ResourceRef[];
+  /** Absolute expiry epoch-ms, or null for no TTL. */
+  readonly expiresAt: number | null;
+}
+
+/** Invalidation event produced by a write. */
+export interface InvalidationEvent {
+  /** Resources written. */
+  readonly resources: readonly ResourceRef[];
+  /** Keys removed. */
+  readonly keys: readonly string[];
+}
+
+/**
+ * Compute the tier-1 cache key for a read effect set.
+ *
+ * Format: `computed:{resource}` or `computed:{resource}/{dim}` when dims given.
+ *
+ * @param resource - Store resource ref
+ * @param dims - Optional dimension suffixes (e.g. `userId`)
+ */
+export function computedCacheKey(
+  resource: ResourceRef,
+  dims?: readonly string[],
+): string {
+  if (!dims || dims.length === 0) return `computed:${resource}`;
+  return `computed:${resource}/${dims.join("/")}`;
+}
+
+/**
+ * Tier-1 keys implied by a read effect set.
+ *
+ * @param effects - Flow effects (must include reads)
+ * @param dimsByResource - Optional per-resource dimension suffixes
+ */
+export function tier1KeysForReads(
+  effects: Effects,
+  dimsByResource?: Readonly<Record<string, readonly string[]>>,
+): string[] {
+  const reads = effects.reads ?? [];
+  return reads.map((resource) =>
+    computedCacheKey(resource, dimsByResource?.[resource]),
+  );
+}
+
+/**
+ * Resources whose tier-1 entries a write must invalidate.
+ *
+ * @param effects - Write flow effects
+ */
+export function resourcesTouchedByWrites(effects: Effects): ResourceRef[] {
+  return [...(effects.writes ?? [])];
+}
+
+/**
+ * Whether a tier-1 key is invalidated by a write effect set.
+ *
+ * Auto-invalidation fires on exactly the writes touching the read's keys.
+ *
+ * @param key - Tier-1 cache key (`computed:…`)
+ * @param writeEffects - Effects of the writing flow
+ */
+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] ?? "";
+  return (writeEffects.writes ?? []).some((w) => w === resource);
+}
+
+/** In-memory multi-tier cache used by the store runtime and tests. */
+export interface StoreCache {
+  /**
+   * Get a value by key.
+   *
+   * @param key - Cache key
+   */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+   * Set a value.
+   *
+   * @param entry - Entry to store
+   */
+  set<T>(entry: CacheEntry<T>): void;
+  /**
+   * Invalidate every tier-1 entry whose resources intersect `resources`.
+   *
+   * @param resources - Written resources
+   */
+  invalidate(resources: readonly ResourceRef[]): InvalidationEvent;
+  /**
+   * Apply write effects: invalidate exactly the keys those writes touch.
+   *
+   * @param writeEffects - Writing flow's effects
+   */
+  invalidateFromEffects(writeEffects: Effects): InvalidationEvent;
+  /** Snapshot of keys currently held. */
+  keys(): string[];
+  /** Clear all tiers. */
+  clear(): void;
+}
+
+/**
+ * Create an in-memory store cache (all three tiers share one map; tier is metadata).
+ *
+ * @param now - Clock for TTL expiry
+ */
+export function createStoreCache(now: () => number = () => Date.now()): StoreCache {
+  const entries = new Map<string, CacheEntry>();
+
+  function alive(entry: CacheEntry): boolean {
+    return entry.expiresAt === null || entry.expiresAt > now();
+  }
+
+  return {
+    get<T = unknown>(key: string): T | undefined {
+      const entry = entries.get(key);
+      if (!entry) return undefined;
+      if (!alive(entry)) {
+        entries.delete(key);
+        return undefined;
+      }
+      return entry.value as T;
+    },
+    set<T>(entry: CacheEntry<T>): void {
+      entries.set(entry.key, entry as CacheEntry);
+    },
+    invalidate(resources: readonly ResourceRef[]): InvalidationEvent {
+      const set = new Set(resources);
+      const keys: string[] = [];
+      for (const [key, entry] of entries) {
+        if (entry.tier !== 1) continue;
+        if (entry.resources.some((r) => set.has(r))) {
+          keys.push(key);
+          entries.delete(key);
+        }
+      }
+      return { resources: [...resources], keys };
+    },
+    invalidateFromEffects(writeEffects: Effects): InvalidationEvent {
+      return this.invalidate(resourcesTouchedByWrites(writeEffects));
+    },
+    keys(): string[] {
+      return [...entries.keys()];
+    },
+    clear(): void {
+      entries.clear();
+    },
+  };
+}
+
+/**
+ * Parse a short TTL string (`"5m"`, `"1h"`, `"30s"`) to milliseconds.
+ *
+ * @param ttl - Duration string
+ */
+export function parseTtlMs(ttl: string): number {
+  const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl.trim());
+  if (!match) return 0;
+  const n = Number(match[1]);
+  const unit = match[2];
+  switch (unit) {
+    case "ms":
+      return n;
+    case "s":
+      return n * 1000;
+    case "m":
+      return n * 60_000;
+    case "h":
+      return n * 3_600_000;
+    case "d":
+      return n * 86_400_000;
+    default:
+      return 0;
+  }
+}

package/src/elements/store/classify.ts

@@ -0,0 +1,125 @@
+/**
+ * PII / sensitivity classification — lives in the schema, enforced at the
+ * driver boundary so it survives raw SQL (`SELECT *` masks classified columns).
+ */
+
+import type { ColumnClassification } from "../../manifest/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]";
+
+/**
+ * Tag a column (or field) with privacy / retention classification.
+ *
+ * Use in schema metadata or `store.sql` classify maps:
+ * `email: classify({ pii: true })`.
+ *
+ * @param classification - Tags to attach
+ */
+export function classify(
+  classification: ColumnClassification,
+): ColumnClassification {
+  return { ...classification };
+}
+
+/**
+ * Build a classification map from a nested table → column → tags structure.
+ *
+ * @param tables - Per-table column classifications
+ */
+export function buildClassificationMap(
+  tables: Readonly<
+    Record<string, Readonly<Record<string, ColumnClassification>>>
+  >,
+): ClassificationMap {
+  const map = new Map<string, ColumnClassification>();
+  for (const [table, cols] of Object.entries(tables)) {
+    for (const [column, tags] of Object.entries(cols)) {
+      map.set(classificationKey(table, column), tags);
+    }
+  }
+  return map;
+}
+
+/**
+ * Whether a column is classified as PII.
+ *
+ * @param map - Classification map
+ * @param table - Table name (may be unknown for opaque queries)
+ * @param column - Column name
+ */
+export function isPiiColumn(
+  map: ClassificationMap,
+  table: string | undefined,
+  column: string,
+): boolean {
+  if (table) {
+    const direct = map.get(classificationKey(table, column));
+    if (direct?.pii) return true;
+  }
+  // Survive raw SQL when only the column name is known: match any table.
+  for (const [key, tags] of map) {
+    if (tags.pii && key.endsWith(`.${column}`)) return true;
+  }
+  return false;
+}
+
+/** Options for {@link maskRows}. */
+export interface MaskRowsOptions {
+  /** Classification map from the schema. */
+  readonly classifications: ClassificationMap;
+  /** Table hint when known (from query builder). */
+  readonly table?: string;
+  /**
+   * When true, PII columns are returned in cleartext (requires `pii:reveal`).
+   * Default false.
+   */
+  readonly revealPii?: boolean;
+  /** Mask token (defaults to {@link PII_MASK}). */
+  readonly mask?: string;
+}
+
+/**
+ * Mask classified columns on result rows at the driver boundary.
+ *
+ * @param rows - Raw driver rows
+ * @param options - Classification + reveal policy
+ */
+export function maskRows(
+  rows: readonly SqlRow[],
+  options: MaskRowsOptions,
+): SqlRow[] {
+  if (options.revealPii || options.classifications.size === 0) {
+    return rows.map((r) => ({ ...r }));
+  }
+  const mask = options.mask ?? PII_MASK;
+  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;
+    }
+    return out;
+  });
+}
+
+/**
+ * Extract a FROM table name from a SQL string when possible.
+ * Best-effort — used so `SELECT *` still finds classifications.
+ *
+ * @param sql - SQL text
+ */
+export function tableFromSql(sql: string): string | undefined {
+  const match = /\bfrom\s+["`]?([a-zA-Z_][a-zA-Z0-9_]*)["`]?/i.exec(sql);
+  return match?.[1];
+}

package/src/elements/store/declare.ts

@@ -0,0 +1,200 @@
+/**
+ * Store facet declarations — `store.sql` · `store.kv` · `store.files` · `store.index`.
+ *
+ * Declarations are data; I/O happens only through drivers via the runtime / `fx`.
+ */
+
+import type { ColumnClassification, ResourceRef, StoreFacet } from "../../manifest/types.ts";
+import { resolveTableName, type TableHandle } from "./table.ts";
+
+/** CDC trigger shape (mirrors kernel `CdcTrigger` without importing it). */
+export interface StoreCdcTrigger {
+  readonly kind: "cdc";
+  readonly table: string;
+  readonly column?: string;
+  readonly store?: string;
+}
+
+/** Handle from {@link SqlStoreDecl.table}. */
+export interface StoreTableCdc {
+  readonly name: string;
+  /**
+   * CDC trigger when `column` (or any column) changes.
+   *
+   * @param column - Optional column name
+   */
+  changed(column?: string): StoreCdcTrigger;
+}
+
+/** Base fields shared by every facet declaration. */
+export interface StoreDeclBase {
+  /** Facet kind. */
+  readonly facet: StoreFacet;
+  /** Logical name (becomes the resource suffix). */
+  readonly name: string;
+  /** Resource ref `facet:name`. */
+  readonly ref: ResourceRef;
+}
+
+/** Options for {@link store.sql}. */
+export interface SqlStoreOptions {
+  /**
+   * Schema tables — okengine {@link TableHandle}s and/or Drizzle tables.
+   * Classification is read from TableHandle columns when present.
+   */
+  readonly schema?: Readonly<Record<string, TableHandle | unknown>>;
+  /**
+   * 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>>>
+  >;
+}
+
+/** SQL store declaration. */
+export interface SqlStoreDecl extends StoreDeclBase {
+  readonly facet: "sql";
+  readonly ref: `sql:${string}`;
+  readonly schema?: SqlStoreOptions["schema"];
+  readonly classify?: SqlStoreOptions["classify"];
+  /**
+   * CDC handle — `db.table(orders).changed("status")`.
+   *
+   * @param table - Table handle or Drizzle table
+   */
+  table(table: TableHandle | unknown): StoreTableCdc;
+}
+
+/** Options for {@link store.kv}. */
+export interface KvStoreOptions {
+  /** Optional description. */
+  readonly description?: string;
+}
+
+/** KV store declaration. */
+export interface KvStoreDecl extends StoreDeclBase {
+  readonly facet: "kv";
+  readonly ref: `kv:${string}`;
+  readonly description?: string;
+}
+
+/** Options for {@link store.files}. */
+export interface FilesStoreOptions {
+  /** Optional description. */
+  readonly description?: string;
+}
+
+/** Files store declaration. */
+export interface FilesStoreDecl extends StoreDeclBase {
+  readonly facet: "files";
+  readonly ref: `files:${string}`;
+  readonly description?: string;
+}
+
+/** Options for {@link store.index}. */
+export interface IndexStoreOptions {
+  /** Vector dimensions (default 3 for tests; set explicitly in apps). */
+  readonly dims?: number;
+}
+
+/** Index store declaration. */
+export interface IndexStoreDecl extends StoreDeclBase {
+  readonly facet: "index";
+  readonly ref: `index:${string}`;
+  readonly dims?: number;
+}
+
+/** Any store declaration. */
+export type StoreDecl =
+  | SqlStoreDecl
+  | KvStoreDecl
+  | FilesStoreDecl
+  | IndexStoreDecl;
+
+/**
+ * Declare a SQL store.
+ *
+ * @param name - Store name
+ * @param options - Schema / classification
+ */
+export function sql(name: string, options: SqlStoreOptions = {}): SqlStoreDecl {
+  const decl: SqlStoreDecl = {
+    facet: "sql",
+    name,
+    ref: `sql:${name}`,
+    schema: options.schema,
+    classify: options.classify,
+    table(table) {
+      const tableName = resolveTableName(table);
+      return {
+        name: tableName,
+        changed(column?: string): StoreCdcTrigger {
+          return column === undefined
+            ? { kind: "cdc", table: tableName, store: name }
+            : { kind: "cdc", table: tableName, column, store: name };
+        },
+      };
+    },
+  };
+  return decl;
+}
+
+/**
+ * Declare a KV store.
+ *
+ * @param name - Namespace name
+ * @param options - Options
+ */
+export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
+  return {
+    facet: "kv",
+    name,
+    ref: `kv:${name}`,
+    description: options.description,
+  };
+}
+
+/**
+ * Declare a files store.
+ *
+ * @param name - Bucket name
+ * @param options - Options
+ */
+export function files(
+  name: string,
+  options: FilesStoreOptions = {},
+): FilesStoreDecl {
+  return {
+    facet: "files",
+    name,
+    ref: `files:${name}`,
+    description: options.description,
+  };
+}
+
+/**
+ * Declare a vector index store.
+ *
+ * @param name - Index name
+ * @param options - Dimensions
+ */
+export function index(
+  name: string,
+  options: IndexStoreOptions = {},
+): IndexStoreDecl {
+  return {
+    facet: "index",
+    name,
+    ref: `index:${name}`,
+    dims: options.dims,
+  };
+}
+
+/** Public `store` element — four facets. */
+export const store = {
+  sql,
+  kv,
+  files,
+  index,
+} as const;

package/src/elements/store/files-policy.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import {
+  contentAddressedKey,
+  fileKeyWarnings,
+  projectFileKeys,
+} from "./files-policy.ts";
+
+describe("files-policy", () => {
+  test("flags non-ASCII keys for signed-URL risk", () => {
+    const warnings = fileKeyWarnings("фото/id.jpg");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.code).toBe("non_ascii_key");
+  });
+
+  test("ascii keys produce no warnings", () => {
+    expect(fileKeyWarnings("a/b/c.png")).toEqual([]);
+  });
+
+  test("contentAddressedKey is stable sha256 hex", async () => {
+    const a = await contentAddressedKey("hello");
+    const b = await contentAddressedKey("hello");
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("projectFileKeys attaches warnings per key", () => {
+    const rows = projectFileKeys(["ok.txt", "café.bin"]);
+    expect(rows[0]?.warnings).toEqual([]);
+    expect(rows[1]?.warnings[0]?.code).toBe("non_ascii_key");
+  });
+});

package/src/elements/store/files-policy.ts

@@ -0,0 +1,70 @@
+/**
+ * Files facet operational policy — content-addressed keys + driver warnings.
+ *
+ * Warnings are generated here (element physics) so the Console surfaces them
+ * automatically rather than inventing hand-written copy (console §9.5 · §11).
+ */
+
+/** One operational warning attached to a files key. */
+export interface FileKeyWarning {
+  /** Stable machine code. */
+  readonly code: "non_ascii_key";
+  /** Human-readable operator message. */
+  readonly message: string;
+  /** Object key that triggered the warning. */
+  readonly key: string;
+}
+
+/**
+ * Operational warnings for a files object key.
+ *
+ * Non-ASCII keys break signed-URL percent-encoding on S3-compatible stores.
+ *
+ * @param key - Object key
+ */
+export function fileKeyWarnings(key: string): readonly FileKeyWarning[] {
+  const warnings: FileKeyWarning[] = [];
+  // eslint-disable-next-line no-control-regex -- intentional: detect non-ASCII
+  if (/[^\x00-\x7F]/.test(key)) {
+    warnings.push({
+      code: "non_ascii_key",
+      message:
+        "Non-ASCII object key — signed URL encoding may break on S3-compatible stores.",
+      key,
+    });
+  }
+  return warnings;
+}
+
+/**
+ * Content-addressed object key (sha256 hex of bytes).
+ *
+ * @param data - Object bytes or UTF-8 string
+ */
+export async function contentAddressedKey(
+  data: Uint8Array | string,
+): Promise<string> {
+  const bytes =
+    typeof data === "string"
+      ? new TextEncoder().encode(data)
+      : new Uint8Array(data);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Attach warnings to a list of object keys.
+ *
+ * @param keys - Object keys from the driver
+ */
+export function projectFileKeys(keys: readonly string[]): ReadonlyArray<{
+  readonly key: string;
+  readonly warnings: readonly FileKeyWarning[];
+}> {
+  return keys.map((key) => ({
+    key,
+    warnings: fileKeyWarnings(key),
+  }));
+}

package/src/elements/store/replica.ts

@@ -0,0 +1,68 @@
+/**
+ * Automatic replica routing — derived from the effect set.
+ *
+ * Read-only flows (reads declared, no store writes) route to replicas.
+ * No annotations required on the flow.
+ */
+
+import type { Effects } from "../../manifest/types.ts";
+import type { SqlConnectOptions, SqlRole } from "../../drivers/types.ts";
+
+/**
+ * Whether a flow's effect set is store-read-only (eligible for replica routing).
+ *
+ * Emits / sends / asks do not force the primary — only `writes` do.
+ *
+ * @param effects - Declared or inferred effects
+ */
+export function isReadOnlyStoreFlow(effects: Effects): boolean {
+  const writes = effects.writes?.length ?? 0;
+  return writes === 0;
+}
+
+/**
+ * Choose the SQL connection role for a flow from its effects.
+ *
+ * @param effects - Flow effects
+ * @param hasReplicas - Whether replicas are configured
+ */
+export function sqlRoleForEffects(
+  effects: Effects,
+  hasReplicas: boolean,
+): SqlRole {
+  if (hasReplicas && isReadOnlyStoreFlow(effects)) return "replica";
+  return "primary";
+}
+
+/** SQL binding with optional read replicas. */
+export interface SqlBindingConfig {
+  /** Primary connection options. */
+  readonly primary: SqlConnectOptions;
+  /** Read replicas (round-robin). */
+  readonly replicas?: readonly SqlConnectOptions[];
+}
+
+/**
+ * Resolve which connection options to use for a flow.
+ *
+ * @param config - Primary + replicas
+ * @param effects - Flow effects
+ * @param pickReplica - Index picker (defaults to 0)
+ */
+export function resolveSqlTarget(
+  config: SqlBindingConfig,
+  effects: Effects,
+  pickReplica: (count: number) => number = () => 0,
+): { readonly role: SqlRole; readonly options: SqlConnectOptions } {
+  const replicas = config.replicas ?? [];
+  const role = sqlRoleForEffects(effects, replicas.length > 0);
+  if (role === "replica") {
+    const idx = Math.abs(pickReplica(replicas.length)) % replicas.length;
+    const options = replicas[idx]!;
+    return { role: "replica", options: { ...options, role: "replica" } };
+  }
+  return {
+    role: "primary",
+    options: { ...config.primary, role: "primary" },
+  };
+}