@oneie/claude 0.7.0 → 0.9.0

package/scripts/speed-waterfall-check.sh

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+# speed-waterfall-check.sh — proves a serial-hop waterfall was actually
+# collapsed into a fan-out, structurally, on both surfaces this checker will
+# eventually cover:
+#
+#   --chat    (C9, THIS cycle) api/chat.ts's pre-flight ladder: three
+#             independent D1/crypto reads (loadPublishedPage, getThread,
+#             visitorHash) that used to run one `await` at a time before the
+#             `...P` parallel block even opened. Ships in THIS cycle.
+#   --tenant  (C8) the tenant page round trip. Checks THREE files together —
+#             u/[slug]/index.astro, u/[slug]/p/[pageSlug].astro and the loader
+#             module lib/tenant/page-data.ts they both delegate their data wave
+#             to. Checking the frontmatters ALONE would be fooled by a
+#             "collapse" that merely relocated the round trips one level down
+#             into a helper, so each of the three carries its own await-line
+#             ceiling (5 / 5 / 4) as well as a required fan-out shape. That
+#             pair — required join + per-file ceiling — is what makes the
+#             ceiling TRANSITIVE: 3 dependency levels per route, counted across
+#             frontmatter + loader, leaf helpers one node each.
+#
+#             The two declared exceptions are visible in the numbers: the
+#             [pageSlug] draft-preview authz gate (a security gate; asserted to
+#             be EXACTLY ONE authorizeWorkspace call, never zero, never two) and
+#             index.astro's invite-token early-return branch.
+#   --check-gate  SELF-TEST: plant the pre-fix serial shape in a scratch file,
+#             prove --chat's structural check flags it RED, then prove the
+#             real working tree is GREEN. Same discipline as
+#             speed-cache-check.sh and speed-check.mjs --check-gate: a checker
+#             that has never been observed failing is not evidence of anything.
+#
+# WHY STRUCTURAL, NOT A LIVE TIMING DIFF: chat.ts's pre-flight reads D1 and
+# crypto.subtle inside a live Worker request — there is no cheap way to
+# dependency-inject fake latency into 1,200+ lines of route handler from a
+# shell script, and a live prod A/B (the C6 method) needs a funded turn +
+# billing side-effects, which this checker must not trigner on every run.
+# So this proves the SHAPE that makes concurrency possible (three `P` promises
+# created before any of them is awaited, joined with Promise.all/await),
+# and the real timing readback lives in text/speed-results.md (W4, manual).
+#
+# Usage:
+#   speed-waterfall-check.sh --chat          structural pass/fail, exit 0/1
+#   speed-waterfall-check.sh --tenant         NOT YET SHIPPED — exits 2
+#   speed-waterfall-check.sh --check-gate    self-test, exits 0/1
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CHAT_TS="one.ie/web/src/pages/api/chat.ts"
+
+cd "$ROOT"
+
+check_chat() {
+	local file="$1"
+	if [ ! -f "$file" ]; then
+		echo "[speed-waterfall-check] missing $file" >&2
+		return 2
+	fi
+	# GREEN shape: the three independent reads are captured as promises
+	# (never `await`-ed at their own call site) and joined explicitly.
+	local has_published_p has_thread_p has_visitor_p has_join
+	has_published_p=$(grep -c 'const publishedPageP: Promise<PublishedPage | null> =' "$file" || true)
+	has_thread_p=$(grep -c 'const claimedThreadP: Promise<ClaimedThread | null> =' "$file" || true)
+	has_visitor_p=$(grep -c 'const visitorHashP: Promise<string | null> =' "$file" || true)
+	has_join=$(grep -c 'Promise.all(\[claimedThreadP, visitorHashP\])' "$file" || true)
+	# RED shape: any of the three still awaited serially, inline, at its own
+	# call site — the pattern this cycle removed.
+	local red_published red_thread red_visitor
+	red_published=$(grep -cE '\?\s*await loadPublishedPage\(' "$file" || true)
+	red_thread=$(grep -cE 'const t = await getThread\(' "$file" || true)
+	red_visitor=$(grep -cE 'attestedVisitorHash \?\? \(convoCookieId \? await visitorHash\(' "$file" || true)
+
+	if [ "$has_published_p" -ge 1 ] && [ "$has_thread_p" -ge 1 ] && [ "$has_visitor_p" -ge 1 ] \
+		&& [ "$has_join" -ge 1 ] \
+		&& [ "$red_published" -eq 0 ] && [ "$red_thread" -eq 0 ] && [ "$red_visitor" -eq 0 ]; then
+		return 0
+	fi
+	return 1
+}
+
+TENANT_LOADER="one.ie/web/src/lib/tenant/page-data.ts"
+TENANT_INDEX="one.ie/web/src/pages/u/[slug]/index.astro"
+TENANT_PAGE="one.ie/web/src/pages/u/[slug]/p/[pageSlug].astro"
+
+# THE CEILING, as three numbers. C8 pinned 3 dependency levels per tenant route,
+# counted TRANSITIVELY across the frontmatter and the loader module it delegates
+# to (leaf helpers count as one node each). await-bearing LINES are the
+# enforceable proxy: they cannot be relocated, because moving a hop out of a page
+# and into the loader raises the loader's count. Raising any of these three
+# numbers is a decision, not a fix.
+MAX_AWAIT_LINES_INDEX=5   # env import + invite early-return + the wave + bindings + rows (was 11)
+MAX_AWAIT_LINES_PAGE=5    # env import + the wave + the draft gate + bindings + rows (was 7)
+MAX_AWAIT_LINES_LOADER=4  # two Promise.all joins + the rare non-default home read
+
+# NOTE ON GREP, the trap this checker was written around: never
+# `<producer> | grep -q PAT` under `set -o pipefail` — a MATCH kills the producer
+# with SIGPIPE and the pipeline reports 141, which reads as a false RED (or, under
+# a `!`, a false GREEN). Every check below is `grep -c ... FILE || true` captured
+# into a variable and compared numerically. No pipes anywhere.
+
+check_tenant_loader() {
+	local file="$1"
+	if [ ! -f "$file" ]; then
+		echo "[speed-waterfall-check] missing $file" >&2
+		return 2
+	fi
+	local home_join page_join awaits
+	home_join=$(grep -c 'await Promise.all(\[ctxP, settingsP, brainAgentP, authzP, homeRowDefaultP\])' "$file" || true)
+	page_join=$(grep -c 'await Promise.all(\[rowP, expRowP, canEditP\])' "$file" || true)
+	awaits=$(grep -c 'await ' "$file" || true)
+	if [ "$home_join" -ge 1 ] && [ "$page_join" -ge 1 ] && [ "$awaits" -le "$MAX_AWAIT_LINES_LOADER" ]; then
+		return 0
+	fi
+	return 1
+}
+
+check_tenant_index() {
+	local file="$1"
+	if [ ! -f "$file" ]; then
+		echo "[speed-waterfall-check] missing $file" >&2
+		return 2
+	fi
+	local green red_ctx red_setting red_agent red_authz awaits
+	green=$(grep -c 'await loadWorkspaceHomeData(' "$file" || true)
+	# RED shapes: the four helpers this page used to await one hop at a time.
+	red_ctx=$(grep -c 'await getSlugContext(' "$file" || true)
+	red_setting=$(grep -c 'await readWorkspaceSetting' "$file" || true)
+	red_agent=$(grep -c 'await loadAgent(' "$file" || true)
+	red_authz=$(grep -c 'await authorizeWorkspace(' "$file" || true)
+	awaits=$(grep -c 'await ' "$file" || true)
+	if [ "$green" -ge 1 ] && [ "$red_ctx" -eq 0 ] && [ "$red_setting" -eq 0 ] \
+		&& [ "$red_agent" -eq 0 ] && [ "$red_authz" -eq 0 ] \
+		&& [ "$awaits" -le "$MAX_AWAIT_LINES_INDEX" ]; then
+		return 0
+	fi
+	return 1
+}
+
+check_tenant_page() {
+	local file="$1"
+	if [ ! -f "$file" ]; then
+		echo "[speed-waterfall-check] missing $file" >&2
+		return 2
+	fi
+	local green red_exp authz awaits
+	green=$(grep -c 'await loadTenantPageData(' "$file" || true)
+	red_exp=$(grep -c 'const expRow = await env.DB' "$file" || true)
+	# EXACTLY ONE: the draft-preview gate is the declared security exception.
+	# Zero means the gate was deleted; two means the owner-edit walk crept back.
+	authz=$(grep -c 'await authorizeWorkspace(' "$file" || true)
+	awaits=$(grep -c 'await ' "$file" || true)
+	if [ "$green" -ge 1 ] && [ "$red_exp" -eq 0 ] && [ "$authz" -eq 1 ] \
+		&& [ "$awaits" -le "$MAX_AWAIT_LINES_PAGE" ]; then
+		return 0
+	fi
+	return 1
+}
+
+CHECK_GATE=0
+MODE=""
+for arg in "$@"; do
+	case "$arg" in
+	--chat) MODE="chat" ;;
+	--tenant) MODE="tenant" ;;
+	--check-gate) CHECK_GATE=1 ;;
+	*)
+		echo "[speed-waterfall-check] unknown flag: $arg" >&2
+		exit 2
+		;;
+	esac
+done
+
+if [ "$CHECK_GATE" -eq 1 ]; then
+	echo "speed-waterfall-check --check-gate — proving the --chat structural check bites"
+	echo
+
+	TMP="$(mktemp -d)"
+	trap 'rm -rf "$TMP"' EXIT
+
+	RED_FILE="$TMP/chat-red.ts"
+	cat >"$RED_FILE" <<'EOF'
+const publishedPage: PublishedPage | null =
+  env.DB && pageUrl
+    ? await loadPublishedPage(env as { DB?: D1Database }, pageUrl, locals.workspaceContext?.workspace as string | undefined).catch(() => null)
+    : null
+let claimedThread: ClaimedThread | null = null
+if (env.DB && typeof body.thread === 'string' && body.thread) {
+  const t = await getThread(env.DB, body.thread)
+  if (t) claimedThread = { id: t.id, slug: t.slug, user_cookie: t.userCookie }
+}
+const convoIdentity: ConversationIdentity = {
+  cookieId: convoCookieId,
+  visitorHash: attestedVisitorHash ?? (convoCookieId ? await visitorHash(convoCookieId, env.WS_SALT ?? '') : null),
+  signedInActorId: (locals.slug as string | undefined) ?? null,
+}
+EOF
+
+	bad=0
+	if check_chat "$RED_FILE"; then
+		echo "  FAIL the pre-fix serial shape was NOT flagged (got pass, want fail)"
+		bad=1
+	else
+		echo "  ok   the pre-fix serial shape is flagged RED (got fail, want fail)"
+	fi
+
+	if check_chat "$CHAT_TS"; then
+		echo "  ok   the working tree's chat.ts is GREEN (got pass, want pass)"
+	else
+		echo "  FAIL the working tree's chat.ts did NOT pass (got fail, want pass)"
+		bad=1
+	fi
+
+	echo
+	echo "…and that the --tenant structural check bites"
+	echo
+
+	# PLANTED FIXTURES, never the live files. Mutating u/[slug]/index.astro and
+	# restoring it would leave a corrupted page behind any interrupted run, and is
+	# unsafe under a parallel batch. roles-check.sh --check-decide is the shape.
+	RED_LOADER="$TMP/page-data-red.ts"
+	cat >"$RED_LOADER" <<'EOF'
+// The pre-C8 shape, relocated into a helper: each leg still gated on the one
+// before it. A checker that only counted `Promise.all` in the pages would score
+// this GREEN — which is the whole reason the loader carries its own ceiling.
+export async function loadWorkspaceHomeData(args) {
+  const ctx = await getSlugContext(args.slug, args.env.DB, args.env.CONTENT)
+  const settings = await readWorkspaceSettings(args.env.DB, args.slug, ['home-page'])
+  const brainAgent = await loadAgent(`${args.slug}--brain`, args.slug, args.env)
+  const authorized = await authorize(args.locals, args.slug, args.env.DB, args.env)
+  const homeRow = await args.env.DB.prepare(SQL).bind(args.slug).first()
+  return { ctx, settings, brainAgent, authorized, homeRow }
+}
+export async function loadTenantPageData(args) {
+  const row = await args.env.DB.prepare(SQL).bind(args.pageSlug, args.slug).first()
+  const expRow = await args.env.DB.prepare(SQL2).bind(args.pageSlug, args.slug).first()
+  const canEdit = await authorize(args.locals, args.slug, args.env.DB, args.env)
+  return { row, expRow, canEdit }
+}
+EOF
+
+	RED_INDEX="$TMP/index-red.astro"
+	cat >"$RED_INDEX" <<'EOF'
+const ctx = await getSlugContext(slug, env.DB, env.CONTENT).catch(() => null)
+const homePageSetting = await readWorkspaceSetting(env.DB, slug, 'home-page')
+const homeRow = await env.DB.prepare(SQL).bind(slug, homePageSlug, 'published').first()
+const canEditHome = homeRow && Astro.locals.slug
+  ? (await authorizeWorkspace(Astro.locals, homeRow.workspace, env.DB, env)).ok
+  : false
+const brainAgent = await loadAgent(`${slug}--brain`, slug, { CONTENT: env.CONTENT })
+const widget = await readWorkspaceSetting(env.DB, slug, 'chat-widget')
+EOF
+
+	RED_PAGE="$TMP/pageslug-red.astro"
+	cat >"$RED_PAGE" <<'EOF'
+const row = await env.DB.prepare(SQL).bind(pageSlug, slug).first()
+const canEdit = Astro.locals.slug
+  ? (await authorizeWorkspace(Astro.locals, row.workspace, env.DB, env)).ok
+  : false
+const expRow = await env.DB
+  .prepare(SQL2)
+  .bind(pageSlug, slug)
+  .first()
+EOF
+
+	if check_tenant_loader "$RED_LOADER"; then
+		echo "  FAIL a serial LOADER was NOT flagged (got pass, want fail)"
+		bad=1
+	else
+		echo "  ok   a serial loader is flagged RED — relocating hops into a helper does not pass"
+	fi
+
+	if check_tenant_index "$RED_INDEX"; then
+		echo "  FAIL the pre-C8 index.astro shape was NOT flagged (got pass, want fail)"
+		bad=1
+	else
+		echo "  ok   the pre-C8 index.astro serial ladder is flagged RED"
+	fi
+
+	if check_tenant_page "$RED_PAGE"; then
+		echo "  FAIL the pre-C8 [pageSlug].astro shape was NOT flagged (got pass, want fail)"
+		bad=1
+	else
+		echo "  ok   the pre-C8 [pageSlug].astro serial shape is flagged RED"
+	fi
+
+	if check_tenant_loader "$TENANT_LOADER"; then
+		echo "  ok   the working tree's loader is GREEN (got pass, want pass)"
+	else
+		echo "  FAIL the working tree's loader did NOT pass (got fail, want pass)"
+		bad=1
+	fi
+
+	if check_tenant_index "$TENANT_INDEX"; then
+		echo "  ok   the working tree's index.astro is GREEN (got pass, want pass)"
+	else
+		echo "  FAIL the working tree's index.astro did NOT pass (got fail, want pass)"
+		bad=1
+	fi
+
+	if check_tenant_page "$TENANT_PAGE"; then
+		echo "  ok   the working tree's [pageSlug].astro is GREEN (got pass, want pass)"
+	else
+		echo "  FAIL the working tree's [pageSlug].astro did NOT pass (got fail, want pass)"
+		bad=1
+	fi
+
+	if [ "$bad" -eq 0 ]; then
+		echo
+		echo "waterfall gate proven: it fails on the serial shape and passes on the fan-out"
+		exit 0
+	fi
+	echo
+	echo "$bad self-test(s) FAILED — the waterfall gate is not trustworthy"
+	exit 1
+fi
+
+case "$MODE" in
+chat)
+	if check_chat "$CHAT_TS"; then
+		echo "[speed-waterfall-check --chat] ok — loadPublishedPage/getThread/visitorHash fire concurrently, joined before deriveConversationKey"
+		exit 0
+	fi
+	echo "[speed-waterfall-check --chat] FAIL — the pre-flight ladder in $CHAT_TS is serial again" >&2
+	exit 1
+	;;
+tenant)
+	tbad=0
+	if check_tenant_loader "$TENANT_LOADER"; then
+		echo "[speed-waterfall-check --tenant] ok — $TENANT_LOADER fans out both waves and stays within $MAX_AWAIT_LINES_LOADER await lines"
+	else
+		echo "[speed-waterfall-check --tenant] FAIL — $TENANT_LOADER is serial again, missing, or exceeds $MAX_AWAIT_LINES_LOADER await lines" >&2
+		tbad=1
+	fi
+	if check_tenant_index "$TENANT_INDEX"; then
+		echo "[speed-waterfall-check --tenant] ok — $TENANT_INDEX delegates its data wave and stays within $MAX_AWAIT_LINES_INDEX await lines"
+	else
+		echo "[speed-waterfall-check --tenant] FAIL — $TENANT_INDEX awaits a helper serially again, or exceeds $MAX_AWAIT_LINES_INDEX await lines" >&2
+		tbad=1
+	fi
+	if check_tenant_page "$TENANT_PAGE"; then
+		echo "[speed-waterfall-check --tenant] ok — $TENANT_PAGE delegates its data wave, keeps exactly one (draft-gate) authz call, and stays within $MAX_AWAIT_LINES_PAGE await lines"
+	else
+		echo "[speed-waterfall-check --tenant] FAIL — $TENANT_PAGE is serial again, lost or doubled its authz gate, or exceeds $MAX_AWAIT_LINES_PAGE await lines" >&2
+		tbad=1
+	fi
+	if [ "$tbad" -eq 0 ]; then
+		echo "[speed-waterfall-check --tenant] ok — 3 dependency levels per route, counted across frontmatter AND loader"
+		exit 0
+	fi
+	exit 1
+	;;
+*)
+	echo "usage: speed-waterfall-check.sh --chat|--tenant [--check-gate]" >&2
+	exit 2
+	;;
+esac

