okengine 0.1.4

package/src/console/ui/store/fixture.ts

@@ -0,0 +1,163 @@
+/**
+ * Fixture stores for unit tests and the axe gate.
+ */
+
+import type { StoreListResponse, StoreRecord } from "./types.ts";
+
+/** Skyport-shaped Store fixture covering all four facets. */
+export const STORE_FIXTURE: readonly StoreRecord[] = [
+  {
+    ref: "sql:db",
+    facet: "sql",
+    name: "db",
+    children: [
+      {
+        name: "bookings",
+        effectRef: "sql:bookings",
+        writers: ["bookings.create"],
+        readers: ["bookings.create", "bookings.mine"],
+        cache: {
+          producedByRead: "computed:sql:bookings",
+          invalidatedByWrites: ["sql:bookings"],
+          invalidatingFlowIds: ["bookings.create"],
+        },
+        willNotFire: {
+          writerFlowIds: ["bookings.create"],
+          signals: ["order-placed"],
+          channels: [],
+        },
+        piiColumns: ["email"],
+      },
+      {
+        name: "shipments",
+        effectRef: "sql:shipments",
+        writers: ["fulfillment.onOrder"],
+        readers: [],
+        cache: {
+          producedByRead: "computed:sql:shipments",
+          invalidatedByWrites: ["sql:shipments"],
+          invalidatingFlowIds: ["fulfillment.onOrder"],
+        },
+        willNotFire: {
+          writerFlowIds: ["fulfillment.onOrder"],
+          signals: [],
+          channels: ["booking-confirmed"],
+        },
+        piiColumns: [],
+      },
+    ],
+    replicaLagMs: 240,
+    migrationDrift: {
+      declared: "abc123",
+      applied: "abc123",
+      drifted: false,
+    },
+    contentAddressed: false,
+    warnings: [],
+  },
+  {
+    ref: "kv:sessions",
+    facet: "kv",
+    name: "sessions",
+    children: [
+      {
+        name: "sessions",
+        effectRef: "kv:sessions",
+        writers: [],
+        readers: [],
+        cache: {
+          producedByRead: "computed:kv:sessions",
+          invalidatedByWrites: [],
+          invalidatingFlowIds: [],
+        },
+        willNotFire: {
+          writerFlowIds: [],
+          signals: [],
+          channels: [],
+        },
+        piiColumns: [],
+      },
+    ],
+    replicaLagMs: null,
+    migrationDrift: null,
+    contentAddressed: false,
+    warnings: [],
+  },
+  {
+    ref: "files:uploads",
+    facet: "files",
+    name: "uploads",
+    children: [
+      {
+        name: "uploads",
+        effectRef: "files:uploads",
+        writers: [],
+        readers: [],
+        cache: {
+          producedByRead: "computed:files:uploads",
+          invalidatedByWrites: [],
+          invalidatingFlowIds: [],
+        },
+        willNotFire: {
+          writerFlowIds: [],
+          signals: [],
+          channels: [],
+        },
+        piiColumns: [],
+      },
+    ],
+    replicaLagMs: null,
+    migrationDrift: null,
+    contentAddressed: true,
+    warnings: [
+      {
+        code: "non_ascii_key",
+        message:
+          "Non-ASCII object key — signed URL encoding may break on S3-compatible stores.",
+        key: "фото/id.jpg",
+      },
+    ],
+  },
+  {
+    ref: "index:docs",
+    facet: "index",
+    name: "docs",
+    children: [
+      {
+        name: "docs",
+        effectRef: "index:docs",
+        writers: [],
+        readers: [],
+        cache: {
+          producedByRead: "computed:index:docs",
+          invalidatedByWrites: [],
+          invalidatingFlowIds: [],
+        },
+        willNotFire: {
+          writerFlowIds: [],
+          signals: [],
+          channels: [],
+        },
+        piiColumns: [],
+      },
+    ],
+    replicaLagMs: null,
+    migrationDrift: null,
+    contentAddressed: false,
+    warnings: [],
+  },
+];
+
+/** Full list envelope with tenancy declared (Skyport-shaped). */
+export const STORE_LIST_FIXTURE: StoreListResponse = {
+  tenancyDeclared: true,
+  tenants: ["tenant_a", "tenant_b"],
+  stores: STORE_FIXTURE,
+};
+
+/** List envelope without tenancy (Notes-shaped). */
+export const STORE_LIST_NO_TENANCY: StoreListResponse = {
+  tenancyDeclared: false,
+  tenants: [],
+  stores: STORE_FIXTURE,
+};

