@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/testing/assertions.ts

@@ -1,986 +1,986 @@
-/**
- * Phase C.1 — Semantic Primitives (@mandujs/core/testing barrel).
- *
- * Mandu-specific assertion primitives that the generic Playwright / bun:test
- * vocabulary cannot express cleanly:
- *
- *   - `expectContract`      — Zod shape validation with strict/loose/drift
- *     modes and path-based `ignorePaths`. Replaces `JSON.stringify`
- *     comparisons.
- *   - `expectNavigation`    — redirect-chain capture for Playwright pages.
- *   - `waitForIsland`       — polls `data-island="<name>"`'s
- *     `data-hydrated`/`data-island-state` attribute. Short-circuits for
- *     `hydration:none` strategies.
- *   - `assertStreamBoundary`— consumes a streaming SSR response and counts
- *     `<!--$-->` / `<!--/$-->` boundary markers. Validates shell chunk
- *     byte budgets and tail chunk content.
- *   - `expectSemantic`      — agent-delegated oracle. Writes an entry to
- *     `.mandu/ate-oracle-queue.jsonl` for an agent to judge later. CI is
- *     never blocked (`MANDU_ATE_DETERMINISTIC_ONLY=1` skips queueing).
- *     `promoteVerdicts: true` option lets a previously-failed verdict
- *     become a deterministic fail on re-run.
- *
- * Spec: docs/ate/phase-c-spec.md §C.1.
- *
- * These primitives live in `@mandujs/core/testing` (not `@mandujs/ate`) so
- * they are usable in any Mandu project test file, with or without the ATE
- * MCP server.
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-  appendFileSync,
-} from "node:fs";
-import { join, dirname, isAbsolute } from "node:path";
-
-// ────────────────────────────────────────────────────────────────────────────
-// expectContract
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Minimal structural type of a Zod schema. We don't import `zod` here —
- * the caller provides the schema and we only call `safeParse`. This keeps
- * `@mandujs/core/testing` free of a zod peer dep for consumers who don't
- * use it.
- */
-/**
- * Structural type matching both real `zod` schemas and hand-rolled
- * fakes. We intentionally widen the `error.issues` shape to `unknown[]`
- * — the primitive normalizes each issue internally so the call sites
- * don't have to worry about Zod version drift.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export interface ZodLikeSchema<T = unknown> {
-  safeParse: (input: unknown) => {
-    success: boolean;
-    data?: T;
-    // Intentionally loose — see note above.
-    error?: { issues: readonly unknown[] } | undefined;
-  };
-}
-
-interface NormalizedIssue {
-  path: Array<string | number>;
-  message: string;
-  code?: string;
-  expected?: string;
-  received?: string;
-}
-
-function normalizeIssue(raw: unknown): NormalizedIssue {
-  const obj = (raw ?? {}) as Record<string, unknown>;
-  const pathRaw = obj.path;
-  const path: Array<string | number> = Array.isArray(pathRaw)
-    ? (pathRaw.filter((p) => typeof p === "string" || typeof p === "number") as Array<
-        string | number
-      >)
-    : [];
-  return {
-    path,
-    message: typeof obj.message === "string" ? obj.message : "",
-    ...(typeof obj.code === "string" ? { code: obj.code } : {}),
-    ...(typeof obj.expected === "string" ? { expected: obj.expected } : {}),
-    ...(typeof obj.received === "string" ? { received: obj.received } : {}),
-  };
-}
-
-export type ContractMode = "strict" | "loose" | "drift-tolerant";
-
-export interface ContractViolation {
-  path: string;
-  expected: string;
-  actual: string;
-  severity: "critical" | "warning";
-}
-
-export interface ExpectContractOptions {
-  mode?: ContractMode;
-  /**
-   * Dot-notation paths to ignore. Use `.createdAt`, `.items[0].updatedAt`,
-   * or `.user.id`. Matching is prefix-aware — `.user` ignores every
-   * descendant field.
-   */
-  ignorePaths?: string[];
-}
-
-export interface ExpectContractResult {
-  status: "pass" | "fail";
-  violations: ContractViolation[];
-}
-
-/**
- * Validate `actual` against a Zod schema and surface structured
- * violations. Throws when `status === "fail"` unless `mode` is
- * `drift-tolerant`, which only records warnings.
- *
- * @example
- * ```ts
- * expectContract(await res.json(), SignupResponseSchema, {
- *   mode: "loose",
- *   ignorePaths: [".createdAt", ".user.id"],
- * });
- * ```
- */
-export function expectContract<T>(
-  actual: unknown,
-  schema: ZodLikeSchema<T>,
-  options: ExpectContractOptions = {},
-): ExpectContractResult {
-  const mode: ContractMode = options.mode ?? "strict";
-  const ignore = options.ignorePaths ?? [];
-
-  const result = schema.safeParse(actual);
-
-  if (result.success) {
-    // Strict mode: walk `actual` looking for keys not mentioned anywhere
-    // in the schema. We can't introspect a Zod schema structurally without
-    // the runtime — instead we round-trip through `safeParse`'s `data`
-    // which a default Zod schema strips unknown keys from (unless the
-    // schema uses `.passthrough()` / `.strict()`). If `data` shape differs
-    // from `actual` in strict mode, we flag the extras.
-    if (mode === "strict" && result.data !== undefined) {
-      const extras = findExtraKeys("", actual, result.data, ignore);
-      if (extras.length > 0) {
-        const violations: ContractViolation[] = extras.map((e) => ({
-          path: e,
-          expected: "(not in schema)",
-          actual: "extra key present",
-          severity: "critical",
-        }));
-        throwViolations(violations, "strict");
-        return { status: "fail", violations };
-      }
-    }
-    return { status: "pass", violations: [] };
-  }
-
-  // safeParse failed — translate Zod issues to our violation shape.
-  const rawIssues = result.error?.issues ?? [];
-  const violations: ContractViolation[] = [];
-  for (const raw of rawIssues) {
-    const issue = normalizeIssue(raw);
-    const path = pathToString(issue.path);
-    if (isIgnored(path, ignore)) continue;
-
-    // loose mode forgives extra-key errors (unrecognized keys) but keeps
-    // `missing_required` + format violations.
-    if (mode === "loose" && isExtraKeyIssue(issue)) continue;
-
-    const severity: "critical" | "warning" =
-      mode === "drift-tolerant" ? "warning" : "critical";
-    violations.push({
-      path,
-      expected: issue.expected ?? issue.message,
-      actual: issue.received ?? describeActual(actual, issue.path),
-      severity,
-    });
-  }
-
-  if (violations.length === 0) {
-    return { status: "pass", violations: [] };
-  }
-
-  if (mode === "drift-tolerant") {
-    // Warnings collected; no throw. Caller may log via
-    // `mandu_ate_remember({ kind: "contract_drift" })`.
-    return { status: "fail", violations };
-  }
-
-  throwViolations(violations, mode);
-  return { status: "fail", violations };
-}
-
-function isExtraKeyIssue(issue: { code?: string; message?: string }): boolean {
-  if (issue.code === "unrecognized_keys") return true;
-  return /unrecognized key/i.test(issue.message ?? "");
-}
-
-function throwViolations(violations: ContractViolation[], mode: ContractMode): never {
-  const summary = violations
-    .slice(0, 5)
-    .map((v) => `  - ${v.path}: expected ${v.expected}, got ${v.actual}`)
-    .join("\n");
-  const more = violations.length > 5 ? `\n  ... +${violations.length - 5} more` : "";
-  throw new ContractAssertionError(
-    `expectContract (${mode}) failed with ${violations.length} violation(s):\n${summary}${more}`,
-    violations,
-  );
-}
-
-export class ContractAssertionError extends Error {
-  violations: ContractViolation[];
-  constructor(message: string, violations: ContractViolation[]) {
-    super(message);
-    this.name = "ContractAssertionError";
-    this.violations = violations;
-  }
-}
-
-function pathToString(path: Array<string | number>): string {
-  let out = "";
-  for (const seg of path) {
-    if (typeof seg === "number") out += `[${seg}]`;
-    else out += `.${seg}`;
-  }
-  return out;
-}
-
-function isIgnored(path: string, ignore: string[]): boolean {
-  for (const ign of ignore) {
-    if (path === ign || path.startsWith(ign + ".") || path.startsWith(ign + "[")) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function describeActual(actual: unknown, path: Array<string | number>): string {
-  let cursor: unknown = actual;
-  for (const seg of path) {
-    if (cursor === null || cursor === undefined) return "undefined";
-    cursor = (cursor as Record<string | number, unknown>)[seg as string];
-  }
-  if (cursor === null) return "null";
-  if (cursor === undefined) return "undefined";
-  if (typeof cursor === "object") return JSON.stringify(cursor).slice(0, 60);
-  return JSON.stringify(cursor);
-}
-
-/**
- * Find keys present in `actual` that are NOT present in `parsed` — extra
- * keys Zod stripped during safeParse. Only used in strict mode.
- */
-function findExtraKeys(
-  prefix: string,
-  actual: unknown,
-  parsed: unknown,
-  ignore: string[],
-): string[] {
-  const out: string[] = [];
-  if (!actual || typeof actual !== "object" || Array.isArray(actual)) return out;
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return out;
-
-  const actualKeys = Object.keys(actual as Record<string, unknown>);
-  const parsedKeys = new Set(Object.keys(parsed as Record<string, unknown>));
-
-  for (const key of actualKeys) {
-    const path = `${prefix}.${key}`;
-    if (isIgnored(path, ignore)) continue;
-    if (!parsedKeys.has(key)) {
-      out.push(path);
-      continue;
-    }
-    const aVal = (actual as Record<string, unknown>)[key];
-    const pVal = (parsed as Record<string, unknown>)[key];
-    if (
-      aVal !== null &&
-      typeof aVal === "object" &&
-      !Array.isArray(aVal) &&
-      pVal !== null &&
-      typeof pVal === "object" &&
-      !Array.isArray(pVal)
-    ) {
-      out.push(...findExtraKeys(path, aVal, pVal, ignore));
-    }
-  }
-
-  return out;
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// expectNavigation
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Minimal Playwright Page shape — we only touch the bits we need so
- * consumers can use `@playwright/test`'s `Page` without creating an
- * import coupling.
- */
-export interface PlaywrightLikePage {
-  url(): string;
-  on(event: "framenavigated", listener: (frame: { url: () => string }) => void): void;
-  off?(event: "framenavigated", listener: (frame: { url: () => string }) => void): void;
-  waitForURL?(url: string | RegExp, opts?: { timeout?: number }): Promise<void>;
-  waitForLoadState?(state?: "load" | "networkidle" | "domcontentloaded", opts?: { timeout?: number }): Promise<void>;
-}
-
-export interface ExpectNavigationInput {
-  from?: string;
-  to: string | RegExp;
-  /** Exact chain length — overrides `maxRedirects` when both set. */
-  redirectCount?: number;
-  /** ≤ — chain length must not exceed this. */
-  maxRedirects?: number;
-  /** Milliseconds to wait for the terminal URL to match. Default 5000. */
-  timeoutMs?: number;
-}
-
-export interface ExpectNavigationResult {
-  status: "pass";
-  chain: string[];
-  finalUrl: string;
-}
-
-/**
- * Validate a redirect chain. Installs a `framenavigated` listener before
- * asserting the final URL matches `to`. When `from` is given we assert
- * the starting URL matches first.
- *
- * Emits a structured `failure.v1` `redirect_unexpected` error on
- * mismatch — callers should wrap in try/catch to translate to their
- * runner's fail helper.
- */
-export async function expectNavigation(
-  page: PlaywrightLikePage,
-  expectation: ExpectNavigationInput,
-): Promise<ExpectNavigationResult> {
-  const timeoutMs = expectation.timeoutMs ?? 5000;
-  const chain: string[] = [];
-  let firstUrl: string | null = null;
-
-  const onNav = (frame: { url: () => string }) => {
-    const u = frame.url();
-    if (firstUrl === null) firstUrl = u;
-    // Only append when the URL actually changes.
-    if (chain.length === 0 || chain[chain.length - 1] !== u) {
-      chain.push(u);
-    }
-  };
-  page.on("framenavigated", onNav);
-
-  try {
-    // Seed the chain with the current URL before waiting, so synchronous
-    // navigations are captured even if `framenavigated` fires before we
-    // attach.
-    const current = page.url();
-    if (current) chain.push(current);
-
-    if (page.waitForURL) {
-      try {
-        await page.waitForURL(expectation.to, { timeout: timeoutMs });
-      } catch {
-        // fall through — we'll diagnose below
-      }
-    } else {
-      // Fallback poll when waitForURL isn't available (mock pages etc).
-      const deadline = Date.now() + timeoutMs;
-      while (Date.now() < deadline) {
-        if (urlMatches(page.url(), expectation.to)) break;
-        await new Promise((r) => setTimeout(r, 25));
-      }
-    }
-
-    const finalUrl = page.url();
-    if (chain.length === 0 || chain[chain.length - 1] !== finalUrl) {
-      chain.push(finalUrl);
-    }
-
-    // Validate `from`.
-    if (expectation.from !== undefined) {
-      const first = chain[0];
-      if (first && !urlMatches(first, expectation.from)) {
-        throw new NavigationAssertionError(
-          `expectNavigation: starting URL mismatch. Expected ${expectation.from}, got ${first}`,
-          { from: expectation.from, expectedTo: String(expectation.to), actualTo: finalUrl, chain },
-        );
-      }
-    }
-
-    // Validate final URL.
-    if (!urlMatches(finalUrl, expectation.to)) {
-      throw new NavigationAssertionError(
-        `expectNavigation: terminal URL mismatch. Expected ${expectation.to}, got ${finalUrl}`,
-        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
-      );
-    }
-
-    // Validate chain length.
-    // Redirect count excludes the starting URL itself when `from` is set.
-    const chainHops = expectation.from !== undefined ? Math.max(0, chain.length - 1) : chain.length;
-    if (expectation.redirectCount !== undefined && chainHops !== expectation.redirectCount) {
-      throw new NavigationAssertionError(
-        `expectNavigation: redirect count mismatch. Expected exactly ${expectation.redirectCount}, got ${chainHops}`,
-        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
-      );
-    }
-    if (expectation.maxRedirects !== undefined && chainHops > expectation.maxRedirects) {
-      throw new NavigationAssertionError(
-        `expectNavigation: redirect chain too long. Expected ≤ ${expectation.maxRedirects}, got ${chainHops}`,
-        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
-      );
-    }
-
-    return { status: "pass", chain, finalUrl };
-  } finally {
-    if (page.off) {
-      try {
-        page.off("framenavigated", onNav);
-      } catch {
-        // ignore
-      }
-    }
-  }
-}
-
-export class NavigationAssertionError extends Error {
-  /** Shape matches `failure.v1` `redirect_unexpected` detail. */
-  detail: {
-    from: string;
-    expectedTo: string;
-    actualTo: string;
-    chain: string[];
-  };
-  kind = "redirect_unexpected" as const;
-  constructor(
-    message: string,
-    detail: { from: string; expectedTo: string; actualTo: string; chain: string[] },
-  ) {
-    super(message);
-    this.name = "NavigationAssertionError";
-    this.detail = detail;
-  }
-}
-
-function urlMatches(actual: string, expected: string | RegExp): boolean {
-  if (expected instanceof RegExp) return expected.test(actual);
-  // String match — treat as substring OR exact. "/kr" should match
-  // "http://localhost/kr" too.
-  if (actual === expected) return true;
-  try {
-    const parsed = new URL(actual);
-    if (parsed.pathname === expected) return true;
-    if (parsed.pathname + parsed.search === expected) return true;
-  } catch {
-    // fall through
-  }
-  return actual.includes(expected);
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// waitForIsland
-// ────────────────────────────────────────────────────────────────────────────
-
-export interface WaitForIslandOptions {
-  timeoutMs?: number;
-  /** "hydrated" (default) or "visible". "visible" only checks mount. */
-  state?: "hydrated" | "visible";
-  /**
-   * Override how islands expose their strategy. When this returns
-   * "none" we short-circuit and resolve immediately.
-   */
-  strategyOf?: (page: PlaywrightIslandPage, name: string) => Promise<"none" | "other" | null>;
-}
-
-export interface PlaywrightIslandPage {
-  /**
-   * Invoke a JS function in the browser context. We use
-   * `page.evaluate(fn, arg)` — same signature as Playwright's `Page`.
-   */
-  evaluate<T, A>(fn: (arg: A) => T, arg: A): Promise<T>;
-}
-
-/**
- * Wait until `[data-island="<name>"]` is hydrated.
- *
- * `hydration:none` strategy islands resolve immediately (Mandu's SSR
- * emits `data-island-strategy="none"` for those — we check that first
- * and short-circuit).
- *
- * Primary signal: `data-hydrated="true"` attribute (the one emitted by
- * `@mandujs/core/client/hydrate`). Fallback: `data-island-state="hydrated"`.
- */
-export async function waitForIsland(
-  page: PlaywrightIslandPage,
-  name: string,
-  options: WaitForIslandOptions = {},
-): Promise<void> {
-  const timeoutMs = options.timeoutMs ?? 3000;
-  const state = options.state ?? "hydrated";
-
-  // Short-circuit for hydration:none islands.
-  try {
-    const strategy = await page.evaluate(
-      (n: string) => {
-        const el = document.querySelector(`[data-island="${n}"]`);
-        if (!el) return null;
-        const s = el.getAttribute("data-island-strategy");
-        return s ?? null;
-      },
-      name,
-    );
-    if (strategy === "none") {
-      return;
-    }
-  } catch {
-    // fall through — evaluate may be unsupported in mocks
-  }
-
-  const deadline = Date.now() + timeoutMs;
-  const pollInterval = 25;
-
-  while (Date.now() < deadline) {
-    try {
-      const status = await page.evaluate(
-        (args: { name: string; state: string }) => {
-          const el = document.querySelector(`[data-island="${args.name}"]`);
-          if (!el) return { mounted: false, hydrated: false };
-          const mounted = true;
-          if (args.state === "visible") return { mounted, hydrated: mounted };
-          // primary
-          if (el.getAttribute("data-hydrated") === "true") {
-            return { mounted, hydrated: true };
-          }
-          // fallback
-          if (el.getAttribute("data-island-state") === "hydrated") {
-            return { mounted, hydrated: true };
-          }
-          return { mounted, hydrated: false };
-        },
-        { name, state },
-      );
-      if (state === "visible" && status.mounted) return;
-      if (status.hydrated) return;
-    } catch {
-      // evaluate failure — treat as not-yet-ready and retry.
-    }
-    await new Promise((r) => setTimeout(r, pollInterval));
-  }
-
-  throw new HydrationTimeoutError(
-    `waitForIsland: island "${name}" did not reach state=${state} within ${timeoutMs}ms`,
-    { island: name, waitedMs: timeoutMs },
-  );
-}
-
-export class HydrationTimeoutError extends Error {
-  kind = "hydration_timeout" as const;
-  detail: { island: string; waitedMs: number };
-  constructor(message: string, detail: { island: string; waitedMs: number }) {
-    super(message);
-    this.name = "HydrationTimeoutError";
-    this.detail = detail;
-  }
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// assertStreamBoundary
-// ────────────────────────────────────────────────────────────────────────────
-
-export interface AssertStreamBoundaryInput {
-  /** Substrings the FIRST decoded chunk must contain (all of them). */
-  shellChunkContains?: string[];
-  /** Exact count of `<!--$-->` / `<!--/$-->` pairs. */
-  boundaryCount?: number;
-  /** First-chunk size guard (bytes). */
-  firstChunkMaxSizeBytes?: number;
-  /** Any one of these strings must appear in the final chunk. */
-  tailChunkContainsAnyOf?: string[];
-}
-
-export interface AssertStreamBoundaryResult {
-  status: "pass";
-  chunks: number;
-  totalBytes: number;
-  boundaryOpenCount: number;
-  boundaryCloseCount: number;
-}
-
-/**
- * Consume a streaming Response chunk-by-chunk and validate boundary
- * markers / shell content / byte budgets.
- *
- * Throws `StreamBoundaryError` (failure.v1-shaped) on mismatch.
- */
-export async function assertStreamBoundary(
-  response: Response,
-  expectations: AssertStreamBoundaryInput,
-): Promise<AssertStreamBoundaryResult> {
-  const body = response.body;
-  if (!body) {
-    throw new StreamBoundaryError("assertStreamBoundary: response has no body", {
-      reason: "no_body",
-    });
-  }
-
-  const reader = body.getReader();
-  const decoder = new TextDecoder("utf-8", { fatal: false });
-  const chunks: string[] = [];
-  let totalBytes = 0;
-  let firstChunkBytes = 0;
-
-  try {
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (!value) continue;
-      const bytes = value.byteLength;
-      totalBytes += bytes;
-      if (chunks.length === 0) firstChunkBytes = bytes;
-      chunks.push(decoder.decode(value, { stream: true }));
-    }
-    // flush trailing decoder state
-    chunks.push(decoder.decode());
-  } finally {
-    try {
-      reader.releaseLock();
-    } catch {
-      // ignore
-    }
-  }
-
-  const shell = chunks[0] ?? "";
-  // Walk back to find the last non-empty chunk. The TextDecoder's final
-  // flush can append an empty string — that would give us a useless tail.
-  let tail = "";
-  for (let i = chunks.length - 1; i >= 0; i--) {
-    if (chunks[i] && chunks[i].length > 0) {
-      tail = chunks[i];
-      break;
-    }
-  }
-  if (!tail) tail = chunks.join("");
-  const full = chunks.join("");
-
-  // shellChunkContains
-  if (expectations.shellChunkContains) {
-    for (const needle of expectations.shellChunkContains) {
-      if (!shell.includes(needle)) {
-        throw new StreamBoundaryError(
-          `assertStreamBoundary: first chunk missing expected content "${needle}"`,
-          {
-            reason: "shell_missing_content",
-            missing: needle,
-            shellPreview: shell.slice(0, 200),
-          },
-        );
-      }
-    }
-  }
-
-  // firstChunkMaxSizeBytes
-  if (
-    expectations.firstChunkMaxSizeBytes !== undefined &&
-    firstChunkBytes > expectations.firstChunkMaxSizeBytes
-  ) {
-    throw new StreamBoundaryError(
-      `assertStreamBoundary: first chunk ${firstChunkBytes} bytes exceeds budget ${expectations.firstChunkMaxSizeBytes}`,
-      {
-        reason: "shell_over_budget",
-        firstChunkBytes,
-        budget: expectations.firstChunkMaxSizeBytes,
-      },
-    );
-  }
-
-  // boundary count — count occurrences of `<!--$-->` (open) and
-  // `<!--/$-->` (close). A "boundary" is one open+close pair, so we
-  // expect the open count to equal the close count AND equal
-  // `expectations.boundaryCount`.
-  const openCount = countOccurrences(full, "<!--$-->");
-  const closeCount = countOccurrences(full, "<!--/$-->");
-  if (
-    expectations.boundaryCount !== undefined &&
-    openCount !== expectations.boundaryCount
-  ) {
-    throw new StreamBoundaryError(
-      `assertStreamBoundary: expected ${expectations.boundaryCount} Suspense boundaries, saw ${openCount} open / ${closeCount} close`,
-      { reason: "boundary_count_mismatch", expected: expectations.boundaryCount, openCount, closeCount },
-    );
-  }
-
-  // tailChunkContainsAnyOf
-  if (expectations.tailChunkContainsAnyOf && expectations.tailChunkContainsAnyOf.length > 0) {
-    const hit = expectations.tailChunkContainsAnyOf.some((n) => tail.includes(n));
-    if (!hit) {
-      throw new StreamBoundaryError(
-        `assertStreamBoundary: tail chunk missing any of [${expectations.tailChunkContainsAnyOf.join(", ")}]`,
-        {
-          reason: "tail_missing_content",
-          candidates: expectations.tailChunkContainsAnyOf,
-          tailPreview: tail.slice(-200),
-        },
-      );
-    }
-  }
-
-  return {
-    status: "pass",
-    chunks: chunks.length,
-    totalBytes,
-    boundaryOpenCount: openCount,
-    boundaryCloseCount: closeCount,
-  };
-}
-
-export class StreamBoundaryError extends Error {
-  kind = "stream_boundary_mismatch" as const;
-  detail: Record<string, unknown>;
-  constructor(message: string, detail: Record<string, unknown>) {
-    super(message);
-    this.name = "StreamBoundaryError";
-    this.detail = detail;
-  }
-}
-
-function countOccurrences(haystack: string, needle: string): number {
-  if (!needle) return 0;
-  let count = 0;
-  let idx = 0;
-  while ((idx = haystack.indexOf(needle, idx)) !== -1) {
-    count++;
-    idx += needle.length;
-  }
-  return count;
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// expectSemantic — agent-delegated oracle
-// ────────────────────────────────────────────────────────────────────────────
-
-export interface ExpectSemanticOptions {
-  /** What to capture. Default "both". */
-  capture?: "screenshot" | "dom" | "both";
-  /** Treat the queueing as non-blocking (default). */
-  deferToAgent?: boolean;
-  /**
-   * When true, past `failed` verdicts for the same claim promote to a
-   * deterministic fail on this run. Default false. Per §C.1.5.
-   */
-  promoteVerdicts?: boolean;
-  /** Override the repo root — default `process.cwd()`. */
-  repoRoot?: string;
-  /** Override the spec path recorded in the queue entry. */
-  specPath?: string;
-  /** Override the runId recorded in the queue entry. */
-  runId?: string;
-  /** Inject a fixed timestamp — for goldens / tests. */
-  now?: () => string;
-  /**
-   * Optional DOM snapshot — tests pass it in explicitly so we don't have
-   * to stand up a headless browser. In real use this is captured via
-   * `page.content()`.
-   */
-  domSnapshot?: string;
-  /**
-   * Optional screenshot bytes — tests pass it in explicitly so we don't
-   * require Playwright at callers.
-   */
-  screenshotBytes?: Uint8Array;
-}
-
-export interface ExpectSemanticPage {
-  /** Playwright Page.content(). */
-  content?(): Promise<string>;
-  /** Playwright Page.screenshot() — returns binary. */
-  screenshot?(opts?: Record<string, unknown>): Promise<Uint8Array>;
-}
-
-export interface OracleQueueEntry {
-  assertionId: string;
-  specPath: string;
-  runId: string;
-  claim: string;
-  artifactPath: string;
-  status: "pending" | "passed" | "failed";
-  verdict?: {
-    judgedBy: "agent" | "human";
-    reason: string;
-    timestamp: string;
-  };
-  timestamp: string;
-}
-
-export interface ExpectSemanticResult {
-  status: "pass" | "fail";
-  assertionId: string;
-  /** Set when a past verdict triggered a promoted deterministic fail. */
-  promotedFromVerdict?: OracleQueueEntry["verdict"];
-  /** True when we skipped queueing (CI / DETERMINISTIC_ONLY). */
-  deferred: boolean;
-}
-
-/**
- * Queue a semantic claim for agent judgment.
- *
- * Default behaviour is **non-blocking** — we enqueue to
- * `.mandu/ate-oracle-queue.jsonl`, return `status: "pass"`, and let a
- * later agent session judge via `mandu_ate_oracle_verdict`.
- *
- * Two escape hatches:
- *   - `MANDU_ATE_DETERMINISTIC_ONLY=1` → no file writes, return immediately.
- *   - `promoteVerdicts: true` + past `failed` verdict for the same claim
- *     → throw `SemanticDivergenceError` to regress the spec.
- */
-export function expectSemantic(
-  page: ExpectSemanticPage,
-  claim: string,
-  options: ExpectSemanticOptions = {},
-): ExpectSemanticResult {
-  const repoRoot = options.repoRoot ?? process.cwd();
-  const deterministicOnly = process.env.MANDU_ATE_DETERMINISTIC_ONLY === "1";
-
-  // Compute a stable assertionId — hash of (claim + specPath). This is
-  // how promoteVerdicts matches past verdicts without relying on random
-  // ids.
-  const specPath = options.specPath ?? inferSpecPath();
-  const runId = options.runId ?? deriveRunId();
-  const assertionId = stableAssertionId(claim, specPath);
-
-  // promoteVerdicts — scan existing queue for the same assertionId.
-  if (options.promoteVerdicts) {
-    const past = findPastVerdict(repoRoot, assertionId);
-    if (past && past.status === "failed" && past.verdict) {
-      throw new SemanticDivergenceError(
-        `expectSemantic: past verdict flagged this claim as failed. claim="${claim}" reason="${past.verdict.reason}"`,
-        { claim, evidence: past.artifactPath, oraclePending: false },
-      );
-    }
-  }
-
-  if (deterministicOnly) {
-    return {
-      status: "pass",
-      assertionId,
-      deferred: true,
-    };
-  }
-
-  // Create artifact dir + write captures.
-  const nowStr = options.now ? options.now() : new Date().toISOString();
-  const artifactDir = join(repoRoot, ".mandu", "ate-oracle-queue", runId, assertionId);
-  try {
-    mkdirSync(artifactDir, { recursive: true });
-  } catch {
-    // fall through — queue is best-effort
-  }
-
-  const capture = options.capture ?? "both";
-  // Pull from explicit options first (test path), fall back to page calls.
-  const domPromise =
-    options.domSnapshot !== undefined
-      ? Promise.resolve(options.domSnapshot)
-      : capture === "screenshot" || !page.content
-        ? Promise.resolve(null)
-        : page.content().catch(() => null);
-  const screenshotPromise =
-    options.screenshotBytes !== undefined
-      ? Promise.resolve(options.screenshotBytes)
-      : capture === "dom" || !page.screenshot
-        ? Promise.resolve(null)
-        : page.screenshot().catch(() => null);
-
-  // Write captures synchronously after they resolve. expectSemantic is
-  // declared synchronous in §C.1.5 — but file writes here are also
-  // expected to not block on network, so we kick off a microtask and
-  // return. This matches the spec's "non-blocking for CI" contract.
-  void Promise.all([domPromise, screenshotPromise]).then(([dom, shot]) => {
-    try {
-      if (dom !== null && dom !== undefined) {
-        writeFileSync(join(artifactDir, "dom.html"), dom, "utf8");
-      }
-      if (shot) {
-        writeFileSync(join(artifactDir, "screenshot.png"), Buffer.from(shot));
-      }
-    } catch {
-      // swallow
-    }
-  });
-
-  // Append the queue entry immediately so agents see it before the
-  // artifacts finish writing.
-  const entry: OracleQueueEntry = {
-    assertionId,
-    specPath,
-    runId,
-    claim,
-    artifactPath: artifactDir.replace(/\\/g, "/"),
-    status: "pending",
-    timestamp: nowStr,
-  };
-  try {
-    const queuePath = join(repoRoot, ".mandu", "ate-oracle-queue.jsonl");
-    mkdirSync(dirname(queuePath), { recursive: true });
-    appendFileSync(queuePath, `${JSON.stringify(entry)}\n`, "utf8");
-  } catch {
-    // swallow — queue write is best-effort.
-  }
-
-  return {
-    status: "pass",
-    assertionId,
-    deferred: true,
-  };
-}
-
-export class SemanticDivergenceError extends Error {
-  kind = "semantic_divergence" as const;
-  detail: { claim: string; evidence?: string; oraclePending: boolean };
-  constructor(
-    message: string,
-    detail: { claim: string; evidence?: string; oraclePending: boolean },
-  ) {
-    super(message);
-    this.name = "SemanticDivergenceError";
-    this.detail = detail;
-  }
-}
-
-function stableAssertionId(claim: string, specPath: string): string {
-  // Small deterministic hash — DJB2 variant. Don't need cryptographic
-  // strength; we just need stable ids across runs.
-  const input = `${specPath}|${claim}`;
-  let hash = 5381;
-  for (let i = 0; i < input.length; i++) {
-    hash = ((hash << 5) + hash + input.charCodeAt(i)) >>> 0;
-  }
-  return `sem-${hash.toString(16).padStart(8, "0")}`;
-}
-
-function inferSpecPath(): string {
-  // Best-effort: peek at the stack for the first frame outside this file.
-  const err = new Error();
-  const stack = err.stack ?? "";
-  const lines = stack.split("\n");
-  for (const line of lines) {
-    if (line.includes("assertions.ts")) continue;
-    const match = line.match(/\(([^)]+?):(\d+):(\d+)\)/) || line.match(/at\s+([^\s]+?):(\d+):(\d+)/);
-    if (match) {
-      const file = match[1];
-      if (isAbsolute(file) && !file.includes("node_modules")) {
-        return file.replace(/\\/g, "/");
-      }
-    }
-  }
-  return "unknown.spec.ts";
-}
-
-function deriveRunId(): string {
-  return process.env.MANDU_ATE_RUN_ID ?? `run-${Date.now().toString(36)}`;
-}
-
-function findPastVerdict(repoRoot: string, assertionId: string): OracleQueueEntry | null {
-  const path = join(repoRoot, ".mandu", "ate-oracle-queue.jsonl");
-  if (!existsSync(path)) return null;
-  try {
-    const content = readFileSync(path, "utf8");
-    // Walk from the tail — most recent verdict for this id wins.
-    const lines = content.split("\n").filter(Boolean);
-    for (let i = lines.length - 1; i >= 0; i--) {
-      try {
-        const e = JSON.parse(lines[i]) as OracleQueueEntry;
-        if (e.assertionId === assertionId && e.status !== "pending") {
-          return e;
-        }
-      } catch {
-        // skip corrupt line
-      }
-    }
-  } catch {
-    // swallow
-  }
-  return null;
-}
+/**
+ * Phase C.1 — Semantic Primitives (@mandujs/core/testing barrel).
+ *
+ * Mandu-specific assertion primitives that the generic Playwright / bun:test
+ * vocabulary cannot express cleanly:
+ *
+ *   - `expectContract`      — Zod shape validation with strict/loose/drift
+ *     modes and path-based `ignorePaths`. Replaces `JSON.stringify`
+ *     comparisons.
+ *   - `expectNavigation`    — redirect-chain capture for Playwright pages.
+ *   - `waitForIsland`       — polls `data-island="<name>"`'s
+ *     `data-hydrated`/`data-island-state` attribute. Short-circuits for
+ *     `hydration:none` strategies.
+ *   - `assertStreamBoundary`— consumes a streaming SSR response and counts
+ *     `<!--$-->` / `<!--/$-->` boundary markers. Validates shell chunk
+ *     byte budgets and tail chunk content.
+ *   - `expectSemantic`      — agent-delegated oracle. Writes an entry to
+ *     `.mandu/ate-oracle-queue.jsonl` for an agent to judge later. CI is
+ *     never blocked (`MANDU_ATE_DETERMINISTIC_ONLY=1` skips queueing).
+ *     `promoteVerdicts: true` option lets a previously-failed verdict
+ *     become a deterministic fail on re-run.
+ *
+ * Spec: docs/ate/phase-c-spec.md §C.1.
+ *
+ * These primitives live in `@mandujs/core/testing` (not `@mandujs/ate`) so
+ * they are usable in any Mandu project test file, with or without the ATE
+ * MCP server.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+} from "node:fs";
+import { join, dirname, isAbsolute } from "node:path";
+
+// ────────────────────────────────────────────────────────────────────────────
+// expectContract
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal structural type of a Zod schema. We don't import `zod` here —
+ * the caller provides the schema and we only call `safeParse`. This keeps
+ * `@mandujs/core/testing` free of a zod peer dep for consumers who don't
+ * use it.
+ */
+/**
+ * Structural type matching both real `zod` schemas and hand-rolled
+ * fakes. We intentionally widen the `error.issues` shape to `unknown[]`
+ * — the primitive normalizes each issue internally so the call sites
+ * don't have to worry about Zod version drift.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ZodLikeSchema<T = unknown> {
+  safeParse: (input: unknown) => {
+    success: boolean;
+    data?: T;
+    // Intentionally loose — see note above.
+    error?: { issues: readonly unknown[] } | undefined;
+  };
+}
+
+interface NormalizedIssue {
+  path: Array<string | number>;
+  message: string;
+  code?: string;
+  expected?: string;
+  received?: string;
+}
+
+function normalizeIssue(raw: unknown): NormalizedIssue {
+  const obj = (raw ?? {}) as Record<string, unknown>;
+  const pathRaw = obj.path;
+  const path: Array<string | number> = Array.isArray(pathRaw)
+    ? (pathRaw.filter((p) => typeof p === "string" || typeof p === "number") as Array<
+        string | number
+      >)
+    : [];
+  return {
+    path,
+    message: typeof obj.message === "string" ? obj.message : "",
+    ...(typeof obj.code === "string" ? { code: obj.code } : {}),
+    ...(typeof obj.expected === "string" ? { expected: obj.expected } : {}),
+    ...(typeof obj.received === "string" ? { received: obj.received } : {}),
+  };
+}
+
+export type ContractMode = "strict" | "loose" | "drift-tolerant";
+
+export interface ContractViolation {
+  path: string;
+  expected: string;
+  actual: string;
+  severity: "critical" | "warning";
+}
+
+export interface ExpectContractOptions {
+  mode?: ContractMode;
+  /**
+   * Dot-notation paths to ignore. Use `.createdAt`, `.items[0].updatedAt`,
+   * or `.user.id`. Matching is prefix-aware — `.user` ignores every
+   * descendant field.
+   */
+  ignorePaths?: string[];
+}
+
+export interface ExpectContractResult {
+  status: "pass" | "fail";
+  violations: ContractViolation[];
+}
+
+/**
+ * Validate `actual` against a Zod schema and surface structured
+ * violations. Throws when `status === "fail"` unless `mode` is
+ * `drift-tolerant`, which only records warnings.
+ *
+ * @example
+ * ```ts
+ * expectContract(await res.json(), SignupResponseSchema, {
+ *   mode: "loose",
+ *   ignorePaths: [".createdAt", ".user.id"],
+ * });
+ * ```
+ */
+export function expectContract<T>(
+  actual: unknown,
+  schema: ZodLikeSchema<T>,
+  options: ExpectContractOptions = {},
+): ExpectContractResult {
+  const mode: ContractMode = options.mode ?? "strict";
+  const ignore = options.ignorePaths ?? [];
+
+  const result = schema.safeParse(actual);
+
+  if (result.success) {
+    // Strict mode: walk `actual` looking for keys not mentioned anywhere
+    // in the schema. We can't introspect a Zod schema structurally without
+    // the runtime — instead we round-trip through `safeParse`'s `data`
+    // which a default Zod schema strips unknown keys from (unless the
+    // schema uses `.passthrough()` / `.strict()`). If `data` shape differs
+    // from `actual` in strict mode, we flag the extras.
+    if (mode === "strict" && result.data !== undefined) {
+      const extras = findExtraKeys("", actual, result.data, ignore);
+      if (extras.length > 0) {
+        const violations: ContractViolation[] = extras.map((e) => ({
+          path: e,
+          expected: "(not in schema)",
+          actual: "extra key present",
+          severity: "critical",
+        }));
+        throwViolations(violations, "strict");
+        return { status: "fail", violations };
+      }
+    }
+    return { status: "pass", violations: [] };
+  }
+
+  // safeParse failed — translate Zod issues to our violation shape.
+  const rawIssues = result.error?.issues ?? [];
+  const violations: ContractViolation[] = [];
+  for (const raw of rawIssues) {
+    const issue = normalizeIssue(raw);
+    const path = pathToString(issue.path);
+    if (isIgnored(path, ignore)) continue;
+
+    // loose mode forgives extra-key errors (unrecognized keys) but keeps
+    // `missing_required` + format violations.
+    if (mode === "loose" && isExtraKeyIssue(issue)) continue;
+
+    const severity: "critical" | "warning" =
+      mode === "drift-tolerant" ? "warning" : "critical";
+    violations.push({
+      path,
+      expected: issue.expected ?? issue.message,
+      actual: issue.received ?? describeActual(actual, issue.path),
+      severity,
+    });
+  }
+
+  if (violations.length === 0) {
+    return { status: "pass", violations: [] };
+  }
+
+  if (mode === "drift-tolerant") {
+    // Warnings collected; no throw. Caller may log via
+    // `mandu_ate_remember({ kind: "contract_drift" })`.
+    return { status: "fail", violations };
+  }
+
+  throwViolations(violations, mode);
+  return { status: "fail", violations };
+}
+
+function isExtraKeyIssue(issue: { code?: string; message?: string }): boolean {
+  if (issue.code === "unrecognized_keys") return true;
+  return /unrecognized key/i.test(issue.message ?? "");
+}
+
+function throwViolations(violations: ContractViolation[], mode: ContractMode): never {
+  const summary = violations
+    .slice(0, 5)
+    .map((v) => `  - ${v.path}: expected ${v.expected}, got ${v.actual}`)
+    .join("\n");
+  const more = violations.length > 5 ? `\n  ... +${violations.length - 5} more` : "";
+  throw new ContractAssertionError(
+    `expectContract (${mode}) failed with ${violations.length} violation(s):\n${summary}${more}`,
+    violations,
+  );
+}
+
+export class ContractAssertionError extends Error {
+  violations: ContractViolation[];
+  constructor(message: string, violations: ContractViolation[]) {
+    super(message);
+    this.name = "ContractAssertionError";
+    this.violations = violations;
+  }
+}
+
+function pathToString(path: Array<string | number>): string {
+  let out = "";
+  for (const seg of path) {
+    if (typeof seg === "number") out += `[${seg}]`;
+    else out += `.${seg}`;
+  }
+  return out;
+}
+
+function isIgnored(path: string, ignore: string[]): boolean {
+  for (const ign of ignore) {
+    if (path === ign || path.startsWith(ign + ".") || path.startsWith(ign + "[")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function describeActual(actual: unknown, path: Array<string | number>): string {
+  let cursor: unknown = actual;
+  for (const seg of path) {
+    if (cursor === null || cursor === undefined) return "undefined";
+    cursor = (cursor as Record<string | number, unknown>)[seg as string];
+  }
+  if (cursor === null) return "null";
+  if (cursor === undefined) return "undefined";
+  if (typeof cursor === "object") return JSON.stringify(cursor).slice(0, 60);
+  return JSON.stringify(cursor);
+}
+
+/**
+ * Find keys present in `actual` that are NOT present in `parsed` — extra
+ * keys Zod stripped during safeParse. Only used in strict mode.
+ */
+function findExtraKeys(
+  prefix: string,
+  actual: unknown,
+  parsed: unknown,
+  ignore: string[],
+): string[] {
+  const out: string[] = [];
+  if (!actual || typeof actual !== "object" || Array.isArray(actual)) return out;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return out;
+
+  const actualKeys = Object.keys(actual as Record<string, unknown>);
+  const parsedKeys = new Set(Object.keys(parsed as Record<string, unknown>));
+
+  for (const key of actualKeys) {
+    const path = `${prefix}.${key}`;
+    if (isIgnored(path, ignore)) continue;
+    if (!parsedKeys.has(key)) {
+      out.push(path);
+      continue;
+    }
+    const aVal = (actual as Record<string, unknown>)[key];
+    const pVal = (parsed as Record<string, unknown>)[key];
+    if (
+      aVal !== null &&
+      typeof aVal === "object" &&
+      !Array.isArray(aVal) &&
+      pVal !== null &&
+      typeof pVal === "object" &&
+      !Array.isArray(pVal)
+    ) {
+      out.push(...findExtraKeys(path, aVal, pVal, ignore));
+    }
+  }
+
+  return out;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// expectNavigation
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal Playwright Page shape — we only touch the bits we need so
+ * consumers can use `@playwright/test`'s `Page` without creating an
+ * import coupling.
+ */
+export interface PlaywrightLikePage {
+  url(): string;
+  on(event: "framenavigated", listener: (frame: { url: () => string }) => void): void;
+  off?(event: "framenavigated", listener: (frame: { url: () => string }) => void): void;
+  waitForURL?(url: string | RegExp, opts?: { timeout?: number }): Promise<void>;
+  waitForLoadState?(state?: "load" | "networkidle" | "domcontentloaded", opts?: { timeout?: number }): Promise<void>;
+}
+
+export interface ExpectNavigationInput {
+  from?: string;
+  to: string | RegExp;
+  /** Exact chain length — overrides `maxRedirects` when both set. */
+  redirectCount?: number;
+  /** ≤ — chain length must not exceed this. */
+  maxRedirects?: number;
+  /** Milliseconds to wait for the terminal URL to match. Default 5000. */
+  timeoutMs?: number;
+}
+
+export interface ExpectNavigationResult {
+  status: "pass";
+  chain: string[];
+  finalUrl: string;
+}
+
+/**
+ * Validate a redirect chain. Installs a `framenavigated` listener before
+ * asserting the final URL matches `to`. When `from` is given we assert
+ * the starting URL matches first.
+ *
+ * Emits a structured `failure.v1` `redirect_unexpected` error on
+ * mismatch — callers should wrap in try/catch to translate to their
+ * runner's fail helper.
+ */
+export async function expectNavigation(
+  page: PlaywrightLikePage,
+  expectation: ExpectNavigationInput,
+): Promise<ExpectNavigationResult> {
+  const timeoutMs = expectation.timeoutMs ?? 5000;
+  const chain: string[] = [];
+  let firstUrl: string | null = null;
+
+  const onNav = (frame: { url: () => string }) => {
+    const u = frame.url();
+    if (firstUrl === null) firstUrl = u;
+    // Only append when the URL actually changes.
+    if (chain.length === 0 || chain[chain.length - 1] !== u) {
+      chain.push(u);
+    }
+  };
+  page.on("framenavigated", onNav);
+
+  try {
+    // Seed the chain with the current URL before waiting, so synchronous
+    // navigations are captured even if `framenavigated` fires before we
+    // attach.
+    const current = page.url();
+    if (current) chain.push(current);
+
+    if (page.waitForURL) {
+      try {
+        await page.waitForURL(expectation.to, { timeout: timeoutMs });
+      } catch {
+        // fall through — we'll diagnose below
+      }
+    } else {
+      // Fallback poll when waitForURL isn't available (mock pages etc).
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (urlMatches(page.url(), expectation.to)) break;
+        await new Promise((r) => setTimeout(r, 25));
+      }
+    }
+
+    const finalUrl = page.url();
+    if (chain.length === 0 || chain[chain.length - 1] !== finalUrl) {
+      chain.push(finalUrl);
+    }
+
+    // Validate `from`.
+    if (expectation.from !== undefined) {
+      const first = chain[0];
+      if (first && !urlMatches(first, expectation.from)) {
+        throw new NavigationAssertionError(
+          `expectNavigation: starting URL mismatch. Expected ${expectation.from}, got ${first}`,
+          { from: expectation.from, expectedTo: String(expectation.to), actualTo: finalUrl, chain },
+        );
+      }
+    }
+
+    // Validate final URL.
+    if (!urlMatches(finalUrl, expectation.to)) {
+      throw new NavigationAssertionError(
+        `expectNavigation: terminal URL mismatch. Expected ${expectation.to}, got ${finalUrl}`,
+        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
+      );
+    }
+
+    // Validate chain length.
+    // Redirect count excludes the starting URL itself when `from` is set.
+    const chainHops = expectation.from !== undefined ? Math.max(0, chain.length - 1) : chain.length;
+    if (expectation.redirectCount !== undefined && chainHops !== expectation.redirectCount) {
+      throw new NavigationAssertionError(
+        `expectNavigation: redirect count mismatch. Expected exactly ${expectation.redirectCount}, got ${chainHops}`,
+        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
+      );
+    }
+    if (expectation.maxRedirects !== undefined && chainHops > expectation.maxRedirects) {
+      throw new NavigationAssertionError(
+        `expectNavigation: redirect chain too long. Expected ≤ ${expectation.maxRedirects}, got ${chainHops}`,
+        { from: expectation.from ?? "", expectedTo: String(expectation.to), actualTo: finalUrl, chain },
+      );
+    }
+
+    return { status: "pass", chain, finalUrl };
+  } finally {
+    if (page.off) {
+      try {
+        page.off("framenavigated", onNav);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+export class NavigationAssertionError extends Error {
+  /** Shape matches `failure.v1` `redirect_unexpected` detail. */
+  detail: {
+    from: string;
+    expectedTo: string;
+    actualTo: string;
+    chain: string[];
+  };
+  kind = "redirect_unexpected" as const;
+  constructor(
+    message: string,
+    detail: { from: string; expectedTo: string; actualTo: string; chain: string[] },
+  ) {
+    super(message);
+    this.name = "NavigationAssertionError";
+    this.detail = detail;
+  }
+}
+
+function urlMatches(actual: string, expected: string | RegExp): boolean {
+  if (expected instanceof RegExp) return expected.test(actual);
+  // String match — treat as substring OR exact. "/kr" should match
+  // "http://localhost/kr" too.
+  if (actual === expected) return true;
+  try {
+    const parsed = new URL(actual);
+    if (parsed.pathname === expected) return true;
+    if (parsed.pathname + parsed.search === expected) return true;
+  } catch {
+    // fall through
+  }
+  return actual.includes(expected);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// waitForIsland
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface WaitForIslandOptions {
+  timeoutMs?: number;
+  /** "hydrated" (default) or "visible". "visible" only checks mount. */
+  state?: "hydrated" | "visible";
+  /**
+   * Override how islands expose their strategy. When this returns
+   * "none" we short-circuit and resolve immediately.
+   */
+  strategyOf?: (page: PlaywrightIslandPage, name: string) => Promise<"none" | "other" | null>;
+}
+
+export interface PlaywrightIslandPage {
+  /**
+   * Invoke a JS function in the browser context. We use
+   * `page.evaluate(fn, arg)` — same signature as Playwright's `Page`.
+   */
+  evaluate<T, A>(fn: (arg: A) => T, arg: A): Promise<T>;
+}
+
+/**
+ * Wait until `[data-island="<name>"]` is hydrated.
+ *
+ * `hydration:none` strategy islands resolve immediately (Mandu's SSR
+ * emits `data-island-strategy="none"` for those — we check that first
+ * and short-circuit).
+ *
+ * Primary signal: `data-hydrated="true"` attribute (the one emitted by
+ * `@mandujs/core/client/hydrate`). Fallback: `data-island-state="hydrated"`.
+ */
+export async function waitForIsland(
+  page: PlaywrightIslandPage,
+  name: string,
+  options: WaitForIslandOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const state = options.state ?? "hydrated";
+
+  // Short-circuit for hydration:none islands.
+  try {
+    const strategy = await page.evaluate(
+      (n: string) => {
+        const el = document.querySelector(`[data-island="${n}"]`);
+        if (!el) return null;
+        const s = el.getAttribute("data-island-strategy");
+        return s ?? null;
+      },
+      name,
+    );
+    if (strategy === "none") {
+      return;
+    }
+  } catch {
+    // fall through — evaluate may be unsupported in mocks
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  const pollInterval = 25;
+
+  while (Date.now() < deadline) {
+    try {
+      const status = await page.evaluate(
+        (args: { name: string; state: string }) => {
+          const el = document.querySelector(`[data-island="${args.name}"]`);
+          if (!el) return { mounted: false, hydrated: false };
+          const mounted = true;
+          if (args.state === "visible") return { mounted, hydrated: mounted };
+          // primary
+          if (el.getAttribute("data-hydrated") === "true") {
+            return { mounted, hydrated: true };
+          }
+          // fallback
+          if (el.getAttribute("data-island-state") === "hydrated") {
+            return { mounted, hydrated: true };
+          }
+          return { mounted, hydrated: false };
+        },
+        { name, state },
+      );
+      if (state === "visible" && status.mounted) return;
+      if (status.hydrated) return;
+    } catch {
+      // evaluate failure — treat as not-yet-ready and retry.
+    }
+    await new Promise((r) => setTimeout(r, pollInterval));
+  }
+
+  throw new HydrationTimeoutError(
+    `waitForIsland: island "${name}" did not reach state=${state} within ${timeoutMs}ms`,
+    { island: name, waitedMs: timeoutMs },
+  );
+}
+
+export class HydrationTimeoutError extends Error {
+  kind = "hydration_timeout" as const;
+  detail: { island: string; waitedMs: number };
+  constructor(message: string, detail: { island: string; waitedMs: number }) {
+    super(message);
+    this.name = "HydrationTimeoutError";
+    this.detail = detail;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// assertStreamBoundary
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface AssertStreamBoundaryInput {
+  /** Substrings the FIRST decoded chunk must contain (all of them). */
+  shellChunkContains?: string[];
+  /** Exact count of `<!--$-->` / `<!--/$-->` pairs. */
+  boundaryCount?: number;
+  /** First-chunk size guard (bytes). */
+  firstChunkMaxSizeBytes?: number;
+  /** Any one of these strings must appear in the final chunk. */
+  tailChunkContainsAnyOf?: string[];
+}
+
+export interface AssertStreamBoundaryResult {
+  status: "pass";
+  chunks: number;
+  totalBytes: number;
+  boundaryOpenCount: number;
+  boundaryCloseCount: number;
+}
+
+/**
+ * Consume a streaming Response chunk-by-chunk and validate boundary
+ * markers / shell content / byte budgets.
+ *
+ * Throws `StreamBoundaryError` (failure.v1-shaped) on mismatch.
+ */
+export async function assertStreamBoundary(
+  response: Response,
+  expectations: AssertStreamBoundaryInput,
+): Promise<AssertStreamBoundaryResult> {
+  const body = response.body;
+  if (!body) {
+    throw new StreamBoundaryError("assertStreamBoundary: response has no body", {
+      reason: "no_body",
+    });
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  const chunks: string[] = [];
+  let totalBytes = 0;
+  let firstChunkBytes = 0;
+
+  try {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      const bytes = value.byteLength;
+      totalBytes += bytes;
+      if (chunks.length === 0) firstChunkBytes = bytes;
+      chunks.push(decoder.decode(value, { stream: true }));
+    }
+    // flush trailing decoder state
+    chunks.push(decoder.decode());
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // ignore
+    }
+  }
+
+  const shell = chunks[0] ?? "";
+  // Walk back to find the last non-empty chunk. The TextDecoder's final
+  // flush can append an empty string — that would give us a useless tail.
+  let tail = "";
+  for (let i = chunks.length - 1; i >= 0; i--) {
+    if (chunks[i] && chunks[i].length > 0) {
+      tail = chunks[i];
+      break;
+    }
+  }
+  if (!tail) tail = chunks.join("");
+  const full = chunks.join("");
+
+  // shellChunkContains
+  if (expectations.shellChunkContains) {
+    for (const needle of expectations.shellChunkContains) {
+      if (!shell.includes(needle)) {
+        throw new StreamBoundaryError(
+          `assertStreamBoundary: first chunk missing expected content "${needle}"`,
+          {
+            reason: "shell_missing_content",
+            missing: needle,
+            shellPreview: shell.slice(0, 200),
+          },
+        );
+      }
+    }
+  }
+
+  // firstChunkMaxSizeBytes
+  if (
+    expectations.firstChunkMaxSizeBytes !== undefined &&
+    firstChunkBytes > expectations.firstChunkMaxSizeBytes
+  ) {
+    throw new StreamBoundaryError(
+      `assertStreamBoundary: first chunk ${firstChunkBytes} bytes exceeds budget ${expectations.firstChunkMaxSizeBytes}`,
+      {
+        reason: "shell_over_budget",
+        firstChunkBytes,
+        budget: expectations.firstChunkMaxSizeBytes,
+      },
+    );
+  }
+
+  // boundary count — count occurrences of `<!--$-->` (open) and
+  // `<!--/$-->` (close). A "boundary" is one open+close pair, so we
+  // expect the open count to equal the close count AND equal
+  // `expectations.boundaryCount`.
+  const openCount = countOccurrences(full, "<!--$-->");
+  const closeCount = countOccurrences(full, "<!--/$-->");
+  if (
+    expectations.boundaryCount !== undefined &&
+    openCount !== expectations.boundaryCount
+  ) {
+    throw new StreamBoundaryError(
+      `assertStreamBoundary: expected ${expectations.boundaryCount} Suspense boundaries, saw ${openCount} open / ${closeCount} close`,
+      { reason: "boundary_count_mismatch", expected: expectations.boundaryCount, openCount, closeCount },
+    );
+  }
+
+  // tailChunkContainsAnyOf
+  if (expectations.tailChunkContainsAnyOf && expectations.tailChunkContainsAnyOf.length > 0) {
+    const hit = expectations.tailChunkContainsAnyOf.some((n) => tail.includes(n));
+    if (!hit) {
+      throw new StreamBoundaryError(
+        `assertStreamBoundary: tail chunk missing any of [${expectations.tailChunkContainsAnyOf.join(", ")}]`,
+        {
+          reason: "tail_missing_content",
+          candidates: expectations.tailChunkContainsAnyOf,
+          tailPreview: tail.slice(-200),
+        },
+      );
+    }
+  }
+
+  return {
+    status: "pass",
+    chunks: chunks.length,
+    totalBytes,
+    boundaryOpenCount: openCount,
+    boundaryCloseCount: closeCount,
+  };
+}
+
+export class StreamBoundaryError extends Error {
+  kind = "stream_boundary_mismatch" as const;
+  detail: Record<string, unknown>;
+  constructor(message: string, detail: Record<string, unknown>) {
+    super(message);
+    this.name = "StreamBoundaryError";
+    this.detail = detail;
+  }
+}
+
+function countOccurrences(haystack: string, needle: string): number {
+  if (!needle) return 0;
+  let count = 0;
+  let idx = 0;
+  while ((idx = haystack.indexOf(needle, idx)) !== -1) {
+    count++;
+    idx += needle.length;
+  }
+  return count;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// expectSemantic — agent-delegated oracle
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface ExpectSemanticOptions {
+  /** What to capture. Default "both". */
+  capture?: "screenshot" | "dom" | "both";
+  /** Treat the queueing as non-blocking (default). */
+  deferToAgent?: boolean;
+  /**
+   * When true, past `failed` verdicts for the same claim promote to a
+   * deterministic fail on this run. Default false. Per §C.1.5.
+   */
+  promoteVerdicts?: boolean;
+  /** Override the repo root — default `process.cwd()`. */
+  repoRoot?: string;
+  /** Override the spec path recorded in the queue entry. */
+  specPath?: string;
+  /** Override the runId recorded in the queue entry. */
+  runId?: string;
+  /** Inject a fixed timestamp — for goldens / tests. */
+  now?: () => string;
+  /**
+   * Optional DOM snapshot — tests pass it in explicitly so we don't have
+   * to stand up a headless browser. In real use this is captured via
+   * `page.content()`.
+   */
+  domSnapshot?: string;
+  /**
+   * Optional screenshot bytes — tests pass it in explicitly so we don't
+   * require Playwright at callers.
+   */
+  screenshotBytes?: Uint8Array;
+}
+
+export interface ExpectSemanticPage {
+  /** Playwright Page.content(). */
+  content?(): Promise<string>;
+  /** Playwright Page.screenshot() — returns binary. */
+  screenshot?(opts?: Record<string, unknown>): Promise<Uint8Array>;
+}
+
+export interface OracleQueueEntry {
+  assertionId: string;
+  specPath: string;
+  runId: string;
+  claim: string;
+  artifactPath: string;
+  status: "pending" | "passed" | "failed";
+  verdict?: {
+    judgedBy: "agent" | "human";
+    reason: string;
+    timestamp: string;
+  };
+  timestamp: string;
+}
+
+export interface ExpectSemanticResult {
+  status: "pass" | "fail";
+  assertionId: string;
+  /** Set when a past verdict triggered a promoted deterministic fail. */
+  promotedFromVerdict?: OracleQueueEntry["verdict"];
+  /** True when we skipped queueing (CI / DETERMINISTIC_ONLY). */
+  deferred: boolean;
+}
+
+/**
+ * Queue a semantic claim for agent judgment.
+ *
+ * Default behaviour is **non-blocking** — we enqueue to
+ * `.mandu/ate-oracle-queue.jsonl`, return `status: "pass"`, and let a
+ * later agent session judge via `mandu_ate_oracle_verdict`.
+ *
+ * Two escape hatches:
+ *   - `MANDU_ATE_DETERMINISTIC_ONLY=1` → no file writes, return immediately.
+ *   - `promoteVerdicts: true` + past `failed` verdict for the same claim
+ *     → throw `SemanticDivergenceError` to regress the spec.
+ */
+export function expectSemantic(
+  page: ExpectSemanticPage,
+  claim: string,
+  options: ExpectSemanticOptions = {},
+): ExpectSemanticResult {
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const deterministicOnly = process.env.MANDU_ATE_DETERMINISTIC_ONLY === "1";
+
+  // Compute a stable assertionId — hash of (claim + specPath). This is
+  // how promoteVerdicts matches past verdicts without relying on random
+  // ids.
+  const specPath = options.specPath ?? inferSpecPath();
+  const runId = options.runId ?? deriveRunId();
+  const assertionId = stableAssertionId(claim, specPath);
+
+  // promoteVerdicts — scan existing queue for the same assertionId.
+  if (options.promoteVerdicts) {
+    const past = findPastVerdict(repoRoot, assertionId);
+    if (past && past.status === "failed" && past.verdict) {
+      throw new SemanticDivergenceError(
+        `expectSemantic: past verdict flagged this claim as failed. claim="${claim}" reason="${past.verdict.reason}"`,
+        { claim, evidence: past.artifactPath, oraclePending: false },
+      );
+    }
+  }
+
+  if (deterministicOnly) {
+    return {
+      status: "pass",
+      assertionId,
+      deferred: true,
+    };
+  }
+
+  // Create artifact dir + write captures.
+  const nowStr = options.now ? options.now() : new Date().toISOString();
+  const artifactDir = join(repoRoot, ".mandu", "ate-oracle-queue", runId, assertionId);
+  try {
+    mkdirSync(artifactDir, { recursive: true });
+  } catch {
+    // fall through — queue is best-effort
+  }
+
+  const capture = options.capture ?? "both";
+  // Pull from explicit options first (test path), fall back to page calls.
+  const domPromise =
+    options.domSnapshot !== undefined
+      ? Promise.resolve(options.domSnapshot)
+      : capture === "screenshot" || !page.content
+        ? Promise.resolve(null)
+        : page.content().catch(() => null);
+  const screenshotPromise =
+    options.screenshotBytes !== undefined
+      ? Promise.resolve(options.screenshotBytes)
+      : capture === "dom" || !page.screenshot
+        ? Promise.resolve(null)
+        : page.screenshot().catch(() => null);
+
+  // Write captures synchronously after they resolve. expectSemantic is
+  // declared synchronous in §C.1.5 — but file writes here are also
+  // expected to not block on network, so we kick off a microtask and
+  // return. This matches the spec's "non-blocking for CI" contract.
+  void Promise.all([domPromise, screenshotPromise]).then(([dom, shot]) => {
+    try {
+      if (dom !== null && dom !== undefined) {
+        writeFileSync(join(artifactDir, "dom.html"), dom, "utf8");
+      }
+      if (shot) {
+        writeFileSync(join(artifactDir, "screenshot.png"), Buffer.from(shot));
+      }
+    } catch {
+      // swallow
+    }
+  });
+
+  // Append the queue entry immediately so agents see it before the
+  // artifacts finish writing.
+  const entry: OracleQueueEntry = {
+    assertionId,
+    specPath,
+    runId,
+    claim,
+    artifactPath: artifactDir.replace(/\\/g, "/"),
+    status: "pending",
+    timestamp: nowStr,
+  };
+  try {
+    const queuePath = join(repoRoot, ".mandu", "ate-oracle-queue.jsonl");
+    mkdirSync(dirname(queuePath), { recursive: true });
+    appendFileSync(queuePath, `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // swallow — queue write is best-effort.
+  }
+
+  return {
+    status: "pass",
+    assertionId,
+    deferred: true,
+  };
+}
+
+export class SemanticDivergenceError extends Error {
+  kind = "semantic_divergence" as const;
+  detail: { claim: string; evidence?: string; oraclePending: boolean };
+  constructor(
+    message: string,
+    detail: { claim: string; evidence?: string; oraclePending: boolean },
+  ) {
+    super(message);
+    this.name = "SemanticDivergenceError";
+    this.detail = detail;
+  }
+}
+
+function stableAssertionId(claim: string, specPath: string): string {
+  // Small deterministic hash — DJB2 variant. Don't need cryptographic
+  // strength; we just need stable ids across runs.
+  const input = `${specPath}|${claim}`;
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) + hash + input.charCodeAt(i)) >>> 0;
+  }
+  return `sem-${hash.toString(16).padStart(8, "0")}`;
+}
+
+function inferSpecPath(): string {
+  // Best-effort: peek at the stack for the first frame outside this file.
+  const err = new Error();
+  const stack = err.stack ?? "";
+  const lines = stack.split("\n");
+  for (const line of lines) {
+    if (line.includes("assertions.ts")) continue;
+    const match = line.match(/\(([^)]+?):(\d+):(\d+)\)/) || line.match(/at\s+([^\s]+?):(\d+):(\d+)/);
+    if (match) {
+      const file = match[1];
+      if (isAbsolute(file) && !file.includes("node_modules")) {
+        return file.replace(/\\/g, "/");
+      }
+    }
+  }
+  return "unknown.spec.ts";
+}
+
+function deriveRunId(): string {
+  return process.env.MANDU_ATE_RUN_ID ?? `run-${Date.now().toString(36)}`;
+}
+
+function findPastVerdict(repoRoot: string, assertionId: string): OracleQueueEntry | null {
+  const path = join(repoRoot, ".mandu", "ate-oracle-queue.jsonl");
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf8");
+    // Walk from the tail — most recent verdict for this id wins.
+    const lines = content.split("\n").filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const e = JSON.parse(lines[i]) as OracleQueueEntry;
+        if (e.assertionId === assertionId && e.status !== "pending") {
+          return e;
+        }
+      } catch {
+        // skip corrupt line
+      }
+    }
+  } catch {
+    // swallow
+  }
+  return null;
+}