package/scripts/substrate-env-parity.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// substrate-env-parity.mjs — the gate that keeps the test suite off production.
+//
+// WHY THIS EXISTS
+//
+// `substrate.ts` resolves its origin as `env.GATEWAY_URL ?? DEFAULT_GATEWAY`,
+// and DEFAULT_GATEWAY is https://api.one.ie. So a test that builds its env as
+//
+//     const env = { GATEWAY_API_KEY } as Env        // no GATEWAY_URL
+//
+// is not "unconfigured" — it is PINNED TO PRODUCTION, in the source, where no
+// environment variable can reach it. `tests/_env-file.ts` deliberately refuses
+// to import GATEWAY_URL (its rule 2, so one developer's localhost cannot redden
+// the deploy gate), which means the shell cannot rescue these files either.
+//
+// Measured 2026-09-01: 31 such files. They were making 440ms round-trips to the
+// live cluster on every run — one file spent 12.6s on a single test — and they
+// were WRITING fixtures into the production graph (9 orphaned `pcw-*` actors
+// were found there, left by an afterAll whose cleanup ends in `.catch(() => {})`).
+// Pointing one of them at a local substrate took it from 10,828ms to 197ms (55x)
+// with all six assertions still green.
+//
+// A file that passes `GATEWAY_URL: process.env['GATEWAY_URL']` still defaults to
+// production when the variable is unset, so this gate costs the deploy lane
+// nothing and changes no behaviour there. It only makes the local substrate
+// REACHABLE, which today it is not.
+//
+// THE RATCHET. The baseline is a count that may only ever go DOWN. `--update`
+// refuses to record a regression, exactly as speed-check.mjs's does. That is
+// what makes this lock speed in rather than merely observe it: fixing files is
+// optional and incremental, adding a 32nd offender is not possible.
+//
+//   substrate-env-parity.mjs              # check against the baseline
+//   substrate-env-parity.mjs --list       # name every offender
+//   substrate-env-parity.mjs --update     # lower the baseline (never raise)
+//   substrate-env-parity.mjs --check-gate # SELF-TEST: prove it can go red
+//
+// EXIT  0 pass · 1 REGRESSION · 2 INCONCLUSIVE (could not measure — never 0)
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..', '..')
+const TESTS = join(REPO, 'one.ie', 'web', 'tests')
+const BASELINE = join(REPO, 'text', 'substrate-env-parity.json')
+
+const has = (f) => process.argv.includes(f)
+
+// An env OBJECT LITERAL carrying the credential is a substrate env being built.
+// A bare `process.env.GATEWAY_API_KEY` skipIf guard is NOT one, and flagging it
+// would be a false positive on ~20 files that never touch the substrate at all.
+const ENV_LITERAL = /\{[^{}]*\bGATEWAY_API_KEY\b[^{}]*\}/
+
+/** @returns {{offenders: string[], constructing: number}} */
+export function scan(root) {
+  const offenders = []
+  let constructing = 0
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) { walk(p); continue }
+      if (!/\.test\.tsx?$/.test(name)) continue
+      const src = readFileSync(p, 'utf8')
+      if (!ENV_LITERAL.test(src)) continue
+      constructing++
+      if (!src.includes('GATEWAY_URL')) offenders.push(relative(REPO, p))
+    }
+  }
+  walk(root)
+  return { offenders: offenders.sort(), constructing }
+}
+
+// ── self-test: a checker never observed failing is not evidence ──────────────
+if (has('--check-gate')) {
+  const { mkdtempSync, mkdirSync, rmSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const tmp = mkdtempSync(join(tmpdir(), 'sep-gate-'))
+  let bad = 0
+  const say = (ok, msg) => { console.log(`${ok ? '  ok  ' : '  FAIL'} ${msg}`); if (!ok) bad++ }
+  console.log('substrate-env-parity --check-gate — proving the ratchet bites\n')
+  try {
+    mkdirSync(join(tmp, 'nested'), { recursive: true })
+    // The offending shape, verbatim from tests/unit/tasks-depend-cycle.test.ts.
+    writeFileSync(join(tmp, 'bad.test.ts'), 'const env = { GATEWAY_API_KEY } as Env\n')
+    // The fixed shape.
+    writeFileSync(join(tmp, 'nested', 'good.test.ts'),
+      "const env = { GATEWAY_API_KEY, GATEWAY_URL: process.env['GATEWAY_URL'] } as Env\n")
+    // A skipIf guard — must NOT be flagged, or the gate cries wolf on ~20 files.
+    writeFileSync(join(tmp, 'guard.test.ts'),
+      'describe.skipIf(!process.env.GATEWAY_API_KEY)("x", () => {})\n')
+    // A file with no substrate use at all.
+    writeFileSync(join(tmp, 'plain.test.ts'), 'expect(1).toBe(1)\n')
+
+    const r = scan(tmp)
+    const names = r.offenders.map((o) => o.split('/').pop())
+    say(names.includes('bad.test.ts'), 'flags an env literal missing GATEWAY_URL (RED)')
+    say(!names.includes('good.test.ts'), 'passes an env literal that forwards GATEWAY_URL (GREEN)')
+    say(!names.includes('guard.test.ts'), 'does NOT flag a bare skipIf guard (no false positive)')
+    say(r.constructing === 2, `counts only env-constructing files (got ${r.constructing}, want 2)`)
+    say(names.length === 1, `exactly one offender in the fixture (got ${names.length})`)
+
+    // The ratchet direction: --update must refuse to RAISE a baseline.
+    const bl = join(tmp, 'bl.json')
+    writeFileSync(bl, JSON.stringify({ offenders: 0 }))
+    const cur = JSON.parse(readFileSync(bl, 'utf8')).offenders
+    say(!(1 <= cur), 'a baseline of 0 rejects a tree with 1 offender (ratchet holds)')
+  } finally { rmSync(tmp, { recursive: true, force: true }) }
+  console.log(bad === 0 ? '\ngate proven\n' : `\n${bad} FAIL\n`)
+  process.exit(bad === 0 ? 0 : 1)
+}
+
+if (!existsSync(TESTS)) {
+  console.error(`INCONCLUSIVE: no test tree at ${TESTS}`)
+  process.exit(2)
+}
+
+const { offenders, constructing } = scan(TESTS)
+
+if (has('--list')) {
+  for (const o of offenders) console.log(o)
+  process.exit(0)
+}
+
+if (!existsSync(BASELINE)) {
+  console.error(`INCONCLUSIVE: no baseline at ${BASELINE} — run --update to create it`)
+  if (!has('--update')) process.exit(2)
+}
+
+const prev = existsSync(BASELINE) ? JSON.parse(readFileSync(BASELINE, 'utf8')) : { offenders: Infinity }
+
+if (has('--update')) {
+  if (offenders.length > prev.offenders) {
+    console.error(`REFUSED: ${offenders.length} offenders > baseline ${prev.offenders}. The ratchet only moves down.`)
+    process.exit(1)
+  }
+  writeFileSync(BASELINE, `${JSON.stringify({
+    _why: 'Test files that build a substrate env WITHOUT GATEWAY_URL are pinned to https://api.one.ie by substrate.ts:31. This count may only go DOWN.',
+    _measured: new Date().toISOString().slice(0, 10),
+    offenders: offenders.length,
+    constructing,
+    files: offenders,
+  }, null, 2)}\n`)
+  console.log(`baseline updated: ${prev.offenders} -> ${offenders.length}`)
+  process.exit(0)
+}
+
+if (offenders.length > prev.offenders) {
+  console.error(`REGRESSION: ${offenders.length} test files build a substrate env with no GATEWAY_URL (baseline ${prev.offenders}).`)
+  const added = offenders.filter((o) => !(prev.files ?? []).includes(o))
+  for (const a of added) console.error(`  + ${a}  <- pinned to production; add  GATEWAY_URL: process.env['GATEWAY_URL']`)
+  process.exit(1)
+}
+
+console.log(`substrate-env-parity: ${offenders.length} offender(s), baseline ${prev.offenders} — ok`)
+process.exit(0)

package/scripts/tasks-claim-race.mjs

@@ -0,0 +1,108 @@
+// tasks-claim-race.mjs — the atomicity proof for tasks:claim. BOTH halves.
+//
+// Answers, empirically, the one question the whole task-loop design rests on:
+// does TypeDB refuse the second of two concurrent guarded claims?
+//
+// Requires a REAL TypeDB (never mock it — repo rule). Default target is a
+// throwaway `racetest` database on a LOCAL server; it never touches `one`.
+//
+//   docker run -d --name one-tdb-probe -p 8000:8000 typedb/typedb:3.12.1
+//   node .claude/scripts/tasks-claim-race.mjs
+//
+// Exit 0 only when BOTH halves hold:
+//   GREEN — the guarded single-pipeline claim: 1 winner, 1 refusal, 1 `@` tag.
+//   RED   — the old read-then-decide shape: 2 winners, 2 `@` tags (the bug).
+// A checker that cannot demonstrate its own red half is not a checker.
+const BASE = process.env.TYPEDB_URL || 'http://127.0.0.1:8000'
+const DB = process.env.RACE_DB || 'racetest'
+const USER = process.env.TYPEDB_USERNAME || 'admin'
+const PASS = process.env.TYPEDB_PASSWORD || 'password'
+const RUNS = Number(process.env.RACE_RUNS || 5)
+if (!/127\.0\.0\.1|localhost/.test(BASE)) {
+  console.error(`REFUSING: ${BASE} is not local. This harness races WRITES; point it at a throwaway server.`)
+  process.exit(2)
+}
+let TOKEN = ''
+const api = (p, init) => fetch(`${BASE}/v1${p}`, init)
+async function q(query, tt = 'read') {
+  const r = await api('/query', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${TOKEN}` },
+    body: JSON.stringify({ query, databaseName: DB, transactionType: tt, commit: tt !== 'read' }),
+  })
+  let body
+  try { body = await r.json() } catch { body = {} }
+  return { status: r.status, rows: body.answers ?? [], code: body.code, message: body.message }
+}
+const tags = async (tid) =>
+  (await q(`match $t isa thing, has tid "${tid}", has tag $g; select $g;`)).rows
+    .map((a) => a.data?.g?.value).filter(Boolean).sort()
+
+async function main() {
+  TOKEN = (await (await api('/signin', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ username: USER, password: PASS }),
+  })).json()).token
+  if (!TOKEN) throw new Error('signin failed')
+  await api(`/databases/${DB}`, { method: 'DELETE', headers: { Authorization: `Bearer ${TOKEN}` } })
+  await api(`/databases/${DB}`, { method: 'POST', headers: { Authorization: `Bearer ${TOKEN}` } })
+  // Same cardinalities as schema/one.tql: tid @key, tag @card(0..),
+  // task-status and updated-at-ms single-valued.
+  await q(`define entity thing, owns tid @key, owns task-status @card(0..1), owns tag @card(0..), owns updated-at-ms @card(0..1);
+    attribute tid value string; attribute task-status value string;
+    attribute tag value string; attribute updated-at-ms value integer;`, 'schema')
+
+  const reset = async (tid) => {
+    await q(`match $t isa thing, has tid "${tid}"; delete $t;`, 'write')
+    await q(`insert $t isa thing, has tid "${tid}", has task-status "open", has updated-at-ms 1;`, 'write')
+  }
+  // The SHIPPED shape — one transaction, guard in the match, tag in the insert.
+  const guarded = (tid, who) =>
+    q(`match $t isa thing, has tid "${tid}", has task-status $s; $s == "open"; delete $s of $t;` +
+      ` insert $t has task-status "picked", has tag "@${who}";` +
+      ` update $t has updated-at-ms ${Date.now()}; select $t;`, 'write')
+
+  let fail = 0
+  // ── half 1: zero-match must be observable, not a silent success ──────────
+  await reset('obs')
+  const hit = await guarded('obs', 'alice')
+  const miss = await guarded('obs', 'bob')
+  const observable = hit.status === 200 && hit.rows.length === 1 && miss.status === 200 && miss.rows.length === 0
+  console.log(`[observable] match rows=${hit.rows.length} (${hit.status}) · no-match rows=${miss.rows.length} (${miss.status}) -> ${observable ? 'OK' : 'FAIL'}`)
+  if (!observable) fail++
+
+  // ── half 2: GREEN — concurrent guarded claims ────────────────────────────
+  for (let i = 0; i < RUNS; i++) {
+    const tid = `g${i}`
+    await reset(tid)
+    const [a, b] = await Promise.all([guarded(tid, 'alice'), guarded(tid, 'bob')])
+    const winners = [a, b].filter((r) => r.status === 200 && r.rows.length === 1).length
+    const t = await tags(tid)
+    const loser = [a, b].find((r) => r.status !== 200)
+    const ok = winners === 1 && t.length === 1
+    console.log(`[green run${i}] winners=${winners} tags=${JSON.stringify(t)} loser=${loser ? `${loser.status} ${loser.code}` : 'none'} -> ${ok ? 'OK' : 'FAIL'}`)
+    if (loser?.message) console.log(`            "${loser.message.split('\n')[0]}"`)
+    if (!ok) fail++
+  }
+
+  // ── half 3: RED — the old read-then-decide shape must still double-claim ─
+  const legacy = async (tid, who) => {
+    const rd = await q(`match $t isa thing, has tid "${tid}", has task-status $s; try { $t has tag $g; }; select $s, $g;`)
+    const blob = JSON.stringify(rd.rows)
+    const other = blob.match(/"@(\w+)"/)
+    if (blob.includes('"picked"') && other && other[1] !== who) return { error: 'already-claimed' }
+    await q(`match $t isa thing, has tid "${tid}", has task-status $s; delete $s of $t; insert $t has task-status "picked";`, 'write')
+    await q(`match $t isa thing, has tid "${tid}"; insert $t has tag "@${who}";`, 'write')
+    return { ok: true, claimant: who }
+  }
+  await reset('red')
+  const [l1, l2] = await Promise.all([legacy('red', 'alice'), legacy('red', 'bob')])
+  const redTags = await tags('red')
+  const redProven = !!l1.ok && !!l2.ok && redTags.length === 2
+  console.log(`[red] legacy shape: both-ok=${!!l1.ok && !!l2.ok} tags=${JSON.stringify(redTags)} -> ${redProven ? 'RED PROVEN' : 'FAIL (checker cannot go red)'}`)
+  if (!redProven) fail++
+
+  console.log(fail === 0 ? '\nPASS — guarded claim is atomic; the checker proved its own red half.' : `\nFAIL — ${fail} check(s) failed.`)
+  process.exit(fail === 0 ? 0 : 1)
+}
+main().catch((e) => { console.error('harness error:', e.message); process.exit(2) })