package/src/console/ui/store/group.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { STORE_FIXTURE } from "./fixture.ts";
+import { groupByFacet } from "./group.ts";
+
+describe("groupByFacet", () => {
+  test("groups into sql / kv / files / index", () => {
+    const groups = groupByFacet(STORE_FIXTURE);
+    expect(groups.map((g) => g.facet)).toEqual([
+      "sql",
+      "kv",
+      "files",
+      "index",
+    ]);
+  });
+
+  test("filters by name", () => {
+    const groups = groupByFacet(STORE_FIXTURE, "bookings");
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.facet).toBe("sql");
+  });
+});

package/src/console/ui/store/group.ts

@@ -0,0 +1,41 @@
+/**
+ * Group stores by facet — one list, adaptive detail (console §9.5).
+ */
+
+import type { StoreFacet, StoreFacetGroup, StoreRecord } from "./types.ts";
+
+const FACET_ORDER: readonly StoreFacet[] = ["sql", "kv", "files", "index"];
+
+const FACET_LABELS: Record<StoreFacet, string> = {
+  sql: "SQL",
+  kv: "KV",
+  files: "Files",
+  index: "Index",
+};
+
+/**
+ * Group store rows by facet, optional name filter.
+ *
+ * @param stores - Projected rows
+ * @param q - Optional filter
+ */
+export function groupByFacet(
+  stores: readonly StoreRecord[],
+  q = "",
+): readonly StoreFacetGroup[] {
+  const needle = q.trim().toLowerCase();
+  const filtered = needle
+    ? stores.filter(
+        (s) =>
+          s.name.toLowerCase().includes(needle) ||
+          s.ref.toLowerCase().includes(needle) ||
+          s.children.some((c) => c.name.toLowerCase().includes(needle)),
+      )
+    : stores;
+
+  return FACET_ORDER.map((facet) => ({
+    facet,
+    label: FACET_LABELS[facet],
+    stores: filtered.filter((s) => s.facet === facet),
+  })).filter((g) => g.stores.length > 0);
+}

package/src/console/ui/store/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Store panel pure modules (console §9.5).
+ */
+
+export type {
+  StoreCacheView,
+  StoreChild,
+  StoreFacet,
+  StoreFacetGroup,
+  StoreListResponse,
+  StoreRecord,
+  WillNotFire,
+} from "./types.ts";
+
+export {
+  parseStoreSearch,
+  serializeStoreSearch,
+  openStore,
+  closeStore,
+  openChild,
+  type StoreSearch,
+} from "./search.ts";
+
+export { groupByFacet } from "./group.ts";
+export {
+  editConfirmation,
+  deleteConfirmation,
+  purgeConfirmation,
+  validateTypedConfirm,
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "./confirmation.ts";
+export { formatWillNotFire, type WillNotFireLines } from "./will-not-fire.ts";
+export { previewOffer, type PreviewOffer } from "./dry-run.ts";
+export { explainCache, type CacheExplanation } from "./cache-view.ts";
+export {
+  STORE_FIXTURE,
+  STORE_LIST_FIXTURE,
+  STORE_LIST_NO_TENANCY,
+} from "./fixture.ts";

package/src/console/ui/store/search.ts

@@ -0,0 +1,78 @@
+/**
+ * URL search state for the Store panel.
+ */
+
+import { z } from "zod";
+
+const StoreSearchSchema = z.object({
+  q: z.string().optional(),
+  ref: z.string().optional(),
+  child: z.string().optional(),
+  /** Only meaningful when `tenancyDeclared` — compliance boundary, not a filter. */
+  tenant: z.string().optional(),
+  view: z.enum(["browse", "cache", "sql", "probe"]).optional(),
+  prefix: z.string().optional(),
+});
+
+/** Parsed Store URL search. */
+export type StoreSearch = z.infer<typeof StoreSearchSchema>;
+
+/**
+ * Parse Store panel search params.
+ *
+ * @param search - Raw router search
+ */
+export function parseStoreSearch(
+  search: Record<string, unknown>,
+): StoreSearch {
+  const parsed = StoreSearchSchema.safeParse(search);
+  return parsed.success ? parsed.data : {};
+}
+
+/**
+ * Serialize Store search for navigation (omit empties).
+ *
+ * @param search - Search state
+ */
+export function serializeStoreSearch(
+  search: StoreSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.q) out.q = search.q;
+  if (search.ref) out.ref = search.ref;
+  if (search.child) out.child = search.child;
+  if (search.tenant) out.tenant = search.tenant;
+  if (search.view && search.view !== "browse") out.view = search.view;
+  if (search.prefix) out.prefix = search.prefix;
+  return out;
+}
+
+/**
+ * Open a store ref in the URL.
+ *
+ * @param search - Current search
+ * @param ref - Store ref
+ */
+export function openStore(search: StoreSearch, ref: string): StoreSearch {
+  return { ...search, ref, child: undefined, view: "browse" };
+}
+
+/**
+ * Close the open store detail.
+ *
+ * @param search - Current search
+ */
+export function closeStore(search: StoreSearch): StoreSearch {
+  const { ref: _r, child: _c, view: _v, ...rest } = search;
+  return rest;
+}
+
+/**
+ * Select a child resource (table / keyspace / …).
+ *
+ * @param search - Current search
+ * @param child - Child name
+ */
+export function openChild(search: StoreSearch, child: string): StoreSearch {
+  return { ...search, child, view: "browse" };
+}

package/src/console/ui/store/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Store panel view types (console §9.5).
+ */
+
+/** Store facet. */
+export type StoreFacet = "sql" | "kv" | "files" | "index";
+
+/** Will-not-fire payload for a direct edit confirmation. */
+export interface WillNotFire {
+  readonly writerFlowIds: readonly string[];
+  readonly signals: readonly string[];
+  readonly channels: readonly string[];
+}
+
+/** Cache sub-view for one child resource. */
+export interface StoreCacheView {
+  readonly producedByRead: string;
+  readonly invalidatedByWrites: readonly string[];
+  readonly invalidatingFlowIds: readonly string[];
+}
+
+/** Child resource under a store. */
+export interface StoreChild {
+  readonly name: string;
+  readonly effectRef: string;
+  readonly writers: readonly string[];
+  readonly readers: readonly string[];
+  readonly cache: StoreCacheView;
+  readonly willNotFire: WillNotFire;
+  readonly piiColumns: readonly string[];
+}
+
+/** One store row from `console.store.list`. */
+export interface StoreRecord {
+  readonly ref: string;
+  readonly facet: StoreFacet;
+  readonly name: string;
+  readonly children: readonly StoreChild[];
+  readonly replicaLagMs: number | null;
+  readonly migrationDrift: {
+    readonly declared: string;
+    readonly applied: string | null;
+    readonly drifted: boolean;
+  } | null;
+  readonly contentAddressed: boolean;
+  readonly warnings: ReadonlyArray<{
+    readonly code: string;
+    readonly message: string;
+    readonly key: string;
+  }>;
+}
+
+/** Facet group for the list. */
+export interface StoreFacetGroup {
+  readonly facet: StoreFacet;
+  readonly label: string;
+  readonly stores: readonly StoreRecord[];
+}
+
+/** List response envelope. */
+export interface StoreListResponse {
+  readonly tenancyDeclared: boolean;
+  readonly tenants: readonly string[];
+  readonly stores: readonly StoreRecord[];
+}

package/src/console/ui/store/will-not-fire.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { STORE_FIXTURE } from "./fixture.ts";
+import { formatWillNotFire } from "./will-not-fire.ts";
+
+describe("formatWillNotFire", () => {
+  test("names signals and channels from Manifest writers", () => {
+    const bookings = STORE_FIXTURE[0]!.children[0]!;
+    const lines = formatWillNotFire(bookings.willNotFire);
+    expect(lines.empty).toBe(false);
+    expect(lines.lines.some((l) => l.includes("order-placed"))).toBe(true);
+    expect(lines.lines.some((l) => l.includes("bookings.create"))).toBe(true);
+  });
+
+  test("names channels for fulfillment writers", () => {
+    const shipments = STORE_FIXTURE[0]!.children[1]!;
+    const lines = formatWillNotFire(shipments.willNotFire);
+    expect(lines.lines.some((l) => l.includes("booking-confirmed"))).toBe(true);
+  });
+});

package/src/console/ui/store/will-not-fire.ts

@@ -0,0 +1,40 @@
+/**
+ * Format Manifest-derived "will not fire" copy for direct-edit confirmation.
+ *
+ * A direct edit is not a flow execution — name the signals/channels skipped.
+ */
+
+import type { WillNotFire } from "./types.ts";
+
+/** Formatted confirmation lines. */
+export interface WillNotFireLines {
+  readonly headline: string;
+  readonly lines: readonly string[];
+  readonly empty: boolean;
+}
+
+/**
+ * Build operator-facing lines naming what will NOT happen on a direct edit.
+ *
+ * @param willNotFire - Manifest-derived payload
+ */
+export function formatWillNotFire(willNotFire: WillNotFire): WillNotFireLines {
+  const lines: string[] = [];
+  for (const signal of willNotFire.signals) {
+    lines.push(`Signal \`${signal}\` will not be emitted`);
+  }
+  for (const channel of willNotFire.channels) {
+    lines.push(`Channel \`${channel}\` will not fire`);
+  }
+  if (willNotFire.writerFlowIds.length > 0) {
+    lines.push(
+      `Owning flow(s): ${willNotFire.writerFlowIds.map((f) => `\`${f}\``).join(", ")} — not executed`,
+    );
+  }
+  return {
+    headline:
+      "Direct edit is not a flow execution — the following will NOT happen:",
+    lines,
+    empty: lines.length === 0,
+  };
+}

package/src/console/ui/traces/TracesA11yView.tsx

@@ -0,0 +1,200 @@
+/**
+ * Static Traces markup for the axe gate — same landmarks / roles as the
+ * live panel, fed by a fixture (no router / network).
+ */
+
+import { buildCausalChain, groupTraceRoots, initialFocusSpanId } from "./chain.ts";
+import { criticalPathSpanIds } from "./critical-path.ts";
+import { TRACES_FIXTURE } from "./fixture.ts";
+import { foldTimeline, intervalsFromSpans } from "./fold.ts";
+import { miniWaterfall, rootErrorCode } from "./mini.ts";
+import { replayDecision } from "./replay.ts";
+import { DEFAULT_SAMPLING_LABEL } from "./sampling.ts";
+import { peakSpanTier } from "./tier.ts";
+
+/** Props for {@link TracesA11yView}. */
+export interface TracesA11yViewProps {
+  /** Optional root id to open in detail. */
+  readonly openRootId?: string;
+}
+
+/**
+ * Accessible Traces list + detail for CI.
+ *
+ * @param props - Optional open root
+ */
+export function TracesA11yView(props: TracesA11yViewProps) {
+  const roots = groupTraceRoots(TRACES_FIXTURE);
+  const openRootId = props.openRootId ?? "run-create-ok";
+  const open = roots.find((r) => r.rootId === openRootId);
+  const focusId = open
+    ? initialFocusSpanId(open.spans)
+    : undefined;
+  const chain = focusId
+    ? buildCausalChain(TRACES_FIXTURE, focusId)
+    : null;
+  const critical = chain
+    ? criticalPathSpanIds(chain.connected)
+    : new Set<string>();
+  const folded = chain
+    ? foldTimeline(intervalsFromSpans(chain.connected), {}, critical)
+    : null;
+  const decision = chain ? replayDecision(chain.connected) : null;
+
+  return (
+    <div className="traces-a11y">
+      <a href="#traces-main">Skip to main content</a>
+      <header>
+        <h1>Traces</h1>
+        <p>Sampling: {DEFAULT_SAMPLING_LABEL}</p>
+        <label>
+          Filter by effect
+          <select aria-label="Filter by effect" defaultValue="">
+            <option value="">All effects</option>
+            <option value="wrote:sql:bookings">Wrote sql:bookings</option>
+            <option value="sent">Sent email</option>
+            <option value="asked">Asked a model</option>
+            <option value="secret">Read a secret</option>
+            <option value="cost:0.05">Cost &gt; $0.05</option>
+          </select>
+        </label>
+        <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+          Trace bookings.create fully for 10 minutes
+        </button>
+      </header>
+      <main id="traces-main">
+        <section aria-label="Trace list">
+          <h2>Traces</h2>
+          <ul>
+            {roots.map((root) => {
+              const err = rootErrorCode(root.spans);
+              const bars = miniWaterfall(root.spans);
+              return (
+                <li key={root.rootId}>
+                  <button
+                    type="button"
+                    aria-pressed={root.rootId === openRootId}
+                    style={{ minHeight: 32, width: "100%" }}
+                  >
+                    <span>{root.root.flow}</span>
+                    {err ? (
+                      <span role="status" style={{ color: "#c44b4b" }}>
+                        {" "}
+                        {err}
+                      </span>
+                    ) : null}
+                    <span aria-hidden="true">
+                      {" "}
+                      [{bars.length} bars]
+                    </span>
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        </section>
+
+        {chain && folded ? (
+          <section aria-label="Trace detail" aria-live="polite">
+            <h2>Causal chain</h2>
+            <ol>
+              {chain.parents.map((p) => (
+                <li key={p.id}>
+                  <button type="button" style={{ minHeight: 32 }}>
+                    {p.flow}
+                  </button>
+                </li>
+              ))}
+              <li aria-current="true">
+                <strong>{chain.current.flow}</strong>
+                {chain.current.errorCode ? (
+                  <span role="status"> {chain.current.errorCode}</span>
+                ) : null}
+              </li>
+              {chain.children.map((c) => (
+                <li key={c.id}>
+                  <button type="button" style={{ minHeight: 32 }}>
+                    {c.flow}
+                  </button>
+                </li>
+              ))}
+            </ol>
+
+            <h2 id="waterfall-heading">Waterfall</h2>
+            <ul
+              aria-labelledby="waterfall-heading"
+              style={{
+                display: "flex",
+                gap: 2,
+                minHeight: 32,
+                listStyle: "none",
+                padding: 0,
+                margin: 0,
+              }}
+            >
+              {folded.segments.map((seg) => {
+                if (seg.kind === "fold") {
+                  return (
+                    <li
+                      key={seg.id}
+                      style={{ flex: `${seg.displayMs} 0 0` }}
+                    >
+                      <button
+                        type="button"
+                        aria-expanded={seg.expanded}
+                        style={{ minHeight: 32, minWidth: 24, width: "100%" }}
+                      >
+                        {seg.label}
+                      </button>
+                    </li>
+                  );
+                }
+                const dim = !seg.critical;
+                const external =
+                  peakSpanTier(
+                    chain.connected.find((s) => s.id === seg.spanId)
+                      ?.effects ?? [],
+                  ) === "external";
+                return (
+                  <li
+                    key={seg.id}
+                    style={{
+                      minHeight: 32,
+                      flex: `${seg.displayMs} 0 0`,
+                      opacity: dim ? 0.38 : 1,
+                      background:
+                        seg.tier === "external" ? "#d97706" : "#3d9a6a",
+                      outline: seg.failed ? "2px solid #c44b4b" : undefined,
+                    }}
+                  >
+                    {seg.label}
+                    {seg.critical ? " (critical path)" : ""}
+                    {seg.failed ? " (failed)" : ""}
+                    {external ? " ↗" : ""}
+                  </li>
+                );
+              })}
+            </ul>
+
+            <a href={`/runs?run=${chain.current.id}`}>Open in Runs</a>
+            <button
+              type="button"
+              style={{ minHeight: 32, minWidth: 24 }}
+              title={
+                decision?.mode === "dry-run" ? decision.reason : undefined
+              }
+            >
+              {decision?.mode === "dry-run" ? "Dry-run replay" : "Replay"}
+            </button>
+            <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+              Close
+            </button>
+            <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+              3 new
+            </button>
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}